Dave Dash

Star Rating using YUI (and Django)

2008-03-04T00:00:00-08:00

I have a very good star rater on reviewsby.us, but it was written using some sloppy prototype code. I wanted to redo star raters in a well thought out manner and I wanted to use YUI. In this particular tutorial I will use Django although it is not a requirement.

For some background information on star raters, see this Yahoo! Design Pattern. Our pattern is more of a join star rater, similar to what's found on Netflix: you see an average rating for a restaurant or dish unless you yourself have rated it.

This was a thought out design decision for our reviewsby.us redesign. Our site is primarily a personal utility that answers the question, "What dishes do I like at a particular restaurant?" If you haven't rated something the website can only offer up an average and you can use that as a decision as to whether you should eat something or not.

If you have eaten something however, that average rating is irrelevant. You don't need fellow meal advisors to tell you that you liked Chicken Makhani, you already know that for yourself. Therefore we show only your rating unless you haven't rated something.

Working backwards

I like to "work backwards" as it were. Meaning, I like to just write the code that I ultimately will use to output a star rater. From there I will work on the supporting code that is necessary. I find by using this strategy, I can keep my code fairly clean and organized.

The template

So ultimately I want this:

{\% star 'mything' 3 4 '/path/to/script' %}

To show up as this:

Unfortunately Django templates doesn't seem to have named attributes for template tags, so I'll need to explain my syntax:

star: is the template tag which we define below
'mything': is an id string we will use for this rater and its associated objects
3: this is the second argument to star, it will be the users current rating, it can also be None
4.1: this is the third argument, it will be the average rating, it can also be None
/path/to/script: is the form that will process our rating

The HTML we want

Another developer had a good approach for handling star ratings and for handling Javascript in general. Create an underlying Javascript-free system, and then let the Javascript make it pretty. This is way to degrade gracefully.

Ultimately, I had my own approach to this problem, I wanted much of the visual lifting to happen on the CSS layer. So, we'll use the following code:

<span class="joint_star_rater"> <form id="rater_restaurant" method="post" action="/restaurant/pizza-luce/rate/"> <fieldset> <legend>Rating</legend> <ul> <li style="width: 100px;" title="5" class="current meta">Current Rating: 5</li> <li title="Poor" class="star_1 star"> <label for="restaurant_rating_1">Poor</label> <input type="radio" name="rating" value="1" id="restaurant_rating_1"/> </li> <li title="Fair" class="star_2 star"> <label for="restaurant_rating_2">Fair</label> <input type="radio" name="rating" value="2" id="restaurant_rating_2"/> </li> <li title="Good" class="star_3 star"> <label for="restaurant_rating_3">Good</label> <input type="radio" name="rating" value="3" id="restaurant_rating_3"/> </li> <li title="Very Good" class="star_4 star"> <label for="restaurant_rating_4">Very Good</label> <input type="radio" name="rating" value="4" id="restaurant_rating_4"/> </li> <li title="Excellent" class="star_5 star"> <label for="restaurant_rating_5">Excellent</label> <input type="radio" name="rating" value="5" id="restaurant_rating_5"/> </li> </ul> </fieldset> <input type="submit" name="rate" value="rate it" class="submit"/> </form> </span>

A couple things to note in our HTML. Our unique string is restaurant. It's got an ID that is as unique as you want: rater_restaurant where restaurant was the first argument to our template tag. We use restaurant to create some other unique IDs as well.

Also, this rating form makes a lot of sense semantically. While this form in its current state is a far cry from some ajaxy goodness, it makes clear sense as to what is going on.

The template tag

Well we know what we want from the HTML side, so let's start coding our star tag:

