Rater plugin

PluginRater
Description Plugin for rate and vote functionality.
Type syntax
Author Taggic
Last update 2014-02-04
DW compatible 2011-05-25 (Rincewind), 2011-11-10 (Angua), 2012-10-13 (Adora Belle)
Depends none
Conflicts none
Similar stars
Download https://github.com/Taggic/rater/archives/master
Issues fcon - Rater issues

Rating

Rate Rater
 stars  (8 votes)

Voting

(3) (0)



Intro

This is a very simple plugin that will allow the inclusion of single or multiple Star Rating or Voting Systems on one page.
The rating details within an expandable box answering how many visitors vote per star level.
It utilises small text files to store it's required information instead of a database. It also delivers a configurable ip voting
restriction and the ability to set how many times a single ip may vote.

To see the plugin in action please visit: Rater examples

Installation

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin.
Refer to Plugins on how to install plugins manually.

Or just download and extract it as folder “rater” into your “\lib\plugins” directory.

:!: External requirements:

  • none

Attention !

The update to version 2011-09-27 needed a change in ”.rating” file names. To reuse the former ”.rating” files please change the filenames in ”…/data/meta”-directory according following concept:

old filename format converted filename
rater_[ID][NAME][TYPE].rating rater_[ID]_[NAME]_[TYPE].rating
rater_1test1rate.rating rater_1_test1_rate.rating

.











Configuration and Settings

Configuration of rater plugin can be done easily.

  1. Log in as administrator into DW
  2. click on Admin action link to open the Admin tools
  3. change to Configuration Settings
  4. jump to Rater Plugin Settings to adjust the options.

The following can be configured:

Item default value
restrict ip address voting true
allowed user votes 1
Exceeded user rate attempts msg You have already rated this item. You were allowed %s vote(s).
Missing rate value msg You have not selected a rating value.
Thank you for msg Thank you for voting.
generic item text this item
end of line character (OS specific) \n

There is also a css file but it is related to thumb output only.

Examples/Usage

Attention !

Please take care that the identifiers like   item1   must not contain space characters ! Instead of a space use an underline if needed (i.e.   item_1  ).





5 Star Rating

