Page last modified 12:58, 6 May 2011 by neilw

User:neilw > Templates and Extensions > DekiScript Star Rater

DekiScript Star Rater

1. Description
2. Requirements
3. Version
4. How to Install
5. Parameters
6. A note about security and related matters
1. 6.1. Security
2. 6.2. Reliability
3. 6.3. Scalability
7. Examples
8. Credits

TEMPLATEDOC WARNING: documentation URL in template 'StarRater' does not point to this page (should be 'http://developer.mindtouch.com/User:neilw/Templates_and_Extensions/DekiScript_Star_Rater')

Description

Simple DekiScript-based Star Rater, either for page ratings or anything else you want to rate. It is inherently insecure, so it is only recommended for light-duty, non-critical usage.

Requirements

MindTouch 10.0 or later.
You must attach the star.gif file to your template page.

Version

Version	Date	Author	Description
1.00b	6-May-2011	Neil Weinstock	First "official" release

How to Install

These instructions will help you install the template'StarRater' on your wiki quickly and correctly.

Perform the following steps:

Copy the template source code:
1. If the code in the "HTML Source" area below is not already visible and selected, click the "View" button to display and select it.
2. Copy it to your clipboard (CTRL-C).
Create a new template on your wiki:
1. Select the Tools->Templates menu item on your wiki
2. Click "New Page" button. This will open the editor on a new page with the title "Template:Page Title".
3. Replace "Page Title" with the name of the template.
Paste in the source code:
1. In the editor, click the "View->Source" menu item to view the HTML source of the page.
2. Select all text (CTRL-A).
3. Paste in the template source code from the clipboard (CTRL-V).
Click "Save" button.

HTML Source for Template:StarRater

  <div id="templateSelfDocumentation" if="false" style="padding:5px; border: 2px dotted black;"> <h2>Documentation</h2> <p>This box includes basic usage information for this template.  When calling the template, this documentation will not appear.  Functional template code should be placed <em>outside</em> the dotted box.</p> <h3>Summary</h3> <table border="1" cellspacing="0" class="summary" style="border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-width: 1px; border-style: solid; width: 100%; margin-bottom: 10px;"> <tbody> <tr class="description"> <td style="background-color: rgb(255, 204, 153); width: 175px;"><strong>Template Description</strong></td> <td>Simple DekiScript-based Star Rater, either for page ratings or anything else you want to rate.  It is inherently insecure, so it is only recommended for light-duty, non-critical usage.</td> </tr> <tr class="requirements"> <td style="background-color: rgb(255, 204, 153);"><strong>Requirements</strong></td> <td> <ul> <li>MindTouch 10.0 or later.</li> <li><strong>You must attach the <a title="http://developer.mindtouch.com/@api/deki/files/7031/=star.gif" href="/@api/deki/files/7031/=star.gif">star.gif</a> file to your template page.</strong></li> </ul> </td> </tr> <tr class="docPage"> <td style="background-color: rgb(255,204,153);"><strong>Documentation URL</strong></td> <td>http://developer.mindtouch.com/App_Catalog/StarRater_-_A simple_DekiScript-based_star_rater_for_light-duty_use</td> </tr> <tr class="discussionPage"> <td style="background-color: rgb(255,204,153);"><strong>Discussion URL</strong></td> <td> </td> </tr> </tbody> </table> <h3>Version History</h3> <p>Place newest version at the <em>top </em>of the table.</p> <table border="1" cellspacing="0" class="versions" style="border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-width: 1px; border-style: solid; width: 100%; margin-bottom: 10px;"> <colgroup> <col width="100px" /> <col width="125px" /> <col width="150px" /> </colgroup> <thead> <tr> <th scope="col" style="background-color: rgb(255,204,153)"><strong>Version</strong></th> <th scope="col" style="background-color: #ffcc99"><strong>Date</strong></th> <th scope="col" style="background-color: #ffcc99"><strong>Author</strong></th> <th scope="col" style="background-color: #ffcc99;"><strong>Description</strong></th> </tr> </thead> <tbody> <tr> <td>1.00b</td> <td>6-May-2011</td> <td>Neil Weinstock</td> <td>First "official" release</td> </tr> </tbody> </table> <h3>Template Parameters</h3>
