DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== Rate Plugin ======

---- plugin ----
description: a simple rate and vote syntax plugin
author     : Taggic 
email      : Taggic@t-online.de
type       : syntax
lastupdate : 2015-03-14
compatible : Rincewind, Angua, Adora Belle, Weatherwax, Binky, Hrun
depends    : 
conflicts  : 
similar    : stars
tags       : rate, rating, vote
screenshot_img: http://www.fristercons.de/fcon/data/media/rater/raterdescr.png
downloadurl: https://github.com/Taggic/rater/zipball/master
bugtracker : http://www.fristercons.de/fcon/doku.php?id=rater:issues
sourcerepo : https://github.com/Taggic/rater
donationurl: 
----

===== 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 its 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: [[http://www.fristercons.de/fcon/doku.php?id=rater:example|fcon- Rater examples]]

===== Installation =====
Install the plugin using the [[plugin:plugin|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 [[https://github.com/Taggic/rater/archives/master|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: \\

===== Configuration and Settings =====
Configuration of rater plugin can be done easily. 
  - Log in as administrator into DW 
  - click on Admin action link to open the Admin tools 
  - change to Configuration Settings 
  - jump to Rater Plugin Settings to adjust the options.

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

===== Syntax =====
The following line contains all parameter and possible values:
<code>
{(rater>id=1|name=item1|type=rate/vote/stat/localstat|trace=user/ip|end=09/25/10 / 25.09.2011|tracedetails=0/1|img= :taggic.png|zoom=30x30|headline=off/on|rater_hdl=test)})}
</code>

=== Parameters ===

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

===== 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 counted and stored to a file at ...dat/meta/*.rating \\ 
The code base is picked up from [[http://2008.gr0w.com/articles/code/php_5_star_rating_system_using_hreview/index.php|PHP, 5 Star Rating System \\ 
(using hReview)]] as mentioned within forum post [[http://forum.dokuwiki.org/thread/1662|Rating plugin]].
<code>
{(rater>id=1|name=item1|type=rate)}
</code>

=== Voting === 
This delivers up/down thumbs to vote for a certain topic. 
<code>
{(rater>id=1|name=item1|type=vote)}
</code>

=== Images inside ===
<code>
{(rater>id=1|name=Ein schräg schöner Übermorgen|img= :taggic.png?45% |type=vote)}
</code>
The image is included inside the rater box and zoomed at 45% of its original size. To handover the image the beginning of the media link is used without curly brackets and pipe extension. Special charachters are handled if the replacements are prvided within lang.php file.

=== Rater Statistic ===
Flam & Loleg asked for a statistic feature to see a list of all raters 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. From "Adora Belle" onwards the list can be sorted by click on column header.
<code>
{(rater>type=stat)}
</code>
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.

If you want to consider just the rater objects of the same page then use following syntax:
<code>
{(rater>type=localstat)}
</code>

If you want to have the statistic of a dedicated namespace ten use the ns-option. All rater objects of the ns rater:tst will be considered (incl. sub-namespaces, if existing).
<code>
{(rater>id=7|type=stat|ns=rater:tst)}
</code>

If you specify a dedicated page then you will have the same result as localstat but you can call it from a different page somewhere in your DokuWiki. Please take care to append the <color blue>.txt</color> that the plugin knows you refer to the page file.
<code>
{(rater>id=7|type=stat|ns=rater:tst:ratertest.txt)}
</code>

Furthermore if you provide a zoom option like for media links, then the lit will contain thumbnails of that size of the rater objects (if immages provided inside the box).
The zoom parameter decides if thumbnails will be displayed and what size. 
__**Take care:**__
  - No zoom Option = no thumbs !
  - No rates/votes no entry !
  - No Image within rater box = no thumbs !
So think about the usage and style that it will not that being crauted like following table:
<code>
{(rater>id=66|type=localstat|zoom=30x30|sid=on|sort=value|)}
</code>

===== Development =====
=== Change Log ===

=== Known Bugs and Issues ===

[[http://www.fristercons.de/fcon/doku.php?id=rater:issues]]

=== ToDo/Wish List ===

//[developers roadmap]//

===== Sites using this Plugin =====

You got this plugin up and running? You have got a demo page? Put a link here! \\ 
Feel free to add yours here:
  * [[http://www.fristercons.de/fcon/doku.php?id=rater:example|fcon - Rater Examples]]
  * [[http://fanartwii.com/doku.php|Fanarts for wii. The rater plugin is used for the votes of the fanarts]]
  * http://www.visual-novel.de
  * [[http://pe.hillschmidt.de|Prinz Eisenherz Wiki (Prince Valiant)]]
  * http://www.simplepedia.de
===== Discussion =====

Please use only the DokuWiki Forum for discussion and [[http://www.fristercons.de/fcon/doku.php?id=rater:issues|Rater issues]] to raise your problems. You can mention it here but this page is not regularily tracked and if something is solved it will be cleaned from this page (better to use the forum due to automated notifications).

===== FAQ =====

a small but most recent FAQ is provided at: [[http://www.fristercons.de/fcon/doku.php?id=rater:descr&#faq|Rater plugin - 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. [[http://www.w3schools.com/css/default.asp| W3C School/CSS]]).

The rating-details-css defaults are \\ 
<code css>
.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;
}
</code>

=== 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]**<color red>_</color>**[NAME]**<color red>_</color>**[TYPE].rating |
| rater_1test1rate.rating | rater_1**<color red>_</color>**test1**<color red>_</color>**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.
<code>
{(rater>id=1|name=@ID@|type=rate|trace=ip)}
</code>
Further information on namespace templates can be found [[doku>namespace_templates|here ...]]

==== Use with URL rewrite ====
If the instance you are using this plugin with is set up to do [[:rewrite|URL Rewriting]] (Option 1: via Web server) you will get redirection issues when it comes to a user clicking on the vote button as the code is set to always start with ''doku.php?id=''. To workaround this change the following lines:

''action.php'' Line ∼171 to:

<code php>
echo '<meta http-equiv="refresh" content="2; URL='.$_SERVER['REDIRECT_URL'].'#'.$anker_id.'"><div class="thumb__positive_feedback">'.$rater_ip.' : '.$rater_msg.'<br />'.
'<a href="'.$_SERVER['REDIRECT_URL'].'#'.$anker_id.'" />'.$alink_Back.'</a></div>';
</code>

''syntax.php'' Line ∼351 to:
<code php>
$ret .= $addMSG.'<a class="thumbup tup" href="?do=rate_voteup&rater_id='.$rater_id.'&rater_ip='.$rater_ip.'&rater_end='.$data['rater_end'].'&anker='.$anker_id.'&rater_name='.$rater_name.'"></a>'.
'<span id="vote1_1" style="color:#5b8f22">('.$vote1.')&nbsp;</span>'.
'<a class="thumbdown tdn" href="?do=rate_votedown&rater_id='.$rater_id.'&rater_ip='.$rater_ip.'&rater_end='.$data['rater_end'].'&anker='.$anker_id.'&rater_name='.$rater_name.'"></a>'.
'<span id="vote1_2" style="color:#FF1822">('.$vote2.')</span>';
</code>

Please fill all the letters into the box to prove you're human. C H D X C Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International