@register.simple_tag def star(id_string, current, average, path, spanfree=False): meta = None if current != None: meta = """ <li class="current meta" title="%d" style="width:%dpx">Current Rating: %d</li> """ % (int(current), int(current)*20, int(current)) else: meta = """ <li class="average meta" title="%.1f" style="width:%dpx">Average Rating: %.1f</li> """ % (average, average*20,average) stars = '' ratings = ['Poor', 'Fair', 'Good', 'Very Good', 'Excellent'] for i in range(1,6): stars = stars + """ <li class="star_%d star" title="%s"> <label for="%s_rating_%d">%s</label> <input id="%s_rating_%d" type="radio" value="%d" name="rating"/> </li> """ % (i, ratings[i-1],id_string, i, ratings[i-1], id_string, i, i) html = """ <form action="%s" method="post" id="rater_%s"> <fieldset> <legend>Rating</legend> <ul> %s %s </ul> </fieldset> <input type="submit" class="submit" value="rate it" name="rate"/> </form> """ % (path, id_string, meta,stars) if spanfree: return html else: return """<span class="joint_star_rater">%s</span>""" % html return html

The CSS

A lot of work will happen via CSS. The CSS will remove quite a bit of the textual data that can be interpreted graphically with stars.

The strategy we use is to:

fix the UL at a certain width with a background of grey stars
decorate the LI.average and LI.current with repeating stars (blue and orange respectively) with a z-index of 1
decorate the LI.average:hover and LI.current:hover with a transparent background
decorate LI:hover input as a colored in star and a z-index of 2

This might not make sense now, until you see the CSS in full action. Also for the stars we'll use a sprite of 3 stars. A grey defunct star as the default background, a blue star if it's the average rating for an item and an orange star if it's what the user wants.

I use the following sprite:

The following CSS will do some magic:

.joint_star_rater {display:inline-block;} .joint_star_rater ul{width:100px;position:relative;height:20px;background:url(../images/icons/stars.png) repeat-x 0 0} .joint_star_rater li.meta{position:absolute;text-indent:-9999px;display:block;z-index:1;} .joint_star_rater ul:hover li.meta{display:none;} .joint_star_rater li.current{background:url(../images/icons/stars.png) repeat-x 0 -40px} .joint_star_rater li.average{background:url(../images/icons/stars.png) repeat-x 0 -20px} .joint_star_rater li{height:20px;width:20px;position:absolute;text-indent:-9999px;z-index:3;} .joint_star_rater li.star_2{left:20px;} .joint_star_rater li.star_3{left:40px} .joint_star_rater li.star_4{left:60px} .joint_star_rater li.star_5{left:80px} .joint_star_rater li.star_1:hover{width:20px} .joint_star_rater li.star_2:hover{width:40px} .joint_star_rater li.star_3:hover{width:60px} .joint_star_rater li.star_4:hover{width:80px} .joint_star_rater li.star_5:hover{width:100px} .joint_star_rater li.star:hover{background:url(../images/icons/stars.png) repeat-x 0 -40px;z-index:2;left:0;} .joint_star_rater input.submit{display:none;}

The inline-block value for display is not supported very well. I recently switched to Firefox 3 Beta and it renders as expected. Firefox 2 has problems with it. I may revise the CSS later to accommodate it.

The Javascript

The fundamental drawback to the design here, is that it really only works well with the Javascript on. In fact, with the CSS on and Javascript off, this code will not work very well for the end user. This too will be revised in the future.

Our Javascript needs to do something very simple: * extract the star value you clicked on * send it to the server * redraw the stars

It's a very simple operation, but I honestly think other libraries have an advantage to YUI in this regard.¹ Here's some unobtrusive code I came up with:

Note: I intentionally left out irrelevant pieces of code, like the function definition of MA.is_authenticated(), this code isn't meant for cutting and pasting, it's meant for cutting-pasting and then some careful editing.

The callback view

The callback script is what you specify when you call {\% star ... %}. The view I use is as follows:

@login_required def rate(request, slug): MyObject = get_my_object() value = request['value'] MyObject,rate(value); return render_to_response("rating.html", locals(), context_instance=RequestContext(request))

That code is oversimplified... you have to write your own logic as it applies to our site. The rating.html is simply the call to your star tag:

