ocPortal Developer's Guide: Feedback (rating and commenting)

» Return to Contents

In ocPortal, feedback is any sort of comments, trackbacks or ratings or notes for any resource.
For ocPortal2+, we have overhauled this system so that you can post feedback on any resource on the website, you can even add it to custom resources!

sources/feedback.php

Global_functions_feedback.php

Function summary

void	init__feedback ()
array	get_details_behind_feedback_code (ID_TEXT content_type, ID_TEXT content_id)
boolean	may_view_content_behind_feedback_code (MEMBER member_id, ID_TEXT content_type, ID_TEXT content_id)
array	embed_feedback_systems (ID_TEXT page_name, ID_TEXT content_id, BINARY allow_rating, integer allow_comments, BINARY allow_trackbacks, BINARY validated, ?MEMBER submitter, mixed content_url, SHORT_TEXT content_title, ?string forum)
void	post_comment_script ()
tempcode	get_rating_box (mixed content_url, ?string content_title, ID_TEXT content_type, ID_TEXT content_id, boolean allow_rating, ?MEMBER submitter)
tempcode	display_rating (mixed content_url, ?string content_title, ID_TEXT content_type, ID_TEXT content_id, ID_TEXT display_tpl, ?MEMBER submitter)
?array	get_rating_simple_array (mixed content_url, ?string content_title, ID_TEXT content_type, ID_TEXT content_id, ID_TEXT form_tpl, ?MEMBER submitter)
boolean	already_rated (array rating_for_types, ID_TEXT content_id)
void	actualise_rating (boolean allow_rating, ID_TEXT content_type, ID_TEXT content_id, mixed content_url, ?string content_title)
void	actualise_specific_rating (?integer rating, ID_TEXT page_name, MEMBER member_id, ID_TEXT content_type, ID_TEXT type, ID_TEXT content_id, ?string content_url, mixed content_title)
tempcode	get_comments (ID_TEXT content_type, boolean allow_comments, ID_TEXT content_id, boolean invisible_if_no_comments, ?string forum, ?string post_warning, ?mixed _comments, boolean explicit_allow, boolean reverse, ?MEMBER highlight_by_user, boolean allow_reviews)
string	extract_topic_identifier (string full_text)
boolean	actualise_post_comment (boolean allow_comments, ID_TEXT content_type, ID_TEXT content_id, mixed content_url, ?string content_title, ?string forum, boolean avoid_captcha, ?BINARY validated, boolean explicit_allow, boolean no_success_message, boolean private)
void	update_spacer_post (boolean allow_comments, ID_TEXT content_type, ID_TEXT content_id, mixed content_url, ?string content_title, ?string forum, ?AUTO_LINK post_id)
tempcode	get_trackbacks (ID_TEXT content_type, ID_TEXT content_id, boolean allow_trackback, ID_TEXT type)
boolean	actualise_post_trackback (boolean allow_trackbacks, ID_TEXT content_type, ID_TEXT content_id)

void init__feedback()

Standard code module initialisation function.

Parameters…

(No return value)

Return to the function index for this class

Expand: View the source code to this function

array get_details_behind_feedback_code(ID_TEXT content_type, ID_TEXT content_id)

Find who submitted a piece of feedbackable content.

Parameters…

Name	content_type
Description	Content type
Type	ID_TEXT

Name	content_id
Description	Content ID
Type	ID_TEXT

Returns…

Description	A tuple: Content title (NULL: unknown), Submitter (NULL: unknown), URL (for use within current browser session), URL (for use in emails / sharing), Content meta aware info array
Type	array

boolean may_view_content_behind_feedback_code(MEMBER member_id, ID_TEXT content_type, ID_TEXT content_id)

Given a particular bit of feedback content, check if the user may access it.

Parameters…

Name	member_id
Description	User to check
Type	MEMBER

Name	content_type
Description	Content type
Type	ID_TEXT

Name	content_id
Description	Content ID
Type	ID_TEXT

Returns…

Description	Whether there is permission
Type	boolean

array embed_feedback_systems(ID_TEXT page_name, ID_TEXT content_id, BINARY allow_rating, integer allow_comments, BINARY allow_trackbacks, BINARY validated, ?MEMBER submitter, mixed content_url, SHORT_TEXT content_title, ?string forum)

Main wrapper function to embed miscellaneous feedback systems into a module output.

Parameters…

Name	page_name
Description	The page name
Type	ID_TEXT

Name	content_id
Description	Content ID
Type	ID_TEXT

Name	allow_rating
Description	Whether rating is allowed
Type	BINARY

Name	allow_comments
Description	Whether comments/reviews is allowed (reviews allowed=2)
Type	integer
Values restricted to	0 1 2

Name	allow_trackbacks
Description	Whether trackbacks are allowed
Type	BINARY

