Fullscreen
[Show/Hide Right Column]

Print
English

Advanced Ratings page

Overview
Use this page to configure a "rating" sytem to evaluate tracker items or wiki pages.

To access
Click the Ratings icon Ratings on the Admin Panel
or
Access http://yourdomain.com/tiki-admin.php?page=rating

Note
Tiki currently supports sorting through advanced rating in:


6.x
Advanced Ratings page
Advanced Ratings page


Setting Description Default
Global configuration
Advanced Rating Enable the internal rating system, used for calculating values from trackers, articles, or other features.
Rating recalculation mode: Determines when and how rating aggregates are recalculated:
* On vote (default): indicates that the score for the object should be recalculated every time a vote is performed. This option is suitable for sites with lower volumes and relatively simple calculation methods when ratings are used.
* Random on load: will cause a few scores to be calculates on page load on a random basis (odds and count can be configured to adapt to site load). This option is suitable for calculation rules involving time that must be recalculated even if no new votes occurred.
* Random on vote is similar to random on load, but will recalculate multiple scores (not necessarily including the current object) when a vote is performed. It is suitable for similar situations. The best option will depend on site load.
* Periodic: is the best option for heavy load sites, making sure all calculations are done outside the web requests. A cron job must be set-up manually by the site's administrator. A sample script is available at the end of this page.
Depending on the site load, some options may be better than others; on large volume sites, we recommend cron job. The Recalculate on vote recalculation may be inaccurate if rating calculation depends time. 		Recalculate on vote
Recalculation odds (1 in X):
Recalculation count:
Wiki
Simple wiki ratings Enable a simple rating bar at the top of each wiki page.
Wiki rating options: List of options for the simple wiki ratings. 1,2,3,4,5
Articles Enable a simple rating bar at the top of each articles page.
User ratings on articles
Article rating options:

5.x

The feature must first be enabled through this same administration panel. Along with the feature, a few options are available. Among them, the score recalculation period must be defined. These are the available options:

  • On vote (default) indicates that the score for the object should be recalculated every time a vote is performed. This option is suitable for sites with lower volumes and relatively simple calculation methods when ratings are used.
  • Random on load will cause a few scores to be calculates on page load on a random basis (odds and count can be configured to adapt to site load). This option is suitable for calculation rules involving time that must be recalculated even if no new votes occurred.
  • Random on vote is similar to random on load, but will recalculate multiple scores (not necessarily including the current object) when a vote is performed. It is suitable for similar situations. The best option will depend on site load.
  • Periodic is the best option for heavy load sites, making sure all calculations are done outside the web requests. A cron job must be set-up manually by the site's administrator. A sample script is available at the end of this page.

For the random options, the odds of recalculating must be specified as a dice roll. For each occurrence of a recalculation, a limit to how many scores can be calculated must be specified to avoid the hang-up effect on the page load.

The value ranges for each object type can also be specified through the administration panels.

The common sort_mode parameter to lists can be used to activate sorting using advanced ratings. To do so, the sort mode must be set to adv_rating_X_asc or adv_rating_X_desc where X is the ID of the rating configuration. The default sort can also be set to advanced ratings in the administration panel where applicable.

Calculation configuration


From the administration panel, new calculations can be added. Initially, only the name is required. When created, the calculation will contain suitable default values.





For wiki pages:
Image


Thus, visitors can provide feedback like:

  • Did this page help you solve the issue?
  • Was this page easy to understand?

alias





Advanced Rating

Introduced in Tiki5, the advanced rating feature allows for more control over the aggregation of scores.

Rating methods are defined globally and will be used for all supported objects. They are defined through the Advanced Rating administration panel (tiki-admin.php?page=rating). Multiple methods can be created. If a method contains type-specific calculations, it will be ignored when performing the calculation.

Features currently supporting sorting through advanced rating:

Sorting items according to advanced rating


Note that the sort mode to use when needing to sort by advanced rating is either adv_rating_xx_asc or adv_rating_xx_desc, where xx is the ratingConfigId.

Feature request: Can we make this take the name of the config instead of the ratingConfigId as well?

Set-up



By default, each calculated value is kept for 1 hour (3600 seconds). This limit does not apply when recalculating on vote, but is used for every other technique to avoid recalculating the same scores over and over again.

The calculation is defined as a small piece of code, similar to functional languages, which is very close to mathematical representations. Creating custom formulas is expected to require some mathematical skills. However, this documentation should provide examples for most frequent cases.

