Helpdesk

1. Functionality

1.1. Function

The module is used to rate different types of content (profiles, listings, etc.). The received information is formed into a rating. The rating is based on a number of parameters set for a specified type of content. It is possible to choose a specific type of rating for a specific type of content – stars or yes/no. Rating values may be in the range of 1 to 5. Rating types and parameters are set in values_(n) array, where (n) is language id:

array(

rate_type_1 => array(

“main” => array(

“header” => “Rate 1”,

“votes” => array(

“1” => “Vote 1”,

“2” => “Vote 2”,

“3” => “Vote 3”,

“4” => “Vote 4”,

“5” => “Vote 5”,

),

),

“dop1” => array(

“header” => “Subrate 1.1”,

“votes” => array(

“1” => “Vote 1”,

“2” => “Vote 2”,

“3” => “Vote 3”,

“4” => “Vote 4”,

“5” => “Vote 5”,

),

),

“dop2” => array(

“header” => “Subrate 1.2”,

“votes” => array(

“1” => “Vote 1”,

“2” => “Vote 2”,

“3” => “Vote 3”,

“4” => “Vote 4”,

“5” => “Vote 5”,

),

),

…

),

rate_type_2 => array(

“main” => array(

“header” => “Rate 2”,

“votes” => array(

“1” => “Vote 1”,

“2” => “Vote 2”,

“3” => “Vote 3”,

“4” => “Vote 4”,

“5” => “Vote 5”,

),

),

“dop1” => array(

“header” => “Subrate 2.1”,

“votes” => array(

“1” => “Vote 1”,

“2” => “Vote 2”,

“3” => “Vote 3”,

“4” => “Vote 4”,

“5” => “Vote 5”,

),

),

“dop2” => array(

“header” => “Subrate 2.2”,

“votes” => array(

“1” => “Vote 1”,

“2” => “Vote 2”,

“3” => “Vote 3”, id

“4” => “Vote 4”,

“5” => “Vote 5”,

),

),

…

),

…

),

Rating is calculated each time a new review is received.

The following formula is used:

all the collected data – rating type, array with detailed reviews, number of reviews, numeric value of rating – object models are passed via a callback along with an object id, so that it retained the data and used without any direct reference to the module of reviews.

The owner of the content can reply reviews only once. Replies to reviews cannot be edited or deleted.

1.2. Admin mode

Admin panel includes a list of submitted reviews and an option to manage reviews of listings and user profiles. The list of reviewed profiles (private persons, agents, agencies) is available in Interface section. The list includes GID, rating type, date added, and actions. Types of content can be edited. They can be deleted or added only during the installation with the help of module methods that want to be reviewed.

The following options are available for site admin:

• Manage types of rating: stars (from 1 to 5) or yes/no (from 1 to 2);
• Add and remove additional ratings;
• Edit rating questions.

The change of a rating type leads to the change of settings available in a rating. Main rating includes rating name, enumeration of rating elements (stars or yes/no) and translations. Additional rating is displayed in blocks and includes: name, enumeration of sub-rating elements, text and remove button. A new sub-rating can be added below. The order of additional rating elements can be changed with the help of drag&drop tool. If admin changes rating type, the changes update all previously received reviews.

The list of received reviews includes user name of the person who submitted a review, rating, message, date and actions (edit and delete). Admin can change the received review – rating, message and reply of the content provider.

1.3. User mode

Three blocks can be added to the website:

• Form of adding a new review;
• Information about object rating;
• A paged list of object reviews.

The form of adding a review contains a graphical representation of the rating system, comment field and button to submit the review. When review is submitted, AJAX-query with review details is sent to the module controller. The result is either a notification about successfully submitted review or an error message. A review cannot be submitted if main parameters and message fields are empty.

Information block of object rating can include a graphical representation of either a main parameter without value specification (mini) and with value specification (normal), or all parameters (extended).

A separate review of the information block includes a graphical representation of the main rating, reviewer logotype, message and reply of user whose content is reviewed (if there is any).

1.4. Related modules

The module uses the functionality of the following related modules:

• notifications — notification about reviews;
• spam — a review is marked as spam;
• moderation — badwords check in a review message;
• ausers — permissions of moderators.

1.5. Functionality related to other modules

The module functionality can be used by any other module to add the ability to review an content object. To do it, during the installation the module must create a new type of object for the module of reviews. To retrieve and save the calculated values of the rating, the module should include the method of reverse action. The module of reviews supports helpers to display object rating, review form and a list of reviews on a site page.

1.6. Specific functionality

No specific functionality.

2. Implementation

2.1. API

API controller (Reviews_api) provides the following methods:

public function send_review();

Creates/saves a review. Details about reviewed object and user are required to create a review. If the received data are validated, the methods create a new review and send notifications to the object owner and admin (if an appropriate feature is checked). If the validation fails, there is a list of errors.

POST parameters:

$data array – review details. Keys of the array: id – review id, id_object – object id, gid_type – guid of rating type (stars, yes/no), id_poster – id of user who sumbits a review, rating_data – rating details

public function get_reviews($type_gid=null, $object_id=null, $order=date_add, $order_direction=DESC, $page=1);

A paged list of object reviews. Standard formatting options are applied to the objects of review. Formatted data is returned in special fields.

Parameters:

$type_gid string — GID of rating type

$object_id integer — object id

$order string — sort results by field

$order_direction string — order direction

$page integer — page with results

public function reply($review_id);

Replies a review. The method returns an error if a current user is not the owner of the reviewed object. After a successful validation, the reply is added to the review, the reviewer receives a notification about reply of the object owner. Depending on settings in the admin panel, admin receives a notification about a reply to review or not.

POST parameters:

$data array — review details. Keys of the array: answer – reply text.