This delivers a picture of 5 stars and radio buttons below to rate. The rating will be countet and stored to a file at …dat/meta/*.rating
The code base is picked up from PHP, 5 Star Rating System \\ (using hReview) as mentioned within forum post Rating plugin.

Rate item321
 stars  (91 votes)
{(rater>id=1|name=item1|type=rate)}

Voting

This delivers up/down thumbs to vote for a certain topic.

(273) (239)(details)
{(rater>id=1|name=item1|type=vote|tracedetails=1)}

Rater Statistic

Flam & Loleg asked for a statistic feature to see a list of all rater of a site sorted by highest rate. This is now implemented and the following syntax will deliver it (see also Examples). There are no more parameter necessary.

{(rater>type=stat)}

The list layout can be customized within style.css. The list shows the Star rater first and the Voting below, all sorted according their value. The list shows only rater objects currently referenced on pages. Orphan rater object files cannot be detected (currently). Rater syntax inside code blocks will be ignored.

Syntax

The following line contains all parameters and possible values:

{(rater>id=1|name=item1|type=rate/vote/stat|trace=user/ip|end=09/25/10 / 25.09.2011|tracedetails=0/1|headline=off/on|rater_hdl=test)})}
  • Following parameters:
    • id              — mandatory, unique — an id to differ between the rate/vote (no need for stat)
    • name         — mandatory, unique — usually the item name what will be voted/rated (no need for stat)
    • type           — mandatory            — defines of rate, vote or stat use case
    • trace          — optional                — can be set to user or ip, where user is to be preferred for closed wikis
    • end            — optional                — defines the end date of the rate/vote action, can be any valid date expression
    • tracedetails — optional                — can be 0 or 1 and defines if the rate or vote details will be displayed
                                                        (:!: vote + tracedetails will display real user name or its ip
                                                           ⇒ be carefully with this combination)
    • headline      — optional                — off/on
    • rater_hdl     — optional                — a free-text headline to substitute that defined in language.php

It is allowed to place more than one rate/vote function into the same page but I don't know about the performance impacts if you will place there hundreds.

Development

Recent releases

Known Bugs and Issues

Please use Rater Issues to report a problem.

Change Log

Date Changes
soon
Id Created Product Version Severity Status Title Resolution
2014-02-04 BugFix: - (#208) language corrections
2014-01-06 NewFeature: - Dutch language file added
BugFix: - (#205) Rater headline hardcoded
2012-10-28 BugFixes:
     - (#155) stat box not display the IP of the voters
     - (#154) disturbing blue message boxes after voting
2012-10-22 NewFeature: - make stat table sortable
BugFix: - issue #149
2012-10-17 secure that 'eol_char' is not empty
2012-09-21 rater top-line syntax switch added, css for rater styling extended
2012-06-03 Statistic improved to also display votes
Statistic does now ignore rater syntax within code blocks
2011-12-16 BugFix: Vote details link prevented if tracedetails switched off
2011-09-26 handle end of vote periods
2011-09-26 trace user real names instead of ip (e.g. for closed wiki to prevent problem of temporary ip)
2011-09-26 text output customizable by language files
2011-09-27 output statistic of all rate items
2011-10-05 rater as element of namespace templates

FAQ

1. Can I use multiple rater on the same page ?

Yes, of course. The rater plugin allows you as many as you want. Therefore you have to define by syntax unique id's. All 3 parameters will be used together as filename.

2. Where are the information stored to ?

All information are stored into files. So you don't need to use a database. The files are within the \dokuwiki\data\meta folder and have a suffix .rating . The filename containing the id, item and type parameter from syntax.
Example:
The syntax {(rater>id=1|name=issuetracker|type=vote)} cause information storage to a file named rater_1_issuetracker_vote.rating .

3. Can I change the Style ?

Currently the style of rate details expandable box and statistic layout can be customized by style.css stored in the rater plugin folder. How to use css and what parameter are possible is explained many times by articles in the internet (e.g. W3C school).

The rating-details-css defaults are

.rating__details {
	border:        1px #BDBEC1 solid;
	font-size:                0.85em;
	text-align:                right;
	background-color:        #F2F2F2;
	padding-right:              10px;
	padding-left:               10px;
	margin-left:              0.75em;
	margin-right:             0.75em;
	border-radius:               5px;
	box-shadow:         3px 3px #666;
}

4. There are more rate attempts possible than configured

That is the case if you have set trace=ip. Web provider may give their users dynamic ip's, changing per day. For closed wiki you could use the trace=user option where the real user name is logged.

5. Former results disappeared after rater plugin update

The update to version 2011-09-27 needed a change in ”.rating” file names. To reuse the former ”.rating” files please change the filenames in ”…/data/meta”-directory according following concept:

old filename format converted filename
rater_[ID][NAME][TYPE].rating rater_[ID]_[NAME]_[TYPE].rating
rater_1test1rate.rating rater_1_test1_rate.rating

6. How to use rater as part of namespace template ?

This is possible by using following syntax within your __template.txt file. It is better to use the ID replacement pattern instead of PAGE to prevent mismatch of file names caused by multiple same named pages in different namespaces.

{(rater>id=1|name=@ID@|type=rate|trace=ip)}

Further information on namespace templates can be found here ...

7. What to be done on explode-warnings ?

If you click to rate/vote and following Warnings appear:

Warning: explode() [function.explode]: Empty delimiter in ....../wiki/lib/plugins/rater/syntax.php on line ...
Warning: Invalid argument supplied for foreach() in ...../wiki/lib/plugins/rater/syntax.php on line ...
Warning: Division by zero in ...wiki/lib/plugins/rater/syntax.php on line ...

This explains that the data strings cannot be split into the necessary parts due to a configuration setting is empty. Therefore please check your plugin settings via Configuration Manager. The related parameter is 'eol_char'. This should be set to '\n'.

Future Versions (beyond 2012-09-21) will set this parameter to default '\n' if configuration attribute is empty.

Discussion

Please use only the DokuWiki Forum for discussion and Rater - IssueTracker to report incidents, ask questions or for new features.

rater/descr.txt · Last modified: 2014/04/30 09:36 (external edit)

This Wiki is hosted and ruled by Policies of Frister Consultancy Services.
By using this wiki you accept these rules. -> Impressum