<table border="1" cellspacing="0" class="parameters" style="border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-width: 1px; border-style: solid; width: 100%; margin-bottom: 10px;"> <thead> <tr> <th style="background-color: rgb(255, 204, 153); width:150px"><strong>Name</strong></th> <th style="background-color: rgb(255, 204, 153); width:100px"><strong>Type</strong></th> <th style="background-color: rgb(255, 204, 153); width:150px"><strong>Default</strong></th> <th style="background-color: rgb(255, 204, 153); "><strong>Description</strong></th> </tr> </thead> <tbody> <tr> <td>property</td> <td>str?</td> <td>"star_data"</td> <td> <p>Name of the property in which the voting data will be stored.  If you plan to have multiple StarRaters on a page, you should assign each one a unique property name to avoid collisions, otherwise, just leave this blank.</p> <p>The ID of the page is always tacked onto the end of the property name, so you can safely store the ratings data from multiple pages in the same page, without collision.</p> </td> </tr> <tr> <td>msg</td> <td>str?</td> <td> <p>&lt;none&gt; or</p> <p>"Rate this page:" if page==true</p> </td> <td>This is the little "please vote" message that gets placed above the stars.  If this is not specified, and page==true (see below), this value will default to "Rate this page:".  If the current user does not have voting rights, then the message is not displayed</td> </tr> <tr> <td>page</td> <td>bool?</td> <td>false</td> <td> <p>Page mode.  This is a convenience for when you use this as a page rating mechanism.  If true, then two things happen:</p> <ol> <li>The star rater is floated to the right</li> <li>The message (if not specified above) defaults to "Rate this page:"</li> </ol> </td> </tr> <tr> <td>path</td> <td>str?</td> <td>page.path</td> <td>Path of the page where the voting data property will be stored.</td> </tr> </tbody>
</table>
</div>
<h2 if="false">Template Code</h2>
<h3 if="false">Unsafecontent Permission Check</h3>
<pre class="script">
// This code checks if the template is properly installed for unsafe content execution,
// and may be removed if this check is not desired.  If you leave this here, add your new code
// in a new DekiScript block below this one.
var thisTemplate = wiki.inclusions()[-1];
if (!wiki.pagepermissions(thisTemplate.id, thisTemplate.author.id).unsafecontent)
  &lt;div style="color:red; width:75%; padding:5px; border:1px solid red;"&gt;
    "WARNING: The page '"..thisTemplate.path.."' must be re-saved by a user with UNSAFECONTENT permission in order to work correctly. ";
    &lt;a href="http://developer.mindtouch.com/en/kb/Using_templates_which_require_UNSAFECONTENT_permission"&gt; "See this" &lt;/a&gt;;
    " for more info."; 
  &lt;/div&gt;;
</pre>
<h3 if="false">Parameter Processing</h3>
<pre class="script">// Arg processing
var errors = [];

// prop:  name of property used to store ratings data
var prop = ($0 ?? $property ?? "star_data") .. "_" .. page.id;
var table = "table_" .. prop;

// msg:   message to put above star rater
var msg  = $1 ?? $msg;

// page:  "page rating" mode, which floats the rater to the right and auto-populates
//        the "Rate this page:" message if necessary
var pageMode = $2 ?? $page ?? false;
if (pageMode &amp;&amp; msg is nil) let msg = "Rate this page:";

// path:  path of page on which to store property
var path = $3 ?? $path ?? page.path;

// Fetch page used as data store
var p = page;
if (path != page.path) {
    let p = wiki.getpage(path);
    if (p == nil) let errors ..= [ "can't find page with data store" ];
}

// Fetch the current vote data
var data = json.parse(p.properties[prop].text ?? '{}');
if (data is not map) {
    let errors ..= [ "star rating data store has wrong type ('"..typeof(data).."') instead of 'map')" ];
    let data = {};
}
var num_votes = #data - (data[prop] != nil ? 1 : 0);

// Fetch current rating
var rating = data[prop] ?? 0;
if (rating is not num) {
    let errors ..= [ "current results have wrong type ('"..typeof(rating).."' instead of 'num')" ];
    let rating = 0;
}
else
    let rating = num.round(rating, 1);

// can the current user vote?
var can_vote = !user.anonymous &amp;&amp; wiki.pagepermissions(path).update;
</pre>
<h3 if="false">Output Generation</h3>
<pre class="script">// Must have dekiapi extension installed!
dekiapi();

// Image must be attached to this template
var imgURI = thisTemplate.files["star.gif"].uri;

