get_thread_by_unread

Function

Function Name	Description	Level
get_thread_by_unread	This function provides a mean to allow users to jump to the "First Unread" post within a thread he has previously participated. Please note that this function is used in conjunction with "goto_unread" in get_config function. If "goto_unread" is returned and is = "1", get_thread_by_unread is always called instead of get_thread function. Please be noted that this function is not invoked when under Guest mode.	4

Input Parameters:

Name	Type	Required?	Description	Level
topic_id	String	yes	Topic ID of the thread.	4
posts_per_request	Int		The ability to jump to "First Unread" depends on two core actions, one is the ability to load the right "page" and one is the ability to scroll to the right post. This parameter covers the first part that it instructs the plugin to return the right page that contains the first unread post. Please note that this parameter is optional, the plugin assumes this as "20" if missing.	4
return_html	Boolean		Return post content with basic bbcode tags supported. Currently it can return <i>, <u>, <b>. Also if this is set to true, the returned post_content need to convert '&' to '&', '<' to '<', '>' to '>' and '\n' to '<br />'. This extra parameter is used in conjunction with "disable_html" flag in get_config. If "disable_html=0" or is missing, this parameter should be set to false. Otherwise if disable_html is "1", this paramter should be set to true, or simply not using this parameter at all.	4

Output Parameters:

Name	Type	Required?	Description	Level
	Array of Hash table		The output structure is exactly the same as get_thread function. Except an additional "position" key is returned to help the app to scroll to the right post.
position	Int	yes	This value is to indicate the current first unread post position relative to the entire thread, starting from "1" to indicate first post, thereafter. For example if a thread contains 83 posts and "position" is "65", it means the first unread post is at the #65 post. The app can use this key, divided by "posts_per_request" to determine the "page number" the app should jump to, and then use this key to "%" posts_per_request to determine the exact postion of the first unread post within the page. For example, if position is "65", and posts_per_request is "20", the app should scroll to the page 3 and the 5th post automatically.	4