HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

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

Return to the function index for this class Expand: View the source code to this function

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

Return to the function index for this class Expand: View the source code to this function

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

Return to the function index for this class Expand: View the source code to this function

void post_comment_script()

Do an AJAX comment post

Parameters…

(No return value)


Return to the function index for this class Expand: View the source code to this function

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

Return to the function index for this class Expand: View the source code to this function

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

Return to the function index for this class Expand: View the source code to this function

?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

Return to the function index for this class Expand: View the source code to this function

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

Return to the function index for this class Expand: View the source code to this function

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)


Return to the function index for this class Expand: View the source code to this function

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)


Return to the function index for this class Expand: View the source code to this function

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

Return to the function index for this class Expand: View the source code to this function

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

Return to the function index for this class Expand: View the source code to this function

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

Return to the function index for this class Expand: View the source code to this function

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)


Return to the function index for this class Expand: View the source code to this function

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

Return to the function index for this class Expand: View the source code to this function

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

Return to the function index for this class Expand: View the source code to this function

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);