&lt;html&gt;
&lt;head&gt;
//
// CSS and Javascript
//

// CSS-based rating UI
&lt;style type="text/css"&gt; "
#page-top .star-rater td { margin: 0px; padding: 0px; }
#page-top .star-rating,
#page-top .star-rating a:hover,
#page-top .star-rating a:active,
#page-top .star-rating a:focus,
#page-top .star-rating .current-rating {
    background: url("..imgURI..") left -1000px repeat-x;
}
#page-top .star-rating {
    position:relative;
    width:125px;
    height:25px;
    overflow:hidden;
    list-style:none;
    margin:0;
    padding:0;
    background-position: left top;
}
#page-top .star-rating li { display: inline; }
#page-top .star-rating a,
#page-top .star-rating .current-rating {
    position:absolute;
    top:0;
    left:0;
    text-indent:-1000em;
    height:25px;
    line-height:25px;
    outline:none;
    overflow:hidden;
    border: none;
    margin:0;
    padding:0;
}
#page-top .star-rating a:hover,
#page-top .star-rating a:active,
#page-top .star-rating a:focus { background-position: left bottom; }
#page-top .star-rating a.star1 { width:20%; z-index:6; }
#page-top .star-rating a.star2 { width:40%; z-index:5; }
#page-top .star-rating a.star3 { width:60%; z-index:4; }
#page-top .star-rating a.star4 { width:80%; z-index:3; }
#page-top .star-rating a.star5 { width:100%;z-index:2; }
#page-top .star-rating .current-rating { z-index:1; background-position: left center; }
#page-top .star-rating a:active { outline: none; } // remove halo effect in FireFox
" &lt;/style&gt;;

// Initialize Display
&lt;script type="text/javascript"&gt; "
    $(function() { starRaterDisplayUpdate('"..table.."', "..rating..", "..num_votes.."); });
" &lt;/script&gt;;

// Set display based on current rating
&lt;script type="text/javascript"&gt; "
    function starRaterDisplayUpdate(id, rating, votes) {
        var $starRater = $('#'+id);
        $starRater.find('.current-rating').css('width',(20*rating)+'%').text('Currently '+rating+'/5 stars');
        $starRater.find('.current-status').text(rating+'/5 stars ('+votes+' vote'+(votes != 1 ? 's)':')'));
        $starRater.find('a').each(function() { this.blur(); });
    }
" &lt;/script&gt;;

// Code to update the page properties, largely cribbed from SteveB's "UpdateStore" template
&lt;script type="text/javascript"&gt; "
    Deki.subscribe('"..@channel.."', null, function(c, m, d) {
        var store_data = '"..prop.."';
        var api_uri = '"..p.api.."';
        var property = 'urn:custom.mindtouch.com#'  + store_data;
        Deki.Api.ReadPageProperty(api_uri, property,
          function(result) {
            var data = eval('(' + (result.value || '{}') + ')');
            for (var k in m) if (k != '_id_') data[k] = m[k];
            var id = m['_id_'];
            var total = 0;
            var num_votes = 0;
            for (var k in data) {
                if (k != store_data) {
                    ++ num_votes;
                    total += Number(data[k]);
                }
            }
            var current_rating = Math.round(10*(num_votes ? total/num_votes : 0))/10;
            data[store_data] = current_rating;
            if(result.etag)
                Deki.Api.UpdatePageProperty(result.href, YAHOO.lang.JSON.stringify(data), result.etag,
                    function() { starRaterDisplayUpdate(id, current_rating, num_votes); },
                    function(result) { alert('Error updating store (status: '+result.status+' - '+result.text+')'); }
                );
            else
                Deki.Api.CreatePageProperty(api_uri, property, YAHOO.lang.JSON.stringify(data),
                    function() { starRaterDisplayUpdate(id, current_rating, num_votes); },
                    function(result) { alert('Error creating store (status: '+result.status+' - '+result.text+')'); }
                );
          },
          function(result) { alert('An error occurred reading the store (status: '+result.status+' - '+result.text+')'); }
        );
    }, null);
" &lt;/script&gt;;
&lt;/head&gt;;

