Technical Description Relating to View or Mark Unread Posts Mod

In this page, I give technical information about how phpbb3 tracks unread posts and how the
view or mark unread posts mod allows users to mark read posts as unread.
Note: you do NOT need this page to install the mod.

1.	Summary of the database entries phpbb3 makes to track unread posts via the database

	a.	clicking "mark forums read" link on index page:

		-	sets user_lastmark for the user in the users table to the current time 

		-	wipes out all entries for the user in the forums_track table

		-	wipes out all entries for the user in the topics_track table

	b.	clicking "mark topics read" link on viewforum page for a forum:

		- 	sets mark_time for the user and that forum
			in the forums_track table to the current time 

		- 	wipes out all entries for the user and that forum
			in the topics_track table

	c.	opening up existing topic that is already read

		- 	does nothing

	d.	opening up an existing topic that is unread:

		-	via the markread() function, sets mark_time for the user and that topic
			in the topics_track table to the post_time for the last post of the last page
			in the topic that the user read

		-	if there are no other unread topics in the relevant forum,
			then via the update_forum_tracking_info() function:

			-	sets mark_time for the user and that forum
				in the forums_track table to the post_time for the last post
				in the relevant forum

			-	wipes out all entries for the user and the relevant forum
				in the topics_track table

	e.	new topic or reply to existing topic:

		-	via the markread() function, sets mark_time for the user and that topic
			in the topics_track table to the post_time for the new topic or reply

		-	if there are no other unread topics in the relevant forum,
			then via the update_forum_tracking_info() function:
		
			-	sets mark_time for the user and the relevant forum
				in the forums_track table to the post_time for
				the last post in the relevant forum

			-	wipes out all entries for the user and the relevant forum
				in the topics_track table

2.	Summary of how phpbb3 uses those database entries to determine whether forums, topics or posts are unread

	When a user is on the index page, phpbb3 determines whether a forum is unread
	by checking to see whether the forum_last_post_time for the forum is greater (i.e. later) than
	the mark_time entry for the user and the forum in the forums_track table.
	If there is no entry for the user and the forum in the forums_track table, phpbb3 instead
	checks to see if forum_last_post_time for the forum is greater (i.e. later) than the
	user_lastmark entry for the user in the users table.
	If forum_last_post_time for the forum is greater than the applicable mark_time or user_lastmark entry,
	the forum is considered unread.	 The code for all this checking is in the display_forums() function that
	appears in includes/functions_display.php.
	
	When a user is on viewforum, phpbb3 determines whether a topic is unread
	by checking to see whether the topic_last_post_time for the topic is greater (i.e. later) than
	the mark_time entry for the user and the topic in the topics_track table.
	If there is no entry for the user and the topic in the topics_track table, phpbb3 instead
	checks to see if topic_last_post_time for the topic is greater (i.e. later) than the
	mark_time entry for the user and the relevant forum in the forums_track table.
	And if there is no entry for the user and the relevant forum in the forums_track table, phpbb3 instead
	checks to see if topic_last_post_time for the topic is greater (i.e. later) than the
	user_lastmark entry for the user in the users table.
	If topic_last_post_time for the topic is greater than the applicable mark_time or user_lastmark entry,
	the topic is considered unread.	 The code for all this checking is in the get_topic_tracking()
	function that appears in includes/functions.php.
	(Note: viewforum separately uses the display_forums() function to determine whether subforums underneath
	the current forum have unread posts.)
	
	When a user is on viewtopic, phpbb3 determines whether a post is unread
	by checking to see whether its post_time is greater (i.e. later) than
	the mark_time entry for the user and the relevant topic in the topics_track table.
	If there is no entry for the user and the relevant topic in the topics_track table, phpbb3 instead
	checks to see if the post_time is greater (i.e. later) than the
	mark_time entry for the user and the relevant forum in the forums_track table.
	And if there is no entry for the user and the relevant forum in the forums_track table, phpbb3 instead
	checks to see if the post_time is greater (i.e. later) than the
	user_lastmark entry for the user in the users table.
	If the post_time for the post is greater than the applicable mark_time or user_lastmark entry,
	the post is considered unread.	 The code for all this checking is in the get_topic_tracking()
	function (or in some cases the get_complete_topic_tracking() function) that appears in includes/functions.php.
	
3.	Summary of how phpbb3 compiles a list of unread topics when a user clicks the link to view unread topics

	When a user clicks the link to view unread topics, search.php calls get_unread_topics() that appears
	in includes/functions.php.  get_unread_topics() looks for every topic where the topic_last_post_time
	is greater than the mark_time entry for the user and the topic in the topics track table or, if there is no
	such mark_time, the mark_time entry for the user and the relevant forum in the forums track table or, if
	there is no such mark_time, the	user_lastmark entry for the user in the users table.  phpbb3 sorts the list
	by topic_last_post_time in descending order and by default limits the list to 1000 topics.

4.	Summary of how the view or mark unread posts mod determines whether there are any unread posts

	The view or mark unread posts mod uses the same efficient approach as the function display_forums() uses
	to determine if there are any forums with unread topics (see first paragraph under (2) above).
	It then toggles the text for the link to unread posts between 'View unread posts'
	(if there are any unread forums or global announcements) and 'You have no unread posts' (if there are not).
	The code for checking for unreads is in the	check_unread_posts() function that appears in
	includes/functions_view_or_mark_unread_posts.php.  Note that in order to save a query, the code skips
	the check if the user is on the index page and phpbb3 has already done the checking.

5.	Summary of how the view or mark unread posts mod allows users to mark posts as unread

	The most difficult part of the view or mark unread posts mod is the code that allows users
	to mark posts as unread.  That code is in the mark_post_unread() function that appears in
	includes/functions_view_or_mark_unread_posts.php.
	That code does the following when a user clicks to mark a post unread:
	
	a.	sets mark_time for the user and the relevant topic in the topics_track table
		to the post_time of the post minus 1 (so that phpbb3 will think the post is unread)
	
	b.	sets a variable called "$forum_tracking_info" to equal the mark_time entry for the user
		and relevant forum in the forum_tracks table; if there is no such entry, sets
		$forum_tracking_info to be the user_lastmark entry for the user in the users table
	
	c.	if the post_time of the post is smaller (earlier) than $forum_tracking_info, then:

		-	sets mark_time for the user and the relevant forum in the forums_track table
			to the post_time for the post minus 1 (so that phpbb3 will think the forum is unread)
		
		-	but before doing that, adds a new topics_track entry
			(with mark_time = forum_tracking_info) for each other topic in the forum or in forum_id 0
			that meets all of the following tests

			-	does not already have a topics_track entry for the user and forum

			-	has a topic_last_post_time less than or equal to the then current forum_tracking_info
				(which shows that it has already been read)

			-	has a last post time greater than the new mark_time that will be used for the forums_track table

			The purpose of adding these new topics_track entries is to make sure that phpbb3
			will continue to treat already read topics as already read rather than incorrectly
			thinking they are unread because their topic_last_post_time is after the new
			mark_time for the relevant forum