{\% load tags %}
{\% star 'mything' restaurant.current_rating restaurant.average_rating restaurant.get_rating_url 1 %}

Note the 1 at the end. It's a flag to turn off the outer span so we can just insert the guts back into the original span.

Final Thoughts

The star-rater is really a large problem that's hard to tackle in one sitting and quite frankly is not documented well anywhere. The code I've provided is a shadow of the real code I'll be using, but hopefully it's enough to get you started.

I definitely will update my production code to solve a few outstanding issues, as I mentioned above. I'll try to update this tutorial at the same time. If there are questions about the examples given, feel free to ask and I'll attempt to answer.

YUI has the Selector and that might alleviate some problems, but jQuery has very nice selection capabilities. In this future version I keep promising, I'll use the YUI Selector ↩

YUI Autocomplete the easy way

2008-01-27T00:00:00-08:00

[tags]yui, autocomplete, javascript, jquery, symfony[/tags]

I'm redoing the UI for reviewsby.us and for the Javascript library I am standardizing on is YUI. The trick with YUI is that it's very verbose and very configurable.

Unfortunately to do simple things you have to write quite a lot. Which, coming from a jQuery background, is not what I'm used to. Yahoo provides a lot of useful examples for Auto Complete, I'll provide you with another (built in symfony, but anything in any server-side language will work). You'll need:

A data source
Some YUI
Some javascript of your own
And some HTML

We're building a tool to grab random items from our database and put them into our Autocomplete field. We also want to capture and id of these items and set them in our form.

Here we go...

Data Source

YUI gives you a lot of options with data sources. In many cases a remote script that returns JSON will be best. JSON is nice, compact, human debuggable and machine-readable.

We can make a searchJSON method that simply takes your database results and wraps them in to a formatted array and then using PHP's json_encode we can return a nice JSON object.

The ResultSet and Result keys are important as we'll see later.

We can serve this JSON method very easily in symfony like so:

Note that we use renderText rather than a separate ajaxListSuccess.php file.

YUI

There's some YUI code that you need. It's described well in the Autocomplete documentation.

Add the following to your page:

http://yui.yahooapis.com/2.4.1/build/yahoo-dom-event/yahoo-dom-event.js" type="text/javascript
http://yui.yahooapis.com/2.4.1/build/connection/connection-min.js type="text/javascript
http://yui.yahooapis.com/2.4.1/build/autocomplete/autocomplete-min.js
http://yui.yahooapis.com/2.4.1/build/autocomplete/assets/skins/sam/autocomplete.css

These are the bare YUI requirements to get Autocomplete working.

Javascript

There's a good deal of Javascript that you'll need to provide on your own. Here's what I wrote:

var MA = {};
    MA.autocomplete = function()
    {
      var e = YAHOO.util.Event;
      var w = YAHOO.widget;
  
      return {
        init: function()
        {
           e.onAvailable("myInput", this.fnHandler);
        },
        fnHandler: function()
        {
          var rDS = new w.DS_XHR("/ajax/object/list", ["ResultSet.Result","Title"]);

rDS.maxCacheEntries    = 60; 
          rDS.queryMatchContains = true;

var rAC = new w.AutoComplete("myInput","myACContainer", rDS);

rAC.formatResult = function(item, query) 
          {
            return item[1].Title;
          };
      
          rAC.forceSelection           = true; 
          rAC.allowBrowserAutocomplete = false; 
      
          rAC.itemSelectEvent.subscribe(
            function(sType, aArgs) 
            { 
              var data = aArgs[2];
              document.getElementById("object_id").value = aArgs[2][1]['Id'];
            }
          ); 
        },
    
      }
    }();

MA.autocomplete.init();

MA is my own private namespace. /ajax/object/list is the url of our data source we defined earlier. myInput, myACContainer and object_id are all IDs of elements in our DOM which we'll look at next.

HTML

Okay I went through this backwards, now we have the HTML.

This is all you need:

The End

That's it. It might seem like a lot, but YUI offers a tested working solution that works and is very customizable.

