API to rate wiki pages

Description

The Ratings API allows to store and retrieve various kind of Ratings on different elements of XWiki. The API have been designed in order to allow using different RatingsManagers for different purpose on the wiki, and with different meanings: e.g. Ratings pages on a scale [0,5], liking pages on a scale [0,1], Ratings xobjects on a scale [0,3], etc. 

Instantiate a RatingsManager

 

You need to use the dedicated RatingsManagerFactory in order to instantiate a RatingsManager with the proper initialization. You only need to specify the name of the manager you would like to use. You can provide a RatingsConfiguration component with the same name as hint: this configuration will be used for the initialization, else a default configuration will be used. 

Storage

 

The Ratings API manipulate and store two kind of entities: 

• Ratings: the votes performed by people
• Average Ratings: an average vote computed on all ratings performed on the same entity

Storage of Ratings

 

Ratings are always stored in a Solr Core. By default, all ratings for any manager are stored in the same Solr Core, however it's possible to specify in the configuration to store the Ratings of a specific manager in a dedicated core. 

Storage of Average Ratings

Average Ratings can be stored in two places: in Solr Core, or as xobjects in the parent document of the rated entity. The default storage is as xobject.

Configuration

The RatingsConfiguration is used to initialize each RatingsManager and can be adapted uniquely to each usecase.

Events

The following events are automatically sent when using RatingsManager API. 

Ratings Events

CreatedRatingEvent

Sent when an event is created:

• source: the name of the RatingsManager which is responsible of sending the event
• data: the Rating object created

UpdatedRatingEvent

Sent when an event is updated:

• source: the name of the RatingsManager which is responsible of sending the event
• data: the Rating object updated

The event also contain the old vote before the Rating object has been updated.

DeletedRatingEvent

Sent when an event is deleted:

• source: the name of the RatingsManager which is responsible of sending the event
• data: the Rating object deleted

Average Ratings Events

UpdatingAverageRatingEvent

A begin event sent when an AverageRating is about to be updated:

• source: the name of the RatingsManager which is responsible of sending the event
• data: the AverageRating object updated

The event contains the data about the old average before the update, and the old total number of votes. 

UpdatedAverageRatingEvent

An end event sent when an AverageRating is successfully updated:

• source: the name of the RatingsManager which is responsible of sending the event
• data: the AverageRating object updated

The event contains the data about the old average before the update, and the old total number of votes. 

UpdateAverageRatingFailedEvent

An end event sent when an AverageRating failed to update:

• source: the name of the RatingsManager which is responsible of sending the event
• data: the AverageRating object updated

The event contains the data about the old average before the update, and the old total number of votes. 

Scripting

The Ratings Script Service allows to use the defined API for any RatingsManager by specifying its name on the form: $services.ratings.RatingsManagerName.
So if you have a dedicated RatingsManager named foobar, you'll be able to write velocity scripts such as:

#set ($myReference = ...)
#set ($ratings = $services.ratings.foobar.getRatings($myReference, 0, 10))

Note that if you don't specify any RatingsManager name, the script service will use by default the Ratings Application name.

The whole Script Service API is defined in AbstractScriptRatingsManager: 

Migration from old Ratings API (before 12.9RC1)

It has been decided to break the backward compatibility of the Ratings API of versions before 12.9RC1 in order to provide a better designed API and the ability to use this API for more use-cases. By default a migration of the existing Ratings data before 12.9RC1 are automatically performed when you upgrade your wiki. However if you used the Ratings API for some custom changes in your wiki, you might see some problems since some APIs have been broken: we will sum up here some of the breaking changes and how to fix them. 

User Reputation is missing

It has been decided to remove the User Reputation methods and classes: it is not clear for us what was the usecases for it, and the work was only partially done. If you're actually a user of such feature, please open a JIRA issue and we'll see how to introduce it back properly. 

Documents are now containing multiple Average Ratings xobjects

If you were manipulating directly the Average Ratings xobjects stored in the document, you now have to be a bit more careful: we store as many Average Ratings xobjects as they are RatingsManagers usecases. For example, if you have a wiki in which there is the standard Ratings Application and another extension using a RatingsManager for ratings comments, you might see two Average Ratings in your pages: one for the page ratings, and another one for the comments ratings. 

Note that you can easily distinguish them, by checking the dedicated managerId field.

RatingAPI class is missing and Script Service are returning optionals

The old Script Service API used to return RatingAPI class because the Rating class was actually doing too many things. We simplified this and now we only rely on the Rating class everywhere even in the Script Service. As much as possible we kept the same method names between RatingAPI and Rating classes: so Rating#getAuthor() and Rating#getVote() are still available. However note that Rating#getDate() doesn't exist another since we distinguish the creation date and the updated date, you can have look at Rating#getUpdatedAt() and Rating#getCreatedAt(). 

Finally note that we modernized the ScriptService API to use Java Optionals when needed instead of returning null: you might need to adapt your scripts to take it into account.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-ratings-api 18.8.0):

• org.xwiki.commons:xwiki-commons-component-api 18.8.0
• org.xwiki.platform:xwiki-platform-search-solr-api 18.8.0
• org.xwiki.platform:xwiki-platform-configuration-default 18.8.0