wp_star_rating

Output a HTML element with a star rating for a given rating.

Description

wp_star_rating( (array) $args = array() ); 

Outputs a HTML element with the star rating exposed on a 0..5 scale in half star increments (ie. 1, 1.5, 2 stars). Optionally, if specified, the number of ratings may also be displayed by passing the $number parameter.

Parameters (1)

0. $args — Optional. (array) => array()
Array of star ratings arguments.

Options

  • rating (int) => 0

    The rating to display, expressed in either a 0.5 rating increment, or percentage.

  • type (string) => 'rating'

    Format that the $rating is in. Valid values are rating (default), or, percent..

  • number (int) => 0

    The number of ratings that makes up this rating.

array(

    /**
     * The rating to display, expressed in either a 0.5 rating increment, or percentage.
     *
     * @type int
     */
    'rating' => 0,

    /**
     * Format that the $rating is in. Valid values are 'rating' (default), or, 'percent'.
     *
     * @type string
     * @default 'rating'
     */
    'type' => 'rating',

    /**
     * The number of ratings that makes up this rating.
     *
     * @type int
     */
    'number' => 0
);        


Usage

  1. if ( !function_exists( 'wp_star_rating' ) ) { 
  2. require_once ABSPATH . '/wp-admin/includes/template.php'; 
  3.  
  4. // Optional. Array of star ratings arguments. 
  5. $args = array( 
  6. 'rating' => 0, 
  7. 'type' => 'rating', 
  8. 'number' => 0 
  9. ); 
  10.  
  11. // NOTICE! Understand what this does before running. 
  12. $result = wp_star_rating($args); 
  13.  

Defined (1)

The function is defined in the following location(s).

/wp-admin/includes/template.php  
  1. function wp_star_rating( $args = array() ) { 
  2. $defaults = array( 
  3. 'rating' => 0,  
  4. 'type' => 'rating',  
  5. 'number' => 0,  
  6. 'echo' => true,  
  7. ); 
  8. $r = wp_parse_args( $args, $defaults ); 
  9.  
  10. // Non-english decimal places when the $rating is coming from a string 
  11. $rating = str_replace( ', ', '.', $r['rating'] ); 
  12.  
  13. // Convert Percentage to star rating, 0..5 in .5 increments 
  14. if ( 'percent' == $r['type'] ) { 
  15. $rating = round( $rating / 10, 0 ) / 2; 
  16.  
  17. // Calculate the number of each type of star needed 
  18. $full_stars = floor( $rating ); 
  19. $half_stars = ceil( $rating - $full_stars ); 
  20. $empty_stars = 5 - $full_stars - $half_stars; 
  21.  
  22. if ( $r['number'] ) { 
  23. /** translators: 1: The rating, 2: The number of ratings */ 
  24. $format = _n( '%1$s rating based on %2$s rating', '%1$s rating based on %2$s ratings', $r['number'] ); 
  25. $title = sprintf( $format, number_format_i18n( $rating, 1 ), number_format_i18n( $r['number'] ) ); 
  26. } else { 
  27. /** translators: 1: The rating */ 
  28. $title = sprintf( __( '%s rating' ), number_format_i18n( $rating, 1 ) ); 
  29.  
  30. $output = '<div class="star-rating">'; 
  31. $output .= '<span class="screen-reader-text">' . $title . '</span>'; 
  32. $output .= str_repeat( '<div class="star star-full" aria-hidden="true"></div>', $full_stars ); 
  33. $output .= str_repeat( '<div class="star star-half" aria-hidden="true"></div>', $half_stars ); 
  34. $output .= str_repeat( '<div class="star star-empty" aria-hidden="true"></div>', $empty_stars ); 
  35. $output .= '</div>'; 
  36.  
  37. if ( $r['echo'] ) { 
  38. echo $output; 
  39.  
  40. return $output;