Loading...
 

Advanced Ratings & Calculation Syntax

Overview
Use this page to configure a "rating" sytem to evaluate tracker items or wiki pages. Introduced in Tiki5, the advanced rating feature allows for more control over the aggregation of scores. You will also see in this documentation page how to use the calculations syntax, which also applies at the Mathematical Calculation Tracker Field.

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

Note
Tiki currently supports sorting through advanced rating in:



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.
Before any attempt to re-index the object: Ties into the Unified Index and updates the calculation at index-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:



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?



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.

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.

Syntax

General Reference


Sample and use case



comment

Any comment block is stripped from the formula at parse-time
Examples
(mul
  1
  2
  (comment Simple enough?))
    -> 2


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


div (Divide)

Performs a simple division accepting multiple input values.
Examples
(div 3 4)
   -> 0.75
(div (mul 3 10) 5)
   -> 6
(div 30 5 3)
   -> 2
(div 4 0.5)
   -> 8


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


sub (Substract)

Performs a simple substraction accepting multiple input
Examples
(sub 3 4)
   -> -1
(sub (sub 3 4) 5)
   -> -6
(sub 3 4 5)
   -> -6
(sub 4 0.5)
   -> 3.5


round

Rounds to a specific number of digits (new in Tiki12)

Examples
(round 4.556234342234 2)
   -> 4.56
(round 4.556234342234)
   -> 5



coalesce

Returns the first non-empty value from the list.

Examples
(coalesce 3 4)
   -> -3
(coalesce (sub 3 3) 5)
   -> 5
(coalesce 0 0 (str) -10)
   -> -10
(coalesce 0 0 0 0 0)
   -> 0


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.

Note: The quoted string syntax was included in Tiki13.

Examples
(str hello-world)
   -> "hello-world"
(str hello world)
   -> "hello world"
(str 
    hello
    world
    foobar)
   -> "hello world foobar"
(str (mul 2 3) "= 6")
   -> "6 = 6"
(str some text with new line~nl~)
   -> "some text with new line\n"


str-to-time

Parse about any English textual datetime description into a Unix timestamp. See PHP's strtotime function for more details on valid formats and options. New in Tiki18.

Examples
(str-to-time (str 2017-06-05))
   -> "1496610000"
(date (str Y-m-d) (str-to-time (str +1 day) (str 2017-05-29)))
   -> "2017-05-30"


str-replace

Replace substring in a string. See PHP's str_replace function for exact arguments. New in Tiki18.

Examples
(str-replace (str foo) (str bar) (str hello foo))
   -> "hello bar"


number-format

Format a number with grouped thousands. See PHP's number_format function for exact arguments. New in Tiki18.

Examples
(number_format 123456.78)
   -> "123,456.78"
(number_format 120.334 (str 3))
   -> "120.334"
(number_format 120.334 (str 0))
   -> "120"
(number_format 123456.78 (str 2) (str ,) (str ))
   -> "123 456,78"


concat

Concatenates a string of text. (new in Tiki12)

Note: The quoted string syntax was included in Tiki13.

Examples
(concat 
    (str $)
    1234
)
   -> "$1234"
(concat 
    14
    (str %)
)
   -> "14%"
(concat 14 "%")
   -> "14%"


contains

Searches for a value within a vector of values (new in Tiki15.0, backported to Tiki14.2 and Tiki12.5).

Examples
(contains 4 (1,2) )
 -> 0
(contains 4 (2,4) )
 -> 1


Note that if you are using an argument value in here, you would need to eval and then put brackets around to make it work.
args.values_by_permname.version: 305,306
(contains 307 (eval(args.values_by_permname.version)))
 -> 0
(contains 305 (eval(args.values_by_permname.version)))
 -> 1
(contains 30 (eval(args.values_by_permname.version)))
 -> 0



map

Generates a map (or dictionary).

Examples
(map
  (key1 1)
  (key2 2)
  (key3 (str value3))
)
 -> {"key1": 1, "key2": 2, "key3": "value3"}


equals

Compares multiple values.

