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:

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:

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:

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.