This section is ment for extension developers who want to integrate ratings functionality into their extensions. Ratings own frontend plugin is a simple wrapper around this API.
This section defines some terms used by API.
Term | Data type: | Description: |
|---|---|---|
Element | N/A | Any item to rate. It can be page, content element, article, image or any other item that can be identified in any way |
Reference | string | Unique identifier of the element. It must uniquely identify element among any other element inside TYPO3. Ratings API does not care about format of the reference as soon as it can be saved into varchar(255) database field. However it is strongly recommended to use standard typo3 “group” format for it, which consists from table name, undercope and uid of the item (for example, “tt_content_10”, “pages_20” or “tx_myext_data_88”). |
Configuration | array | In order to calculate or display ratings, API needs to know certain configuration parameters. If supplied by caller, it expects an array with parameters described in “Configuration” section of this manual. If configuration is not supplied by caller, API will use “plugin.tx_ratings_pi1” from page TypoScript setup. If none of these two is available, results of the API will be unpredictable. It is an error not to have configuration for the API. |
Ratings extension provides PHP class, which implements a set of functions to find rating for the element or display ratings. Rating modification feature is built into display feature.
To access 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 usage of t3lib_extMsg::isLoaded. This allows you not to have hard dependency on Ratings extension in your own extension.
Next instantiate 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 API class. Never use PHP operator “new” for this purpose.
When class is installed, it is ready to be called. There is no futher initialization necessary. All functions are independent and can be called in any order.
This section describes each function and parameters in details. Reader must read “Terms” section above before reading this section.
Parameter: | Data type: | Description: | Default: |
|---|---|---|---|
$ref | string | Reference to the element | |
$conf | array | API configuration. If not provided, default will be used. | null |
return value | float | Raiting value in percent (from 0 to 100) |
