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 ↩

Building a triangle toggler in YUI

2008-02-25T00:00:00-08:00

If someone knows the more common name for triangle-toggle menu's similar to this. Let me know.

There is a widget where an element toggles the display of a secondary set of elements. The toggle shows an arrow pointing down or right depending on the visibility of the elements. I wanted to build that in YUI.

The problem is two-fold:

Build a triangle that toggles from right to down.
Show and hide content.

However, with some clever CSS we can do this all in a single class change on an element.

Build that triangle

There's a number of ways to show or hide this triangle. Because it is flexible, I'm going to opt for using a background image. Also to save on HTTP requests, I'll use a sprite-d image. This may get merged with other icons on the system.

The particular site I'm working on uses a black background with white text, therefore a white triangle toggle seems appropriate.

This is what I use. I leave a little space, because the background will only clip horizontally based on the size of the element.

Add the HTML/CSS

The following HTML:

and the following CSS:

Provide the two states we require for the triangle. If you are new to sprites, rather than changing the background image entirely we just shift the background image up or down appropriately to show a new background.

The Javascript

The javascript is rather simple, but we put in some magical tricks here and there.

If you're unfamiliar with this style of Javascript, here's what's going on. Everything is done in the MA namespace as to not conflict with other javascript.

The toggler is fairly generic and expects a similar HTML structure for any toggle-able element. That means this code only needs to be written once, and anytime we use the toggle class, toggling in this fashion will occur.

We only run the init function. init says when the DOM is available then run the setup function. setup adds an event handler to doc4. doc4 just happens to be the id we use on our body tag.

Note that we're listening for clicks everywhere. This means we have to define only one event handler, regardless of how many toggle-able items there are. The event handler checks to make sure we clicked on a relevant element and then applies the toggle function to the grandparent element (switching the class from off to on as appropriate).

Note that this style of event handling means you need to carefully apply your class names. Also note, that this code could be optimized a little bit more, I haven't put this code into production, and therefore haven't optimized it for the YUI compressor.

Try this out if you want, I'm sure it can be trimmed down overtime. If you have trouble with it, let me know.

-d

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.

Table based layouts? In this day in age? Really? How about grids?

2007-10-05T00:00:00-07:00

[tags]css, yui, grids, table, layout[/tags]

I think there are three kinds of people:

People who learned tables for layouts and went to CSS+divs.
People who learned tables for layouts and never needed to learn CSS+divs (or insisted that this was way too complicated)
People who never learned tables.

I would argue in some ways the second class of people are right, tables are a lot easier. Until you run into issues... and until you need to maintain your template code.

Luckily there's grids. Grids are easier than tables and easy to maintain and look at. You can achieve just about anything with grids.

Personally I like using Yahoo's YUI to get grid support. It's a CSS framework in the same way that jQuery is a javascript framework or that symfony is a PHP5 framework.

YUI will normalize all your elements and give you a standard way to change the size of text and elements and give you grids.

So it helps to think of your layout in terms of grids... or columns. YUI grids supports some common combinations:

.yui-g - 2 equal size containers (nest to get 4).
.yui-gb - 3 equal size containers
.yui-gc - 2/3 - 1/3
.yui-gd - 1/3 - 2/3
.yui-ge - 3/4 - 1/4
.yui-gf - 1/4 - 3/4

Granted, this doesn't cover every scenario, but it's a start, and it's easy to build off of to create your own special sizes.

So to create some magical columns you do the following:

yui-g can be substituted for any of the above classes. yui-u is your columns or grid cells. first indicates the first column since :first isn't understood by some popular browsers.

Now you know grids. It's less complicated than the tabular equivalent:

With the framework in place, it's a lot easier to quickly adjust your layouts, and the readability is huge especially as your layouts grow.

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 ;)

resetting CSS list items

2007-09-01T00:00:00-07:00

[tags]css, symfony, blueprint, yui[/tags]

Call me a purist, but I really believe that Blueprint should go the extra step as YUI (note: I'm a YUI CSS user dabbling in Blueprint) does and reset list items as well. It's all about how you use your elements and what you consider as resetting, but I feel that a bullet added to a list is something that should be removed in a proper reset.css file.

Different browsers are going to have their own ways of rendering bullets and really the developer should explicitly inform us how they would like their lists rendered.

Personally, most of my list items are lists of links as in menus, which require no bullets usually. This is probably the source of my bias.

sfBlueprintPlugin: Train of thought development

2007-08-30T00:00:00-07:00

I've been creating some dummy projects for my presentations at SymfonyCamp and decided now would be a good time to learn using the Blueprint CSS framework. It's a bit different than YUI which I've been using heavily, but it has some potential.

Of course, instead of just downloading the framework, I made a plugin for symfony. It's not much yet, but eventually I'll throw in some helpers.

Enjoy!

[tags]css, symfony, blueprint, plugins, symfony camp, camp, yui[/tags]

Textmate Snippets for YUI em calculations

2007-05-08T00:00:00-07:00

[tags]yui, yahoo, css, snippet, textmate, ems, px[/tags]

If you use YUI grid layouts you'll notice that ems are the preferred units and for good reason. But ems don't make sense to people like us who want to be super precise down to the pixel... pixels make sense.

So type in a number select it and run this ruby script as a TextMate command (that outputs as a snippet):

You'll have the proper tab stops to change the newly calculated ems from width to margin-left or margin-right or whatever it is you desire.

TextMate + YUI = YUI snippets!

2007-04-30T00:00:00-07:00

I do a lot of YUI grid layouts and I love the nestable grids:

<div class="yui-g$1"> 
    <div class="yui-u first">
        $2
    </div>
    <div class="yui-u">
        $3
    </div>
</div>

There's a tab stop after yui-g in case you want to use one of the variants (yui-gb, yui-gc, etc).

I'm working on a site that uses two equal width columns... a lot... so this comes in quite handy. So long tables.