Examples
(equals 2 (add 1 1) (sub 4 2))
 -> 1 (equivalent of 2 == 1+1 && 2 == 4-2)
(equals (add 1 1) 3)
 -> 0


less-than

New in Tiki14.1 and Tiki12.5: Checks whether the first value is less than the second.

Examples
(less-than 3 (add 2 2) )
 -> 1
(less-than (add 2 2) 3)
 -> 0


more-than

New in Tiki14.1 and Tiki12.5: Checks whether the first value is more than the second.

Examples
(more-than 3 (add 2 2) )
 -> 0
(more-than (add 2 2) 3)
 -> 1


if

Conditionally evaluates a branch.

Examples
(if (equals 2 2) 42 -1)
 -> 42
(if (equals 2 1) 42 -1)
 -> -1


and

Ensures all elements evaluate to true.

Examples
(and 3 2 1 2 3)
 -> 1
(and 2 3 0 2)
 -> 0


or

Ensures that at least one element evaluates to true. Elements are evauated sequentially until a false element is found. Others are left unevaluated.

Examples
(or 3 2 1 2 3)
 -> 1
(or 2 3 0 2)
 -> 1
(or 0 0)
 -> 0


hash

Generates a hash based on multiple values. Used primarily to generate aggregate hashes in the Activity Stream. Note that because it is a hash, the exact value coming out does not matter. Only that given the same parameter, it will produce the same value.

Examples
(hash 1)
 -> [sha1("1")]
(hash 1 2 3 4)
 -> [sha1("1/2/3/4")]
(hash 1 2 (map (a 3) (b 4)))
 -> [sha1("1/2/3/4")]


avg

Calculates the average of multiple values. All entries in the list will be flattened if arrays are present.

Examples
(avg 1 2 3)
-> 2
... given list contains [1, 2, 3]
(avg list)
-> 2


split-list

Produces a multi-dimensional array out of a text string. Each line is expected to be an independent value, each line will be split by a separator into the specified keys.

Examples
... given str contains a list of 3 comma-separated values
(split-list
    (content str)
    (separator ,)
    (keys a b c))
-> [{a: 1, b: 2, c: 3}, {a: 2, b: 3, c: 4}]


for-each

For a list of value pairs, such as the output of split-list, evaluates a formula for each set of values, returns the list of results.

Within the formula, variables coming from the list will be used first. Fallback will be on the other variables available in the execution context.

As of Tiki18, list items can be the output of ItemsList tracker field where individual formula fields are the linked fields from the other tracker. See example below.

Examples
... given items contains [{a: 1, b: 2, c: 3}, {a: 2, b: 3, c: 4}]
(for-each
    (list items)
    (formula (mul a b c)))
-> [6, 24]

... given items contains [{a: 1, b: 2, c: 3}, {a: 2, b: 3, c: 4}]
... and d contains 10
(for-each
    (list items)
    (formula (mul c d)))
-> [30, 40]

... given trackerDetails is an ItemsList field pointing to another tracker with a field detailsAmount
... and particular tracker item has 2 linked items with detailsAmount = 30 and 40
(add
    (for-each
        (list trackerDetails)
        (formula (concat detailsAmount))))
-> 70
This formula sums the detailsAmount column from the other tracker for all items linked from this tracker's item.


Not

New in Tiki14: https://sourceforge.net/p/tikiwiki/code/53590

IsEmpty

New in Tiki14: https://sourceforge.net/p/tikiwiki/code/53588

date

New in Tiki14.1: https://sourceforge.net/p/tikiwiki/code/55964

Takes two optional arguments, format and timestamp and uses the PHP date function. See here for reference. Format defaults to "U" which is the Unix timestamp, and the timestamp defaults to "now".

Date Examples
(date)
> Returns "1438358437" currently

(date (str Y-m-d H:i:s))
> Returns "2015-07-31 17:00:43" currently

(date (str r) theTimeAndTheDate)
> Returns "Tue, 16 Jun 2015 09:23:09 +0100" for instance, where theTimeAndTheDate is the permanent name of a tracker field in the same tracker.


pad

New in Tiki15 committed in r57094

