EXT: Ratings¶

What does it do?¶

This extension provides:

• A frontend plugin for displaying and adjusting ratings
• An AJAX-based voting (extremely fast!)
• A highly customizable look for ratings (template and/or css file)
• Several image sets for ratings
• An API for other extensions to integrate ratings into their records (for photos, news, articles, comments, etc)
• A set of hooks to popular extensions to enable the rating functionality inside of them

The extension requires PHP 5.1 or newer. It will not work with PHP 5.0 or older versions. There is no direct dependency on the TYPO3 version but bugs are not accepted if the TYPO3 version is older than current official major TYPO3 version (4.1 in January 2008).

This extension was created by Dmitry Dulepov for Netcreators BV.

Screenshots¶

Default view, user did not vote yet:

Default view, user already voted:

The following images are shipped with this extension to use in ratings:

The first image column describes the “not voted” state, second is “votes” and the images in third column appear when a visitor hovers over the voting bar. All these images are either licensed under GPL or the Creative Commons license. The respective Copyright information is provided in the CSS file that use these images. See the Configuration section for details.

Rating pages¶

To use ratings for a page, the TS template of the ratings extension has to be added to the page. The extension will work out of the box with the default options. See the configuration section in this manual if any option needs to be adjusted.

As a next step, add the ratings plugin to the page. It is possible to override the storage page ID and template file location through the plugin. Now users can rate the pages!

Rating tt_news items¶

To use ratings for tt_news, the TS template of the ratings extension has to be added to the page. The extension will work out of the box with the default options, however if you need to modify the options, see the Configuration section for details.

Insert the ###TX_RATINGS###marker into your tt_news template. Web site visitors now can rate news items. If the rating should not appear on a particular news item, clear the corresponding box when editing a tt_news record.

FAQ¶

None yet

FAQ¶

Non yet

storagePid¶

templateFile¶

minValue¶

maxValue¶

ratingImageWidth¶

mode¶

disableIpCheck¶

additionalCSS¶

FAQ¶

Q: I disabled IP check but after I rate the item, I cannot rate it again!

A: You need to reload page to rate again. This is a technical limitation due to the usage of AJAX.

Q: I included another CSS but the images are cut or clicks do not work properly

A: You forgot to adjust theratingImageWidth parameter. See the Configuration section.

Q: I try to use the extension with TYPO3 3.x/4.0 but...

A: Sorry, but this extension is not tested and will not be supported under any TYPO3 version below 4.1.

Q: I try to use the extension but PHP errors show up

A: Your PHP version is lower than 5.1. The ratings extension does not work with PHP versions lower than 5.1.

Q: Can each content item on the page be rated?

A: Not out of the box. This feature can be added if you'd like to sponsor it (665€).

Terms¶

This section defines some terms used by the API.

Accessing The API¶

The ratings extension provides PHP class, which implements a set of functions to find the rating for the element or display the attached ratings. The rating modification feature is built into this display feature.

To access the API class, include a class definition into your own plugin class:

if (t3lib_extMgm::isLoaded('ratings')) {
        require_once(t3lib_extMgm::extPath('ratings', 'class.tx_ratings_api.php');
}

Notice the usage of t3lib_extMsg::isLoaded(). This allows you not to have any hard dependency on the ratings extension in your own extension but rather a service that is used if the extension is installed.

As a next step, instantiate the API class in the place where you need to use it:

$ratingsAPI = t3lib_div::makeInstance('tx_ratings_api');

It is important to use t3lib_div::makeInstance() for instantiating the API class. Avoid using the PHP operator “new” for this purpose.

When the class is instantiated, it is ready to be called. There is no futher initialization necessary. All functions are independent and can be called in any order.

API Reference¶

This section describes each function and parameters in detail. Please make sure to have read the Terms chart in this chapter before reading the section below.