The editor in the administration panel performs extensive validation and will make it impossible to save the formula unless it can be evaluated. Checks are performed for:
  • Syntax errors
  • Unknown functions
  • Missing arguments
  • Invalid argument values
  • Unknown input variables

Default formula
(rating-average (object type object-id))


It can be altered to limit the vote consideration to a limited time span, 30 days for example.

Recent votes only
(rating-average
    (object type object-id)
    (range (mul 3600 24 30))
)


In the language, spaces do not matter. Only the parenthesis indicate structure. rating-average is a function that fetches the ratings for a given object. type and object-id are standard variables fed when calculating a rating. object and range are configuration options of the function.

mul is a mathematical function. (mul 3600 24 30) is equivalent to 3600*24*30.

The functions can be combined in various ways. For example, we could calculate a score that considers the votes from the past month, but gives extra emphasis on the recent ones.

Combined vote duration
(add
    (rating-average
        (object type object-id)
        (range (mul 3600 24 30)))
    (rating-average
        (object type object-id)
        (range (mul 3600 24 7)))
)


Even though the votes are 1-5, the final score can be on an entirely different scale. The language is also extensible if the calculation needs to be combined with other factors or weight. See Rating Language.

All available options are documented in the following section.

Reference

mul (Multiply)

Performs a simple multiplication accepting multiple input values.
Examples
(mul 3 4)
   -> 12
(mul (mul 3 4) 5)
   -> 60
(mul 3 4 5)
   -> 60
(mul 4 0.5)
   -> 2


add (Sum)

Performs a simple sum accepting multiple input
Examples
(add 3 4)
   -> 7
(add (add 3 4) 5)
   -> 12
(add 3 4 5)
   -> 12
(add 4 0.5)
   -> 4.5


rating-average and rating-sum

The rating functions calculate the score from the rating history table. Each rating performed on the site is kept in the database and can be used to calculate custom ratings on. The various options allow to adapt the score calculation to reflect the importance on the site, whether it is to support quality improvement on documentation or to rank incoming data on a feed aggregator.

  • object, mandatory and always (object type object-id) in this context.
  • range, to limit how long votes are considered. Argument is provided as a number of seconds.
  • ignore, with anonymous as an argument to only consider votes from registered users.
  • keep, to only consider one vote per visitor. Unless the option is present, all of the votes are taken into account. The option can be either latest or oldest to indicate which one to keep.
  • revote can be specified if keep is specified. Indicates the time period required between votes. For example, users could be allowed to vote more than once per day, but only their latest vote each day would be considered, if revote is set to mul(24 3600). If the user voted yesterday as well as today, both votes will be counted.

str

Generates a static string when needed and the processor attempts to process the string as a variable. Any arguments will be concatenated using spaces.

Examples
(str hello-world)
   -> "hello-world"
(str hello world)
   -> "hello world"
(str 
    hello
    world
    foobar)
   -> "hello world foobar"


article-info

Pulls information from an article to include in the calculation. The first argument must always resolve to 'article'. If any other value, the calculation will be skipped for the evaluated object, making the formula type-specific.

Available properties:
  • rating, the static rating attached to the article
  • view-count
  • age-second
  • age-hour
  • age-day
  • age-week
  • age-month

Examples
(article-info type object-id rating)

(article-info (str article) 42 age-month)


attribute

Pulls information from the generic object attributes.

Examples
(attribute
    (object type object-id)
    (property tiki.proposal.accept)
)
    -> [value for page in a rating calculation]
(attribute
    (object (str wiki page) 14)
    (property tiki.proposal.accept)
    (default 0)
)
    -> [value for page id 14]


Appendix


Cron job
<?php

chdir('/path/to/tikiroot');

require_once 'tiki-setup.php';
require_once 'lib/rating/ratinglib.php';

$ratinglib->refresh_all();




Related



Contributors to this page: xavi67830 points  , Nelson809 points  , Louis-Philippe Huberdeau1043 points  and Marc Laporte9123 points  .
Page last modified on Wednesday 07 December, 2011 08:28:38 UTC by xavi67830 points .
The content on this page is licensed under the terms of the Creative Commons Attribution-ShareAlike License.

SourceHistorySlideshowComments

Site Language

Reference Guide

Keywords

These keywords serve as "hubs" for navigation within the Tiki documentation. They correspond to development keywords (bug reports and feature requests):



Tiki Newsletter

Delivered fresh to your email inbox!
Newsletter subscribe icon
Don't miss major announcements and other news!
Contribute to Tiki