Managing a star rating with the StarRating widget in Yii 2

You are viewing revision #6 of this wiki article.
This is the latest version of this article.
You may want to see the changes made in this revision.

« previous (#5)

In Yii 1.x, there was a built in widget CStarRating based on the jquery star rating plugin. There exists no prebuilt solution in Yii2, however the same concepts can be extended using any jquery plugin.

The only limitation with most of these plugins, was it relied on images that were not perfect to render across many devices and used a nested HTML markup of radio inputs with lot of javascript validation.

With CSS3 and HTML5 supported now in most modern browsers, a simpler solution, using scalable vector icons, for perfect display across devices is attempted in this new StarRating widget. This widget is part of the yii2-widgets package. It requires no images or does not internally use a nested span of radios, but simple HTML5 and CSS3 features.

Important Notes

Before using the plugin, read this for better controlling the widget features for your Yii2 app:

  1. The widget offers many features using pure CSS to markup the star symbols and fractional ratings of any value. You can read about it at the bootstrap-star-rating plugin page. Ensure you have the widget dependencies covered for your environment as per the composer.json.
  2. It is to be noted that the plugin has some important pre-requisites. In addition to JQuery and CSS3 support, it internally uses a HTML 5 range input to capture the input. Hence the browser must support HTML 5 range inputs. Most modern browsers support the HTML-5 range input. For old or unsupported browsers, the plugin gracefully auto-degrades to a normal select input.
  3. The plugin uses the Bootstrap 3 markup by default for styling the stars, the caption, and clear button. However this can be easily overwritten by CSS parameters to the plugin.
  4. How do you control the fractional ratings? The following parameters in pluginOptions are important to control your rating steps and values:
  • stars: the number of stars to display. This defaults to 5
  • min: the minimum value of the rating. This defaults to 0.
  • max: the maximum value of the rating. This defaults to 5.
  • step: the step to increment the rating. This defaults to 0.5.

So if you want 5 stars and increment the rating by 25% of each star width, just change step to 0.25 above.

  1. Display an unicode icon without loading bootstrap glyphicon. You can set the glyphicon property to false - it will display the Unicode Star symbol.

  2. Using alternative icon symbols. You can use any icon font symbol and pass the encoded entity in symbol property.

An example below:

// Fractional star rating with 6 stars , custom star symbol (uses glyphicon heart),
// custom captions, and customizable ranges.
echo StarRating::widget(['name' => 'rating_19', 
    'pluginOptions' => [
        'stars' => 6, 
        'min' => 0,
        'max' => 6,
        'step' => 0.1,
        'symbol' => html_entity_decode('', ENT_QUOTES, "utf-8"),
        'defaultCaption' => '{rating} hearts',
        'starCaptions'=>[]
    ]
]);

Hope you find the widget useful.