Post

Post

This section provides necessary functions related to thread retrieval, post creation, post editing and post quoting.

report_post

Function:

Function Name	Description	Level
report_post	report a problematic post to moderator. This should be used in conjunction with "report_post" flag in "get_config".

Input Parameters:

Name	Type	Required?	Description	Level
post_id	String	yes
reason	byte[]		optional. Allow user to add a message to describe the problem.

Output Parameters:

Name	Type	Required?	Description	Level
result	Boolean	yes	Return "true" if the action is executed successfully. "false" otherwise.
result_text	byte[]		Message to be displayed to user after this action is executed. Optional.

reply_post

Function:

Function Name	Description	Level
reply_post	reply to an existing topic	3,4

Input Parameters:

Name	Type	Required?	Description	Level
forum_id	String	yes		3
topic_id	String	yes		3
subject	byte[]			3
text_body	byte[]	yes		3
attachment_id_array	Array of String		List of attachment ID that come along with this topic creation. Please check upload.
group_id	String		required when attachment_id_array is specified
return_html	Boolean		Only support this parameter when get_config return flag no_refresh_on_post as 1	4

Output Parameters:

Name	Type	Required?	Description	Level
result	Boolean	yes	return true if the action is executed successfully.	3
result_text	byte[]			3
post_id	String	yes	the newly generated post ID for this new topic.	3
state	Int		1 = post is success but need moderation. Otherwise no need to return this key. If this is return. The app should not refresh the thread view as the post will not be appear, instead it should display an alert to user about this post is pending for moderation.	3
post_content	byte[]		Return the newly replied post content and all below keys back to the App if get_config return support no_refresh_on_post. Characters display rules (follow the sequence): 1) Remove all BBCode except [ur], [img], [quote]. 2) Remove all non-displayable characters (e.g. \n, \t, white-space, etc) at the beginning AND the end of the content (Trimming) 3) Replace [url] tags in nested [url][img][/img][/url] image link.	4
can_edit	Boolean		return true if user can edit this post.	4
can_delete	Boolean		return true if user can delete this post.	4
timestamp	String		Timestamp of topic last reply
post_time	Date		dateTime.iso8601 format. If this topic has no reply, use the topic creation time.	4
attachments	Array of Hash table		Returns a list of attachments user has uploaded within this post, in array of hash format.	4
content_type	String		return "image", "pdf" or "other"	4
thumbnail_url	String		if content type = "image"), use absolute path (optional: if not presented, use "url" to load thumbnail instead)	4
url	String		URL of the attachment source.	4

get_quote_post

Function:

Function Name	Description	Level
get_quote_post	Returns a processed [quote] content just like when user click the "Quote" button on the web browser. This is to address different forum systems requires different [quote] format.	3

Input Parameters:

Name	Type	Required?	Description	Level
post_id	String	yes	Level 3: only accept one post_id. Level 4: accept multiple post_id with "-" separated, for multi-quote feature.	3,4

Output Parameters:

Name	Type	Required?	Description	Level
post_id	String	yes		3
post_title	byte[]	yes	Depends on the language or forum systems, the new title is generated with "Re: " or no title at all.	3
post_content	byte[]	yes	display full post content without removing any styles or characters. omitting the attachment information.	3

get_raw_post

Function:

Function Name	Description	Level
get_raw_post	This function allows app to retrive original content to display to user for post editing purpose.	3

Input Parameters:

Name	Type	Required?	Description	Level
post_id	String	yes		3

Output Parameters:

Name	Type	Required?	Description	Level
post_id	String	yes		3
post_title	byte[]	yes	Depends on the language or forum systems, the new title is generated with "Re: " or no title at all.	3
post_content	byte[]	yes	display full post content without removing any styles or characters. omitting the attachment information.	3
show_reason	Boolean		Indicate if the user can add edit reason
edit_reason	byte[]		Reason of last edit.
group_id	String		Attachment group id, used when editing post attachment.
attachments	Array of Hash table		Returns a list of attachments user has uploaded within this post. It will only be returned if get_config returned flag 'advanced_edit' in array of hash format.
attachment_id	String	yes	attachment id
filename	byte[]	yes	Attachment file name
content_type	String	yes	return "image", "pdf" or "other"
url	String	yes	URL of the attachment source.
thumbnail_url	String		if content type = "image"
filesize	Int		file size as byte