ddJQueryCalendarPlugin plugin for symfony released

2007-09-20T00:00:00-07:00

[tags]JQuery, jq, javascript, js, JQuery Calendar, calendar, symfony, plugin[/tags]

I released a new symfony plugin today for the jQuery Calendar available via svn. Feel free to read about it on trac. This adds a clever calendar widget that can trigger events. Very handy for viewing an events calendar.

I'll publish a link to this plugin in action in the following weeks. Enjoy.

jQuery shortcut functions and jQuery plugins

2007-09-15T00:00:00-07:00

[tags]js, javascript, readability, yui, jquery, shortcuts[/tags]

One of the the things that's kept me away from the YUI javascript libraries is longhand. Or rather, the appeal to jQuery (and Prototype) was the almight $ shorthand.

Of course there are times when it pays to write in long hand. Marc Grabanski has written a fantastic calendar plugin which uses a lot of jQuery shorthand. $(), $.extend and whatnot are great for quick code, but disaster when you need to be in maximum compatibility mode. For example, use jQuery with some other libraries and you can get disaster. It's better to opt for the long-hand jQuery and jQuery.extend methods. After some search and replaces, I may have gotten things right, but I think I need to talk to Marc Grabanski and make sure the changes I made make sense.

So remember, long hand is great when other developers are using stuff and namespace conflicts are afoot ;)

Equal height columns with jQuery

2007-05-22T00:00:00-07:00

[tags]css, jQuery, layout, javascript, equal, columns, equal columns[/tags]

I've seen a few examples of how to equalize column heights using javascript, and none of them seem appealing:

jquery.equalizecols.js
- This required a few other libraries, and I wanted more flexibility (e.g. where the column should grow in order to equalize)
Project 7
- The Project 7 approach was the most interesting, but the code seemed a bit messy and not so open source friendly (even thought it might have been). It would let you specify which element was to grow inside a column.
Nifty Corners
- I had trouble with the syntax, but I liked how it just created a new element out of thin air...

So I wrote my own:

$("#col1, #col2").equalizeCols();

will equalize the columns as expected

$("#col1, #col2").equalizeCols("p,p");

will equalize the columns and add the extra space after the p tag in #col1 or #col2 (whichever is shorter).

Here's our function:

This requires jQuery of course, and it hasn't been tested much.

Making anchor links smarter... and sexier

2007-02-14T00:00:00-08:00

So I have a small bone to pick with Jacob Nielsen and his opinion on within-page links or anchor links^.1 There clearly is a benefit to not just linking to a specific page, but linking to a specific part of a page.

With a little help from script.aculo.us we can spice up our anchor links by highlighting them as well as linking to them.

For this article we'll limit our scope to internal anchors only.² We'll write the code using the symfony framework and in straight up XHTML. This is really dirt simple and is more of a design pattern with an example than a tutorial.

Let's do the XHTML first:

Yup, that's it... I told you it was dirt simple. You just need to include the proper prototype and script.aculo.us libraries.

In symfony we avoid repeating ourselves with a helper function:

and call it by doing:

That's it.

Jacob Nielsen is an easy target. ↩
Anchors on other pages are equally useful. To implement that, you need to have an event listener to examine the URL for an anchor and appropriately highlight the correct element. ↩

How to make Prototype Window Class as easy as Lightbox Gone Wild

2006-11-13T00:00:00-08:00

I like the way that Lightbox Gone Wild will automatically pickup any links with the class=lbOn, but I wanted to use (at some point) Prototype Window Class instead.

Luckily PWC is built on Prototype which means we've already loaded a helpful library.

In order to take all class=lbOn objects and run them through PWC we just write a simple loop and iterate.

So here's the low-down:

Download PWC
Copy window.js
Use the included prototype & script.aculo.us if you don't already include it in your page
copy any themes you wish to use.

In your page add this bit of JavaScript:

So, this code simply looks for all the anchor tags with class=lbOn and then creates a new mylb instance for each anchor. The end.