Pull Request for Issue # n/a.

Summary of Changes

This PR adds two new events to the Joomla core, which are triggered when a user votes for an article using the built-in star ratings system.

The events are named onRatingBeforeSave and onRatingAfterSave. Methods with these names can be added to any content plugin. As the names suggest, they are called immediately before and after the rating vote is saved.

Both methods have the same signature. Arguments are:

• $context - this is currently always 'com_content.article', but is provided to allow for future expansion.
• $id - the article ID that has been voted on.
• $user_rating - the score that the user gave the article.

If onRatingBeforeSave returns false then it will prevent the rating from being saved. No error message will be generated; it is up to the plugin to provide one.

If onRatingAfterSave returns false, then it will suppress the default success message. This allows the plugin to provide its own alternative message.

Motivation

I wrote this PR after realising that the built-in star ratings system was somewhat limited. For example, it only stores the single most recent IP address that voted, so it would be very easy for someone to vote an unlimited times simply by alternating their IP.

This PR provides a way for these limitations to be overcome without having to overhaul the existing system. Plugins can now be used to give additional validation. It also gives the possibility of logging votes, reporting on votes, emailing content authors "someone has voted on your article!", providing more detailed messages after voting (eg "thank you. you are the 12th person to vote on this article today").

Testing Instructions

A simple plugin to test this could look like this:

class plgContentRatingsTest extends JPlugin
{
    public function onRatingBeforeSave($context, $id, $rate)
    {
        if ($rate == 5) {
            // Prove that it works by not allowing a score of 5.
            JFactory::getApplication()->enqueueMessage("Sorry, this content isn't good enough; you can't give it top marks.", 'error');
            return false;
        }
        return true;
    }

    public function onRatingAfterSave($context, $id, $rate)
    {
        // Just override the default message.
        JFactory::getApplication()->enqueueMessage('Good news! Your vote has been recorded!', 'message');
        return false;
    }
}

Documentation Changes Required

The new methods should be documented with the other content plugin methods.