Name	validated
Description	Whether the content is validated
Type	BINARY

Name	submitter
Description	Content owner (NULL: none)
Type	?MEMBER

Name	content_url
Description	URL to view the content
Type	mixed

Name	content_title
Description	Content title
Type	SHORT_TEXT

Name	forum
Description	Forum to post comments in (NULL: site-wide default)
Type	?string

Returns…

Description	Tuple: Rating details, Comment details, Trackback details
Type	array

void post_comment_script()

Do an AJAX comment post

Parameters…

(No return value)

tempcode get_rating_box(mixed content_url, ?string content_title, ID_TEXT content_type, ID_TEXT content_id, boolean allow_rating, ?MEMBER submitter)

Get tempcode for doing ratings (sits above get_rating_simple_array)

Parameters…

Name	content_url
Description	The URL to where the commenting will pass back to (to put into the comment topic header) (URLPATH or Tempcode)
Type	mixed

Name	content_title
Description	The title to where the commenting will pass back to (to put into the comment topic header) (NULL: don't know, but not first post so not important)
Type	?string

Name	content_type
Description	The type (download, etc) that this rating is for
Type	ID_TEXT

Name	content_id
Description	The ID of the type that this rating is for
Type	ID_TEXT

Name	allow_rating
Description	Whether this resource allows rating (if not, this function does nothing - but it's nice to move out this common logic into the shared function)
Type	boolean

Name	submitter
Description	Content owner (NULL: none)
Default value
Type	?MEMBER

Returns…

Description	Tempcode for complete rating box
Type	tempcode

tempcode display_rating(mixed content_url, ?string content_title, ID_TEXT content_type, ID_TEXT content_id, ID_TEXT display_tpl, ?MEMBER submitter)

Display rating using images

Parameters…

Name	content_url
Description	The URL to where the commenting will pass back to (to put into the comment topic header) (URLPATH or Tempcode)
Type	mixed

Name	content_title
Description	The title to where the commenting will pass back to (to put into the comment topic header) (NULL: don't know, but not first post so not important)
Type	?string

Name	content_type
Description	The type (download, etc) that this rating is for
Type	ID_TEXT

Name	content_id
Description	The ID of the type that this rating is for
Type	ID_TEXT

Name	display_tpl
Description	The template to use to display the rating box
Default value	RATING_INLINE_STATIC
Type	ID_TEXT

Name	submitter
Description	Content owner (NULL: none)
Default value
Type	?MEMBER

Returns…

Description	Tempcode for complete trackback box
Type	tempcode

?array get_rating_simple_array(mixed content_url, ?string content_title, ID_TEXT content_type, ID_TEXT content_id, ID_TEXT form_tpl, ?MEMBER submitter)

Get rating information for the specified resource.

Parameters…

Name	content_url
Description	The URL to where the commenting will pass back to (to put into the comment topic header) (URLPATH or Tempcode)
Type	mixed

Name	content_title
Description	The title to where the commenting will pass back to (to put into the comment topic header) (NULL: don't know, but not first post so not important)
Type	?string

Name	content_type
Description	The type (download, etc) that this rating is for
Type	ID_TEXT

Name	content_id
Description	The ID of the type that this rating is for
Type	ID_TEXT

Name	form_tpl
Description	The template to use to display the rating box
Default value	RATING_FORM
Type	ID_TEXT

Name	submitter
Description	Content owner (NULL: none)
Default value
Type	?MEMBER

Returns…

Description	Current rating information (ready to be passed into a template). RATING is the rating (out of 10), NUM_RATINGS s the number of ratings so far, RATING_FORM is the tempcode of the rating box (NULL: rating disabled)
Type	?array

boolean already_rated(array rating_for_types, ID_TEXT content_id)

Find whether you have rated the specified resource before.

Parameters…

Name	rating_for_types
Description	List of types (download, etc) that this rating is for. All need to be rated for it to return true.
Type	array

Name	content_id
Description	The ID of the type that this rating is for
Type	ID_TEXT

Returns…

Description	Whether the resource has already been rated
Type	boolean

void actualise_rating(boolean allow_rating, ID_TEXT content_type, ID_TEXT content_id, mixed content_url, ?string content_title)

Actually adds a rating to the specified resource.It performs full checking of inputs, and will log a hackattack if the rating is not between 1 and 10.

Parameters…

Name	allow_rating
Description	Whether this resource allows rating (if not, this function does nothing - but it's nice to move out this common logic into the shared function)
Type	boolean

Name	content_type
Description	The type (download, etc) that this rating is for
Type	ID_TEXT

Name	content_id
Description	The ID of the type that this rating is for
Type	ID_TEXT

Name	content_url
Description	The URL to where the commenting will pass back to (to put into the comment topic header) (URLPATH or Tempcode)
Type	mixed

Name	content_title
Description	The title to where the commenting will pass back to (to put into the comment topic header) (NULL: don't know, but not first post so not important)
Type	?string

(No return value)

void actualise_specific_rating(?integer rating, ID_TEXT page_name, MEMBER member_id, ID_TEXT content_type, ID_TEXT type, ID_TEXT content_id, ?string content_url, mixed content_title)

Implement a rating at the quantum level.

Parameters…

Name	rating
Description	Rating given (NULL: unrate)
Type	?integer
Value range	1 10

Name	page_name
Description	The page name the rating is on
Type	ID_TEXT

Name	member_id
Description	The member doing the rating
Type	MEMBER

Name	content_type
Description	The type (download, etc) that this rating is for
Type	ID_TEXT

Name	type
Description	The second level type (probably blank)
Type	ID_TEXT

Name	content_id
Description	The ID of the type that this rating is for
Type	ID_TEXT

Name	content_url
Description	The title to where the commenting will pass back to (to put into the comment topic header) (NULL: don't know)
Type	?string

Name	content_title
Description	The URL to where the commenting will pass back to (to put into the comment topic header) (URLPATH or Tempcode)
Type	mixed

(No return value)

tempcode get_comments(ID_TEXT content_type, boolean allow_comments, ID_TEXT content_id, boolean invisible_if_no_comments, ?string forum, ?string post_warning, ?mixed _comments, boolean explicit_allow, boolean reverse, ?MEMBER highlight_by_user, boolean allow_reviews)

Get the tempcode containing all the comments posted, and the comments posting form for the specified resource.

Parameters…

Name	content_type
Description	The type (download, etc) that this commenting is for
Type	ID_TEXT

Name	allow_comments
Description	Whether this resource allows comments (if not, this function does nothing - but it's nice to move out this common logic into the shared function)
Type	boolean

Name	content_id
Description	The ID of the type that this commenting is for
Type	ID_TEXT

Name	invisible_if_no_comments
Description	Whether the comment box will be invisible if there are not yet any comments (and you're not staff)
Default value	boolean-false
Type	boolean

Name	forum
Description	The name of the forum to use (NULL: default comment forum)
Default value
Type	?string

Name	post_warning
Description	The default post to use (NULL: standard courtesy warning)
Default value
Type	?string

Name	_comments
Description	The raw comment array (NULL: lookup). This is useful if we want to pass it through a filter
Default value
Type	?mixed

Name	explicit_allow
Description	Whether to skip permission checks
Default value	boolean-false
Type	boolean

Name	reverse
Description	Whether to reverse the posts
Default value	boolean-false
Type	boolean

Name	highlight_by_user
Description	User to highlight the posts of (NULL: none)
Default value
Type	?MEMBER

Name	allow_reviews
Description	Whether to allow ratings along with the comment (like reviews)
Default value	boolean-false
Type	boolean

Returns…

Description	The tempcode for the comment topic
Type	tempcode

string extract_topic_identifier(string full_text)

Topic titles/descriptions (depending on forum driver) are encoded for both human readable data, and a special ID code: this will extract just the ID code, or return the whole thing if no specific pattern match

Parameters…

Name	full_text
Description	Potentially complex topic title
Type	string

Returns…

Description	Simplified topic title
Type	string

boolean actualise_post_comment(boolean allow_comments, ID_TEXT content_type, ID_TEXT content_id, mixed content_url, ?string content_title, ?string forum, boolean avoid_captcha, ?BINARY validated, boolean explicit_allow, boolean no_success_message, boolean private)

Add comments to the specified resource.

Parameters…

Name	allow_comments
Description	Whether this resource allows comments (if not, this function does nothing - but it's nice to move out this common logic into the shared function)
Type	boolean

Name	content_type
Description	The type (download, etc) that this commenting is for
Type	ID_TEXT

Name	content_id
Description	The ID of the type that this commenting is for
Type	ID_TEXT

Name	content_url
Description	The URL to where the commenting will pass back to (to put into the comment topic header) (URLPATH or Tempcode)
Type	mixed

Name	content_title
Description	The title to where the commenting will pass back to (to put into the comment topic header) (NULL: don't know, but not first post so not important)
Type	?string

Name	forum
Description	The name of the forum to use (NULL: default comment forum)
Default value
Type	?string

Name	avoid_captcha
Description	Whether to not require a captcha
Default value	boolean-false
Type	boolean

Name	validated
Description	Whether the post is validated (NULL: unknown, find whether it needs to be marked unvalidated initially). This only works with the OCF driver (hence is the last parameter).
Default value
Type	?BINARY

Name	explicit_allow
Description	Whether to force allowance
Default value	boolean-false
Type	boolean

Name	no_success_message
Description	Whether to skip a success message
Default value	boolean-false
Type	boolean

Name	private
Description	Whether posts made should not be shared
Default value	boolean-false
Type	boolean

Returns…

Description	Whether a hidden post has been made
Type	boolean

void update_spacer_post(boolean allow_comments, ID_TEXT content_type, ID_TEXT content_id, mixed content_url, ?string content_title, ?string forum, ?AUTO_LINK post_id)

Update the spacer post of a comment topic, after an edit.

Parameters…

Name	allow_comments
Description	Whether this resource allows comments (if not, this function does nothing - but it's nice to move out this common logic into the shared function)
Type	boolean

Name	content_type
Description	The type (download, etc) that this commenting is for
Type	ID_TEXT

Name	content_id
Description	The ID of the type that this commenting is for
Type	ID_TEXT

Name	content_url
Description	The URL to where the commenting will pass back to (to put into the comment topic header) (URLPATH or Tempcode)
Type	mixed

Name	content_title
Description	The title to where the commenting will pass back to (to put into the comment topic header) (NULL: don't know, but not first post so not important)
Type	?string

Name	forum
Description	The name of the forum to use (NULL: default comment forum)
Default value
Type	?string

Name	post_id
Description	ID of spacer post (NULL: unknown)
Default value
Type	?AUTO_LINK

(No return value)

tempcode get_trackbacks(ID_TEXT content_type, ID_TEXT content_id, boolean allow_trackback, ID_TEXT type)

Get the tempcode containing all the trackbacks received, and the trackback posting form for the specified resource.

Parameters…

Name	content_type
Description	The type (download, etc) that this trackback is for
Type	ID_TEXT

Name	content_id
Description	The ID of the type that this trackback is for
Type	ID_TEXT

Name	allow_trackback
Description	Whether this resource allows trackback (if not, this function does nothing - but it's nice to move out this common logic into the shared function)
Type	boolean

Name	type
Description	The type of details being fetched (currently: blank or XML)
Default value
Type	ID_TEXT

Returns…

Description	Tempcode for complete trackback box
Type	tempcode

boolean actualise_post_trackback(boolean allow_trackbacks, ID_TEXT content_type, ID_TEXT content_id)

Add trackbacks to the specified resource.

Parameters…

Name	allow_trackbacks
Description	Whether this resource allows trackback (if not, this function does nothing - but it's nice to move out this common logic into the shared function)
Type	boolean

Name	content_type
Description	The type (download, etc) that this trackback is for
Type	ID_TEXT

Name	content_id
Description	The ID of the type that this trackback is for
Type	ID_TEXT

Returns…

Description	Whether trackbacks are on
Type	boolean

Tutorial - Adding Feedback to a Custom Resource

To add ratings, comments, and staff notes to a module, add the following code snippets…

In the install function, in the table creation…

Code (`php`)

   'allow_rating'=>'BINARY',

   'allow_comments'=>'BINARY',

   'notes'=>'LONG_TEXT',

In the run function…

Code (`php`)

   require_code('feedback');

In the get_X_form_fields function header…

Code (`php`)

, $allow_rating=true, $allow_comments=true, $notes=''

In the get_X_form_fields function…

Code (`php`)

   $fields->attach(feedback_fields($allow_rating, $allow_comments, $notes));

In the _ad and __ed functions…

Code (`php`)

   $allow_rating=post_param_integer('allow_rating',0);

   $allow_comments=post_param_integer('allow_comments',0);

   $notes=post_param('notes');

In the _ed function, where the get_X_form_fields function is called…

Code (`php`)

, $myrow['allow_rating'], $myrow['allow_comments'], $myrow['notes']

In the _ad and __ed functions, where the add/edit backend function is called…

Code (`php`)

, $allow_rating, $allow_comments, $notes

In the add/edit backend function header…

Code (`php`)

, $allow_rating, $allow_comments, $notes

In the add/edit backend function query_insert call…

Code (`php`)

'allow_rating'=>$allow_rating,'allow_comments'=>$allow_comments,'notes'=>$notes,

In the delete backend function…

Code (`php`)

   $GLOBALS['SITE_DB']->query_delete('rating',array('rating_for_type'=>get_page_name(),'rating_for_id'=>$id));

In the function for the type that can be commented/rated…

Code (`php`)

   do_rating($myrow['allow_rating'],get_page_name(), $id);

   do_comments($myrow['allow_comments'],get_page_name(), $id, $self_url, $self_title);

   $rating_details=get_rating_text(get_page_name(), $id);

   $comment_details=get_comment_details(get_page_name(), $myrow['allow_comments'], $id);

0 reviews: Unrated (average)

There have been no comments yet

Post review

Your name:	Your name (join or login)
Subject:	Subject
Rating:
Your message: ( posting rules ) [ View all emoticons ]	Your message Make your post civil and relevant.