Ratings
Introduction
The ratings module allows any module developer to add ratings to their
module items with ease. This module is not designed to be called directly,
but instead is meant to be called as a utility module from within other
modules to expand their functionality.
API
The API for the ratings module consists of the following user functions
display
display provides a suitable output string for displaying the current
rating of a defined item. The variables used by this function are as
follows:
modname - the name of the module to get the rating for
itemid - the item in the module to get the rating for
ratingtype - the type of the rating (optional)
style - the style in which to display the rating (optional).
The style can be one of the following items:
percentage - rating shown as a percentage
outoffive - rating shown as value out of five
outoffivestars - rating shown as value out of five using stars
outoften - rating shown as value out of ten
outoftenstars - rating shown as value out of ten using stars
This function returns a suitable output string if the rating is known to
the system, or void if it is not.
ask
ask provides a suitable output string to ask for a rating of a
defined item. The variables used by this function are as follows:
modname - the name of the module to obtain a rating for
itemid - the item in the module to obtain a rating for
ratingtype - the type of the rating (optional)
returnurl - the URL to return to after the ratings has been
obtained
style - the style in which to obtain a rating (optional). See
above for details
This function returns a suitable output string if the current user is
allowed to rate the item, or void if they are not.
Examples
The example below shows how to use the functions provided with this API.
The example is used with the 'News' module and
uses the sid variable as the rating item id.
// Show rating for news item
if (pnModLoad('Ratings')) {
$rating = pnModFunc('Ratings',
'user',
'display',
array('modname' => 'News',
'itemid' => $sid));
if (isset($rating)) {
$output->Text('Rating for this story: ');
$output->SetInputState(_PNH_VERBATIMINPUT);
$output->Text($rating);
$output->SetInputState(_PNH_PARSEINPUT);
}
$askrating = pnModFunc('Ratings',
'user',
'ask',
array('modname' => 'News',
'itemid' => $sid,
'returnurl' => pnModURL('News',
'user',
'display',
array('sid' => $sid))));
$output->SetInputState(_PNH_VERBATIMINPUT);
$output->Text($askrating);
$output->SetInputState(_PNH_PARSEINPUT);
}
Permission
The permissions for the ratings module are as follows:
Component
The component is simply 'Ratings::'
Instance
The instance is 'Module name:Rating type:Item ID'. The items are
described below:
Module name - the module name as passed in as modname to
the display and ask functions as above
Rating type - the specific type of rating that this item is for,
as passed in as ratingtype to the display and ask
functions as above. If no value is supplied this is set to 'default'
Item ID - the module-specific ID of the item being rated, as
passed in as itemid to the display and ask
functions as above.
A user needs to have at least read permission to see an item's rating, and
at least comments permission to be able to rate an item.
Configuration
The module has two configuration variables, described below.
defaultstyle
This variable specifies the style in which ratings are displayed when no
specific display style is supplied by the calling module. This variable
can take the value of any of the display styles available, as listed
above.
seclevel
This variables specificies the security level that is applied to ratings
in an attempt to avoid users being able to rig ratings. The higher the
security level the harder it is for a user to be able to rate an item
multiple times, but the more work that PostNuke has to do to try to ensure
that the user is not attempting to rate a single item many times.