Ratings Plugin

Last modified by Vincent Massol on 2024/07/05 18:09

starA plugin to handle ratings of wiki documents
TypePlugin
Category
Developed by

Ludovic Dubost, Jerome

Rating
LicenseGNU Lesser General Public License 2.1

Description

This plugin is deprecated for newer version of XWiki (4.1+) and is replaced by the Ratings API which is component-based instead of being a plugin.

This plugin can be used together with the Ratings Application version 1.2 or less. 

Configuration

Supported parameters :

xwiki.cfg parameter key (XWiki.XWikiPreferences field name)DescriptionAccepted valuesDefault value
xwiki.ratings.ratingsmanagerThe fully qualified name of the class to be used as rating managercom.xpn.xwiki.plugin.ratings.internal.DefaultRatingsManager
com.xpn.xwiki.plugin.ratings.internal.SeparatePageRatingsManager
xwiki.ratings.averagerating.stored (ratings_averagerating_stored)Is the average rating stored in a XWiki object ?0 or 10
xwiki.ratings.reputation (ratings_reputation)Is user reputation feature activated ?0 or 10
xwiki.ratings.reputation.stored (ratings_reputation_stored)Is user reputation stored in a XWiki object ?0 or 10
xwiki.ratings.reputation.defaultmethod (ratings_reputation_defaultmethod)name of the methods used for calculating a user reputation. In the user profile, one object per calculation method will be stored, each one referencing the name of the method used.Coma-separated list of methodsaverage
xwiki.ratings.reputation.classnameThe default algorithm class to use for calculating user reputationThe fully qualified name of the class to be used as reputation algorithmcom.xpn.xwiki.plugin.ratings.internal.DefaultReputationAlgorythm
xwiki.ratings.reputation.groovypage (ratings_reputation_groovypage)The fullname of a document that contains an implementation of a reputation calculation algorithm written in groovyNone
xwiki.ratings.separatepagemanager.spacename (ratings_separatepagemanager_spacename)The name of the space to use to store ratings documents/objects when using the sepearate-page ratings managerThe name of the space to be usedNone (uses the same spaces as the page being rated)
xwiki.ratings.separatepagemanager.hasratingsforeachspace (ratings_separatepagemanager_hasratingsforeachspace)Should the separate page ratings manager use a space for each of the rated space?0 or 10

API

/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package com.xpn.xwiki.plugin.ratings;

import com.xpn.xwiki.XWikiContext;
import com.xpn.xwiki.api.Document;
import com.xpn.xwiki.plugin.PluginApi;
import com.xpn.xwiki.plugin.ratings.Rating;

import java.util.List;
import java.util.ArrayList;

/**
 * @version $Id$
 */
public class RatingsPluginApi extends PluginApi<RatingsPlugin>
{
    public RatingsPluginApi(RatingsPlugin plugin, XWikiContext context)
    {
        super(plugin, context);
    }

    protected RatingsManager getRatingsManager()
    {
        return getRatingsPlugin().getRatingsManager(context);
    }

    protected RatingsPlugin getRatingsPlugin()
    {
        return ((RatingsPlugin) getProtectedPlugin());
    }

    protected static List<RatingApi> wrapRatings(List<Rating> ratings, XWikiContext context)
    {
        if (ratings == null) {
            return null;
        }

        List<RatingApi> ratingsResult = new ArrayList<RatingApi>();
        for (Rating rating : ratings) {
            ratingsResult.add(new RatingApi(rating, context));
        }
        return ratingsResult;
    }

    public RatingApi setRating(Document doc, String author, int vote)
    {
        // TODO protect this with programming rights
        // and add a setRating(docName), not protected but for which the author is retrieved from context.
        try {
            return new RatingApi(getRatingsPlugin().setRating(doc.getFullName(), author, vote, context), context);
        } catch (Throwable e) {
            context.put("exception", e);
            return null;
        }
    }

    public RatingApi getRating(Document doc, String author)
    {
        try {
            Rating rating =
                getRatingsPlugin()
                    .getRating(doc.getFullName(), author, context);
            if (rating == null) {
                return null;
            }
            return new RatingApi(rating, context);
        } catch (Throwable e) {
            context.put("exception", e);
            return null;
        }
    }

    public List<RatingApi> getRatings(Document doc, int start, int count)
    {
        return getRatings(doc, start, count, true);
    }

    public List<RatingApi> getRatings(Document doc, int start, int count, boolean asc)
    {
        try {
            return wrapRatings(getRatingsPlugin().getRatings(doc.getFullName(), start, count, asc, context), context);
        } catch (Exception e) {
            context.put("exception", e);
            return null;
        }
    }

    public AverageRatingApi getAverageRating(Document doc, String method)
    {
        try {
            return new AverageRatingApi(getRatingsPlugin().getAverageRating(doc.getFullName(), method, context),
                context);
        } catch (Throwable e) {
            context.put("exception", e);
            return null;
        }
    }

    public AverageRatingApi getAverageRating(Document doc)
    {
        try {
            return new AverageRatingApi(getRatingsPlugin().getAverageRating(doc.getFullName(), context), context);
        } catch (Throwable e) {
            context.put("exception", e);
            return null;
        }
    }

    public AverageRatingApi getAverageRating(String fromsql, String wheresql, String method)
    {
        try {
            return new AverageRatingApi(getRatingsPlugin().getAverageRating(fromsql, wheresql, method, context),
                context);
        } catch (Throwable e) {
            context.put("exception", e);
            return null;
        }
    }

    public AverageRatingApi getAverageRating(String fromsql, String wheresql)
    {
        try {
            return new AverageRatingApi(getRatingsPlugin().getAverageRatingFromQuery(fromsql, wheresql, context),
                context);
        } catch (Throwable e) {
            context.put("exception", e);
            return null;
        }
    }

    public AverageRatingApi getUserReputation(String username)
    {
        try {
            return new AverageRatingApi(getRatingsPlugin().getUserReputation(username, context), context);
        } catch (Throwable e) {
            context.put("exception", e);
            return null;
        }
    }
}

Prerequisites & Installation Instructions

Follow these steps:

  • Add the JAR in your container classpath (WEB-INF/lib)
  • Edit xwiki.cfg and add the following line to the list of plugins :
    xwiki.plugins=\
          [...]
           ... ,\
         <plugin package>
  • Restart your container
  • Verify the plugin is properly installed by typing the following in a wiki page :
    {{velocity}}
    $xwiki.<plugin name>.name
    {{/velocity}}

    If the installation has been successful, you will see <plugin name>.


For this plugin replace:

  • <plugin package> by com.xpn.xwiki.plugin.ratings.RatingsPlugin
  • <plugin name> by ratings

Release Notes

v1.2

  • Fixed a NPE when using the default ratings manager
  • By default average rating should be stored

v1.1

Changed the default ratings manager for the one that stores ratings object on the same page as the document being rated (was a rating manager that stores rating object in different pages).

Get Connected