&lt;body&gt;
//UI Table
&lt;table class="star-rater" id=(table) border="0" cellpadding="0" cellspacing="0"
    style=("padding:0px; margin:3px;" .. (pageMode ? "float:right;" : ""))&gt;&lt;tbody&gt;
    if (can_vote)
        &lt;tr&gt;&lt;td align="center" style="font-size: small;"&gt; msg &lt;/td&gt;&lt;/tr&gt;;
    &lt;tr&gt;&lt;td align="center"&gt;&lt;ul class='star-rating'&gt;
        &lt;li class='current-rating'&gt; &lt;/li&gt;
        if (can_vote)
            foreach (var i in [1,2,3,4,5])
                &lt;li&gt;&lt;a href='#' title=(i.." star out of 5") class=("star"..i)
                    onClick=("Deki.publish('"..@channel.."', {'_id_':'"..table.."','"..user.name.."':"..i.." });")&gt;
                    i
                &lt;/a&gt;&lt;/li&gt;;
    &lt;/ul&gt;&lt;/td&gt;&lt;/tr&gt;;
    &lt;tr&gt;&lt;td class='current-status' align="center" style="font-size: x-small"&gt; &lt;/td&gt;&lt;/tr&gt;;
&lt;/tbody&gt;&lt;/table&gt;;

&lt;/body&gt;;
&lt;/html&gt;;
</pre>

Parameters

Name	Type	Default	Description
property	str?	"star_data"	Name of the property in which the voting data will be stored. If you plan to have multiple StarRaters on a page, you should assign each one a unique property name to avoid collisions, otherwise, just leave this blank. The ID of the page is always tacked onto the end of the property name, so you can safely store the ratings data from multiple pages in the same page, without collision.
msg	str?	<none> or "Rate this page:" if page==true	This is the little "please vote" message that gets placed above the stars. If this is not specified, and page==true (see below), this value will default to "Rate this page:". If the current user does not have voting rights, then the message is not displayed
page	bool?	false	Page mode. This is a convenience for when you use this as a page rating mechanism. If true, then two things happen: The star rater is floated to the right The message (if not specified above) defaults to "Rate this page:"
path	str?	page.path	Path of the page where the voting data property will be stored.

A note about security and related matters

The description above includes a disclaimer that states that this is intended for "light, non-critical use". There are three reasons for this: security, reliability, and scaleability.

Security

The page property used to store the ratings data must be updatable by the user. That means that the user is free, if he or she wishes, to go and mess with out. Most users neither know how to do this nor care, but the bottom line is that these ratings are inherently insecure, and that is a prime reason for the "non-critical" recommendation.

You can improve your situation a bit by locating the property (using the path argument) on a separate page. That gives you the option of protecting the page containing the ratings, although you may not always want this.

Finally, I have (for now) put the property into the namespace where it is accessible by going to the "Set Page Properties" page from the "More" menu. This makes it much easier to see what's going on (including seeing who voted how), and also to delete the property if you want to reset the ratings. This makes it easier to go in and hack the ratings. If folks want, I'll add an option one day to put the property into a "hidden" namespace, where it'll be more resistant to casual hackers, but also more difficult to go and fix if problems arise.

Reliability

If a lot of folks are trying to update the ratings at the same time, it'd probably be pretty easy to cause updates to fail. This won't bring down the system (or even corrupt the ratings), but it will cause error messages to show to the user. This is because the data storage method does not really support a proper atomic read/modify/write operation.

Also, this has been tested on a good number of browsers, but browser incompatibility is always a possibility. If so, please report the problem to the forum thread.

Scalability

This template has not been tested when a very large number of people vote. I don't know if it'll run into problems or not. It shouldn't, but you never know!

Examples

The page rater at the top right corner of the page is done like this:

StarRater{page:true};

Its data is stored in the "star_data" property (which you can see if you go to view the page properties for this page).

Here's a non-page version with a custom message:

StarRater("docs", "Rate the documentation:");

This one also uses a different property name, to avoid colliding with the page rating.

You get the idea!

Credits

The Star Rater CSS is based on the Komodo CSS Star Rater.

Tag page
What links here

Files 0

Attach file or image

Images 0
No images to display in the gallery.

DekiScript Star Rater

Table of contents

Description

Requirements

Version

How to Install

Parameters

A note about security and related matters

Security

Reliability

Scalability

Examples

Credits

Files 0

Table of contents

Login or Join Community

DekiScript Star Rater

Table of contents

Description

Requirements

Version

How to Install

Parameters

A note about security and related matters

Security

Reliability

Scalability

Examples

Credits

Files 0

Table of contents