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.