save_raw_post

Function:

Function Name	Description	Level
save_raw_post	This function allows app save post content to an existing post. Flag 'advanced_edit' will indicate if it support edit attachment.

Input Parameters:

Name	Type	Required?	Description	Level
post_id	String	yes		3
post_title	byte[]	yes		3
post_content	byte[]	yes		3
return_html	Boolean		Only support this parameter when get_config return flag no_refresh_on_post as 1	4
attachment_id_array	Array of String		List of attachment ID that come along with this topic creation. Please check interface upload.php Plugin will accept this parameter only when get_config return flag 'advanced_edit'
group_id	String		required when attachment_id_array is specified. Plugin will accept this parameter only when get_config return flag 'advanced_edit'
reason	byte[]		edit reason

Output Parameters:

Name	Type	Required?	Description	Level
result	Boolean	yes		3
result_text	byte[]			3
state	Int		1 = post is saved successfully but need moderation. Otherwise no need to return this key.	4
post_content	byte[]		Return the newly saved post content back to the App if get_config return support no_refresh_on_post. Characters display rules (follow the sequence): 1) Remove all BBCode except [ur], [img], [quote]. 2) Remove all non-displayable characters (e.g. \n, \t, white-space, etc) at the beginning AND the end of the content (Trimming) 3) Replace [url] tags in nested [url][img][/img][/url] image link.	4

get_thread

Function:

Function Name	Description	Level
get_thread	Returns a list of posts under the same thread, given a topic_id	3,4

Input Parameters:

Name	Type	Required?	Description	Level
topic_id	String	yes	Topic ID of the thread.	3
start_num	Int	yes	For pagination. If start_num = 0 & last_num = 9, it returns first 10 posts from the topic. If both are not presented, return first 20 posts. if start_num = 0 and last_num = 0, return the first post only, and so on (e.g. 1,1; 2,2). If start_num smaller than last_num returns null. If last_num - start_num > 50, returns only first 50 posts starting from start_num	3
last_num	Int	yes		3
return_html	Boolean			4

Output Parameters:

Name	Type	Required?	Description	Level
total_post_num	Int	yes	total number of posts in this topic	3
forum_id	String	yes		3
forum_name	byte[]	yes		3
topic_id	String	yes		3
topic_title	byte[]	yes		3
topic_author_id	String		Topic author ID
topic_author_name	byte[]		Topic author display name
topic_author_avatar	String		Topic author avatar
view_number	Int
prefix	byte[]			4
is_subscribed	Boolean		return true if this thread has been subscribed by this user.	3
can_subscribe	Boolean		returns false if the subscription feature is turned off	3
is_poll	Boolean		return ture if this topic contains poll
is_closed	Boolean		return true if this thread has been closed. If this thread is closed, it should not allow reply or edit unless can_reply (thread) or can_edit (post) are set to "true" explicitly	3
can_report	Boolean		return true if if user can report post in this thread
can_reply	Boolean		return false if user cannot reply to this thread.	3
breadcrumb	Array of Hash table		Forum nav to current thread, order from top forum to it's parent forum
forum_id	String
forum_name	byte[]
sub_only	Boolean
posts	Array of Hash table	yes	an array contains a list of posts in a thread.	3
post_id	String	yes		3
post_title	byte[]	yes	Remove all BBCode in title	3
post_content	byte[]	yes	Characters display rules (follow the sequence): 1) Remove all BBCode except [url], [img], [quote], [spoiler] 2) Remove all non-displayable characters (e.g. \n, \t, white-space, etc) at the beginning AND the end of the content (Trimming) 3) when 'return_html' was set as true, it will also return html tag <b>,<i>,<u>,<br />	3
post_author_id	String	yes		4
post_author_name	byte[]	yes		3
is_online	Boolean		return true if this user is currently online	3
can_edit	Boolean		eturn true if user can edit this post.	3
icon_url	String		Return topic author avatar URL	3
timestamp	String	yes	Timestamp of topic last reply
post_time	Date	yes	dateTime.iso8601 format. If this topic has no reply, use the topic creation time.	3
allow_smilies	Boolean		This value (if "false") is to instruct the app do not display smilies and instead display it in text format. This is to address certain forum system allows forum admin to disable smilies across the board. If this flag is missing, assume "true"	4
editor_id	String
editor_name	byte[]		Display name of the editor
edit_time	String		Timestamp of the edit time
edit_reason	byte[]
attachments	Array of Hash table		Returns a list of attachments user has uploaded within this post, in array of hash format.	3
content_type	String	yes	return "image", "pdf" or "other"	3
thumbnail_url	String		if content type = "image", use absolute path (optional: if not presented, use "url" to load thumbnail instead)	3
url	String		URL of the attachment source.	3
filename	byte[]
filesize	Int
thanks_info	Array of Hash table		Return post thanks user list infor only when thank_post is supported.
userid	String		Id of the user who has thanked this post
username	byte[]		Name of the user who has thanked this post
likes_info	Array of Hash table		Return post likes user list infor only when like_post/unlike_post are supported.
userid	String		Id of the user who has liked this post
username	byte[]		Name of the user who has liked this post
client_type	String		the post from which client. return: "web", "mobile", "app", or ""	4

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