Takes two to four arguments, input string, output length, padding string (defaults to a space) and padding type (defaults to right)
See http://php.net/manual/en/function.str-pad.php for more info.

This example right pads prices in a simple products tracker for sorting and filtering
(pad
    productsPrice
    8
    (str 0)
    (str left)
)



Advanced Rating-specific Reference

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.


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]


tracker-field

Pulls information from the tracker item. The field value is converted to numeric value automatically. Zero is provided if the value is not found or unapplicable.

Examples
(tracker-field 
  (object type object-id) 
  (field priority)
)
    -> [value contained in the tracker item field with permanent name ''priority'']


category-present

Gives 1 in score of every listed category present on the object.
Examples
(category-present
  (object type object-id)
  (list 3 4)
)
    -> [0, 1 or 2 - Depending on how many of categories 3 or 4 are on the object]


Appendix

When unified search is used, recalculation can be configured to be done during re-indexing, removing the need for this script.

Cron job
<?php

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

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

$ratinglib->refresh_all();


Sample and use case


Calculate date difference to set if tracker item is new or not

In this use case we compare a field that contain creation date to the actual date and if the difference is lower than 7 days (604800) the field will have the value "new" else "notnew".

Examples
(if(equals (more-than 604800 (sub (add (date) 0) (add dateDeCrAtion 0))) 1) (str new) (str notnew))


Simple Wiki Ratings



Related


alias
Advanced+Rating | AdvancedRating | Advanced Ratings | AdvancedRatings


doc.tiki.org


Bootstrap

AdminGuide

UserGuide

Keywords

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

Accessibility (WAI and 508)
Accounting (7.x)
Articles and Submissions
Backlinks
Banners
Batch (6.x)
BigBlueButton audio/video/chat/screensharing (5.x)
Blog
Bookmark
Browser Compatibility
Link Cache
Calendar
Category
Chat
Clean URLs
Comments
Communication Center
Compression (gzip)
Contacts (Address Book)
Contact us
Content Templates
Contribution (2.x)
Cookie
Copyright
Credit (6.x)
Custom Home and Group Home Page
Date and Time
Debugger Console
Directory of hyperlinks
Documentation link from Tiki to doc.tiki.org (Help System)
Docs 8.x
Draw 7.x
Dynamic Content
Dynamic Variable
External Authentication
FAQ
Featured links
File Gallery
Forum
Friendship Network (Community)
Gmap Google maps
Groups
Hotword
HTML Page
i18n (Multilingual, l10n, Babelfish)
Image Gallery
Import-Export
Install
Integrator
Interoperability
Inter-User Messages
InterTiki
Kaltura video management (4.x)
Karma
Live Support
Login
Logs (system & action)
Look and Feel
Lost edit protection
Mail-in
Map with Mapserver
Menu
Meta Tags
Mobile Tiki and Voice Tiki
Mods
Module
MultiTiki
MyTiki
Newsletter
Notepad
Payment
Performance Speed / Load
Permissions
Platform independence (Linux-Apache, Windows/IIS, Mac, BSD)
Polls
Profiles
Profile Manager
Report
Toolbar
Quiz
Rating
Feeds
Score
Search engine optimization
Search
Search and Replace
Security
Semantic links (3.x)
Shadowbox
Shadow Layers
Share
Shopping cart
Shoutbox
Slideshow
Smiley
Social Networks
Spam protection (Anti-bot CATPCHA)
Spellcheck
Spreadsheet
Stats
Surveys
Tags (2.x)
Task
Tell a Friend, alert + Social Bookmarking
TikiTests (2.x)
Theme CSS & Smarty
Trackers
Transitions (5.x)
TRIM
User Administration including registration and banning
User Files
User Menu
Watch
WebHelp
WebDAV (5.x)
Webmail
Web Services
Wiki 3D
Wiki History, page rename, etc
Wiki Page Staging and Approval (2.x)
Wiki Plugin extends basic syntax
Wiki Syntax
Wiki structure (book and table of content)
Workspace
WSOD
WYSIWYCA
WYSIWYG (2.x)
XMLRPC


Tiki Newsletter

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