Progress Bar Examples - Ratings

The ProgressBar can be used within other widgets. Here we are using Yahoo! Query Language, YQL looking for Sushi restaurants in San Francisco, CA. and displaying the information in a YUI DataTable. We are showing some of the plain text fields as such, but for the ratings of the restaurants we are using the ProgressBar.

The Ratings from the query are being represented by YUI ProgressBars.

YQL allows to query some of YAHOO! vast databases using a language similar to SQL. The query for this examples is:

select Title,Address,Phone, Rating.AverageRating from local.search where query="sushi" and location="san francisco, ca"

which can be tested by pasting it into the YQL Console. YQL replies directly to an HTTP request with the search results either in XML or JSON format, this last being suitable to be used with the YUI Get utility. However, we are using a freely available subclass of YUI DataSource which handles the communication with YQL for us.

The code to build the DataTable on that query is:

var dt = new YAHOO.widget.DataTable( 'Container', [ {key:"Title", sortable:true}, {key:"Address", sortable:true}, {key:"Phone", sortable:true}, {key:"Rating.AverageRating", label:"Rating", formatter:ratingFormatter, sortable:true} ], new YAHOO.util.YQLDataSource(), { initialRequest:'select Title, Address, Phone, Rating.AverageRating from local.search where query="sushi" and location="san francisco, ca"' } );

We are drawing a simple DataTable with four columns, the first three of them, Title, Address and Phone are simple text fields that are displayed just as they are received. The fourth field is the one we are interested in. The query returns that field nested within the structure of each record. The property Rating is actually an object which contains several other properties and from those we choose AverageRating, thus, we use the composite field name Rating.AverageRating both in the query and in the key for the column definitions. Since that is not an acceptable label for the column header, we have to provide one and assign it a custom formatter. All columns are sortable, even the Ratings column.

The ratingFormatter is the one that will draw the ProgressBars:

var pbs = []; var ratingFormatter = function (elLiner, oRecord, oColumn, oData) { var pb = new YAHOO.widget.ProgressBar({ width:'100px', height:'20px', maxValue:5, className:'ratings', value:YAHOO.util.DataSource.parseNumber(oData) }).render(elLiner); pbs.push(pb); };

The core of it is the creation of the ProgressBar 100px wide and 20px hight because our star is in a square 20pixels on each side so that up to five stars will fit horizontally. Five is, indeed, the maxValue that the rating might reach. We add a className "rating" to the widget, which will help us with some formatting details and, finally, we set the current value for the progressBar to the new value for the cell, after converting it to a number. Unfortunately, YQL returns everything as strings.

Everytime the DataTable is sorted or redrawn for any reason, such as call to the render method or paging, the formatters will be called again. As with any widget, the ProgressBar might take resources that might not be automatically cleared by the garbage collector. It is vital to call method destroy to make sure all such resources are cleared. We push the ProgressBar instances created into the array pbs. To destroy those instances, we do:

dt.on('beforeRenderEvent',function() { for (var i = 0; i < pbs.length; i++) { pbs[i].destroy(); } pbs = []; });

Before any render, we make sure we destroy every instance we might have stored in the pbs array, if any.

The stars come from this single star which the ProgressBar tiles until it fills the allotted space. The style settings for this example is:

.yui-skin-sam .ratings { background:white none repeat 0 0; } .yui-skin-sam .ratings .yui-pb-bar { background: transparent url(star.png) repeat-x 0 0; }

We are using .yui-skin-sam .ratings as a selector in all the styles. We use the yui-skin-sam for basic skinning in all the page, including the DataTable, so we need to override some of its settings. We gave the ratings className to all the ProgressBars as one of the arguments in their instantiation. Since the star icon fades to white, we set the background to white. In the second definition, we set the background image for the bar itself to the star icon. We leave the borders that the SAM skin provides.