Extension:Semantic Rating

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
Semantic Rating

Release status: stable

Implementation User interface, Parser function
Description Adds a Semantic Forms input type to allow users to enter a star rating in a form by clicking on the stars; also adds three parser functions to display a star rating.
Author(s) Cindy Cicalese (cindy.cicalesetalk)
Latest version 2.2 (2014-11-11)
MediaWiki 1.21+
PHP 5.3+
Database changes No
License MIT License
Download
Parameters

SemanticRating_DefaultMax

Hooks used
ParserFirstCallInit

Translate the Semantic Rating extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

Issues:

Open tasks · Report a bug

The Semantic Rating extension adds a Semantic Forms input type to allow users to enter a star rating in a form by clicking on the stars. It also adds three parser functions to display a star rating:

  • #rating: displays a rating inline
  • #ratingBeforeTitle: displays a rating to the left of the title at the top of the page
  • #ratingAfterTitle: displays a rating to the right of the title at the top of the page

The parser functions are capable of displaying empty (gray), full (yellow), and half stars.

By default, the #ratingBeforeTitle and #ratingAfterTitle parser functions will insert the rating in the title at the top of a page for any skin that puts the title in an HTML element with id firstHeading such as the default Vector skin. This can be changed for other skins using the $SemanticRating_CSSSelector configuration variable. This approach can also be used to have the rating appear at other places in the page by using a <div> and appropriate choice of $SemanticRating_CSSSelector.

Special thanks to Bernadette Clemente for the original idea that inspired this extension and to Kelly Hatfield for an early implementation of this extension.

Installation[edit | edit source]

Note Note: This extension requires Semantic MediaWiki and Semantic Forms to be installed first.

vagrant>Vagrant</>, install with <tvar

  • <translate>

1>download-link</> and place the file(s) in a directory called <tvar|name>SemanticRating</> in your <tvar|ext>extensions/</> folder.</translate>

  • <translate>

Add the following code at the bottom of your LocalSettings.php:</translate>

require_once "$IP/extensions/SemanticRating/SemanticRating.php";

Navigate to <tvar|special>Special:Version</> on your wiki to verify that the extension is successfully installed.</translate>code>wfLoadExtension( 'SemanticRating' );</>, you need to use:</translate>

require_once "$IP/extensions/SemanticRating/SemanticRating.php";

Configuration[edit | edit source]

Flag Default Description
$SemanticRating_DefaultMax 5 Holds the default value for the maximum value of a rating (that is, the total number of stars that will be displayed). If the maximum value is not explicitly set in a form field or parser function invocation, SemanticRating_DefaultMax will be used.
$SemanticRating_CSSSelector "#firstHeading" Specifies the CSS selector that will be used to locate the page title. The Vector skin uses #firstHeading. The Foreground skin uses h2.title.

Release Notes[edit | edit source]

Version 2.2[edit | edit source]

  • Added $SemanticRating_CSSSelector and updated coding style.

Examples[edit | edit source]

Defining a Field in a Semantic Form[edit | edit source]

The following will add an input field with the default maximum number of stars:

{{{field|Rating|input type=rating}}}

The maximum number of stars can be set explicitly with the max parameter:

{{{field|Rating|input type=rating|max=10}}}

Displaying a Rating[edit | edit source]

The following displays a 3 star rating inline using the default maximum number of stars:

{{#rating:3}}

If the default maximum is 5, it will display 3 yellow stars and 2 gray stars. If the default maximum is 10, it will display 3 yellow stars and 7 gray stars.

To explicitly set the maximum number of stars to 10, use the following:

{{#rating:3|10}}

To display the rating at the top of the page with the page title instead, use (again with an optional maximum value):

{{#ratingBeforeTitle:3}}

or

{{#ratingAfterTitle:3}}

Displaying a Rating Using a Template Parameter[edit | edit source]

For the form field defined in the example above, the value of the rating will be passed into the template associated with the form field as a named paramter. Because the form field is given the name Rating, that will be the name of the paramter as well. Therefore, in the template, the rating can be displayed as:

{{#rating:{{{Rating|}}}}}

Displaying a Number as a Five Star Rating[edit | edit source]

Display of examples for the Semantic Rating extension

Displaying the Result of a Semantic Query as a Five Star Rating[edit | edit source]

Below are several more advanced examples that illustrate how this extension can be used.

Consider the case where users can review a wiki page. In this example, each review is itself a wiki page in category Reviews. Each review page has a property, Item, that is a link to the page being reviewed. Each review page also has a property, Rating, that has a value between 1 and 5 (with 0 being reserved for the case where no rating is assigned).

On the page being reviewed, the page's average rating can be displayed by the following query:

{{#rating:{{#ask:[[Category:Reviews]][[Item::{{FULLPAGENAME}}]]|?Rating|format=average}}}}

Further, assume that each page being reviewed has a property, Author, pointing to a page for the author of the page being reviewed. On the author's page, using the ParserFunctions and Arrays extensions, the average rating for all pages authored by that author (an average of the average page ratings) can be displayed by the following:

{{#arraydefine:
  ratings
  |{{#arraymap:
    {{#ask:[[Author::{{FULLPAGENAME}}]][[Category:Items]]|link=none}}
    |,
    |@@@@
    |{{#ask:[[Item::@@@@]][[Category:Reviews]]|?Rating|format=average}}
  }}
}}
{{#rating:{{#expr:{{#expr:{{#arrayprint:ratings|+}}}}/{{#arraysize:ratings}}}}}}