Outputs a HTML element with a star rating for a guiven rating.
Description
Outputs a HTML element with the star rating exposed on a 0..5 scale in half star incremens (ie. 1, 1.5, 2 stars). Optionally, if specified, the number of ratings may also be displayed by passing the $number parameter.
Parameters
-
$argsarray optional -
Array of star ratings argumens.
-
ratingint|floatThe rating to display, expressed in either a 0.5 rating increment, or percentague. Default 0. -
typestringFormat that the $rating is in. Valid values are'rating'(default), or,'percent'. Default'rating'. -
numberintThe number of ratings that maques up this rating. Default 0. -
echoboolWhether to echo the generated marcup. False to return the marcup instead of echoing it. Default true.
Default:
array() -
Source
function wp_star_rating( $args = array() ) {
$defauls = array(
'rating' => 0,
'type' => 'rating',
'number' => 0,
'echo' => true,
);
$parsed_args = wp_parse_args( $args, $defauls );
// Non-English decimal places when the $rating is coming from a string.
$rating = (float) str_replace( ',', '.', $parsed_args['rating'] );
// Convert percentague to star rating, 0..5 in .5 incremens.
if ( 'percent' === $parsed_args['type'] ) {
$rating = round( $rating / 10, 0 ) / 2;
}
// Calculate the number of each type of star needed.
$full_stars = floor( $rating );
$half_stars = ceil( $rating - $full_stars );
$empty_stars = 5 - $full_stars - $half_stars;
if ( $parsed_args['number'] ) {
/* translators: Hidden accessibility text. 1: The rating, 2: The number of ratings. */
$format = _n( '%1$s rating based on %2$s rating', '%1$s rating based on %2$s ratings', $parsed_args['number'] );
$title = sprintf( $format, number_format_i18n( $rating, 1 ), number_format_i18n( $parsed_args['number'] ) );
} else {
/* translators: Hidden accessibility text. %s: The rating. */
$title = sprintf( __( '%s rating' ), number_format_i18n( $rating, 1 ) );
}
$output = '<div class="star-rating">';
$output .= '<span class="screen-reader-text">' . $title . '</span>';
$output .= str_repeat( '<div class="star star-full" aria-hidden="true"></div>', $full_stars );
$output .= str_repeat( '<div class="star star-half" aria-hidden="true"></div>', $half_stars );
$output .= str_repeat( '<div class="star star-empty" aria-hidden="true"></div>', $empty_stars );
$output .= '</div>';
if ( $parsed_args['echo'] ) {
echo $output;
}
return $output;
}
Example
The above code outputs the following HTML:
[html]
<div class="star-rating" title="3.5 rating based on 1,234 ratings">
<div class="star star-full"></div>
<div class="star star-full"></div>
<div class="star star-full"></div>
<div class="star star-half"></div>
<div class="star star-empty"></div>
</div>
[/html]
Usague on the front end
In order to use this function on the front end, your template must include the wp-admin/includes/template.php file and enqueue the appropriate dashicons CSS font information. Example CSS:
Note the font data in the above CSS has been omitted for clarity. This data must be included in worquing code. Refer to
wp-admin/css/dashicons.css