get_thread_by_post

Function:

Function Name	Description	Level
get_thread_by_post	This function provides a mean to allow users to jump to the exact post within a thread given the post_id as the parameter. Please note that this function is used in conjunction with "goto_post" in get_config function. If "goto_post" is returned and is = "1", get_thread_by_post is always called instead of get_thread function when the app attempts to enter a thread from a list of posts. This function is useful, for example, when entering a thread from a list of posts generated from Search (search_	3

Input Parameters:

Name	Type	Required?	Description	Level
post_id	String	yes		4
posts_per_request	Boolean		The ability to jump to the right post when opening a thread 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 post with the supplied post_id. Please note that this parameter is optional, the plugin assumes this as "20" if missing.	4
return_html	Int		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 target 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 target 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 target 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

guest_reply_post

Function:

Function Name	Description	Level
guest_reply_post	guest reply to an existing topic	3,4

Input Parameters:

Name	Type	Required?	Description	Level
forum_id	String	yes		3
topic_id	String	yes		3
text_body	byte[]	yes		3
username	byte[]	yes	Guest display name
return_html	Boolean		Only support this parameter when get_config return flag no_refresh_on_post as 1	4

Output Parameters:

Name	Type	Required?	Description	Level
result	Boolean	yes	return true if the action is executed successfully.	3
result_text	byte[]			3
post_id	String	yes	the newly generated post ID for this new topic.	3
state	Int		1 = post is success but need moderation. Otherwise no need to return this key. If this is return. The app should not refresh the thread view as the post will not be appear, instead it should display an alert to user about this post is pending for moderation.	3
post_content	byte[]		Return the newly replied post content and all below keys back to the App if get_config return support no_refresh_on_post. Characters display rules (follow the sequence): 1) Remove all BBCode except [ur], [img], [quote]. 2) Remove all non-displayable characters (e.g. \n, \t, white-space, etc) at the beginning AND the end of the content (Trimming) 3) Replace [url] tags in nested [url][img][/img][/url] image link.	4
can_edit	Boolean		return true if user can edit this post.	4
can_delete	Boolean		return true if user can delete this post.	4
timestamp	String		Timestamp of topic last reply
post_time	Date		dateTime.iso8601 format. If this topic has no reply, use the topic creation time.	4
attachments	Array of Hash table		Returns a list of attachments user has uploaded within this post, in array of hash format.	4
content_type	String		return "image", "pdf" or "other"	4
thumbnail_url	String		if content type = "image"), use absolute path (optional: if not presented, use "url" to load thumbnail instead)	4
url	String		URL of the attachment source.	4