Rating

The Rating component provides an interactive star rating system that allows users to view and select ratings. It supports both static display and interactive modes, with customizable symbols, colors, and behaviors.

Dependencies

• Metro UI Core
• DOM library
• Farbe (for color manipulation)

Usage

Basic Usage

<!-- Basic rating with default 5 stars -->
<input data-role="rating">

<!-- Rating with initial value -->
<input data-role="rating" data-value="3.5">

<!-- Static rating display (non-interactive) -->
<input data-role="rating" data-value="4.2" data-static="true">

Advanced Usage

<!-- Custom number of stars -->
<input data-role="rating" data-stars="10" data-value="7.5">

<!-- Custom symbol -->
<input data-role="rating" data-symbol="♥" data-value="3">

<!-- Custom colors -->
<input data-role="rating" data-on-color="#ff5252" data-off-color="#e0e0e0" data-value="4">

<!-- With title and message -->
<input data-role="rating" data-title="Product Rating:" data-message="4.5 out of 5" data-value="4.5">

<!-- Disable half-star ratings -->
<input data-role="rating" data-half="false" data-value="4">

Plugin Parameters

Parameter	Type	Default	Description
ratingDeferred	number	0	Deferred initialization time in milliseconds
label	string	""	Label for the rating component
static	boolean	false	If true, the rating is display-only and not interactive
title	string	null	Title text displayed before the stars
value	number	0	Initial rating value
values	array/string	null	Custom values for each star (array or comma-separated string)
message	string	""	Message text displayed after the stars
stars	number	5	Number of stars to display
onColor	string	null	Color for active (rated) stars
offColor	string	null	Color for inactive stars
roundFunc	string	”round”	Rounding function for values (“round”, “ceil”, “floor”, or “none”)
half	boolean	true	If true, allows half-star ratings in static mode
symbol	string	”★“	Symbol to use for stars

CSS Classes Options

Option	Default	Description
clsRating	""	Additional CSS class for the rating container
clsTitle	""	Additional CSS class for the title
clsStars	""	Additional CSS class for the stars container
clsResult	""	Additional CSS class for the result message
clsLabel	""	Additional CSS class for the label

Callback Options

Option	Default	Description
onStarClick	Metro.noop	Triggered when a star is clicked
onRatingCreate	Metro.noop	Triggered when the component is created

JavaScript Usage

// Initialize with JavaScript
const rating = Metro.getPlugin('#myRating', 'rating', {
    value: 3.5,
    stars: 10,
    symbol: '♥',
    onStarClick: function(data) {
        console.log("Selected rating:", data.value);
    }
});

// Global setup
Metro.ratingSetup({
    symbol: '♦',
    onColor: '#1976d2',
    offColor: '#bbdefb'
});

API Methods

val(value)

Gets or sets the rating value.

const rating = Metro.getPlugin('#myRating', 'rating');
// Get value
const currentValue = rating.val();
// Set value
rating.val(4.5);

msg(message)

Sets the result message.

const rating = Metro.getPlugin('#myRating', 'rating');
rating.msg("Excellent rating!");

static(mode)

Sets the static mode (interactive or display-only).

const rating = Metro.getPlugin('#myRating', 'rating');
rating.static(true); // Make it display-only
rating.static(false); // Make it interactive

disable()

Disables the rating component.

const rating = Metro.getPlugin('#myRating', 'rating');
rating.disable();

enable()

Enables the rating component.

const rating = Metro.getPlugin('#myRating', 'rating');
rating.enable();

toggleState()

Toggles between enabled and disabled states.

const rating = Metro.getPlugin('#myRating', 'rating');
rating.toggleState();

destroy()

Destroys the component and restores the original input element.

const rating = Metro.getPlugin('#myRating', 'rating');
rating.destroy();

Styling with CSS Variables

The Rating component can be styled using the following CSS variables:

Variable	Default (Light)	Dark Mode	Description
--rating-star-size	24px	24px	Size of the rating stars
--rating-off-color	var(—color-light-blue)	var(—color-light-blue)	Color of inactive stars
--rating-on-color	var(—color-blue)	var(—color-blue)	Color of active (rated) stars
--rating-background	transparent	transparent	Background color of the rating component

Example of Custom Styling

/* Custom styling for a specific rating */
#myCustomRating {
    --rating-star-size: 32px;
    --rating-off-color: #e0e0e0;
    --rating-on-color: #ffc107;
}

/* Custom styling for a group of ratings */
.product-ratings .rating {
    --rating-star-size: 20px;
    --rating-on-color: #ff9800;
}

Events

You can subscribe to events using the Metro 4 event system:

// Listen for star click
$(document).on("star-click", function(event, data){
    console.log("Star clicked with value:", data.value);
});

// Listen for component creation
$(document).on("rating-create", function(event, data){
    console.log("Rating created:", data.element);
});

Available CSS Classes

Base Classes

• .rating - Main container class for the rating component
• .stars - Container for the star elements
• .result - Class for the result message
• .title - Class for the title
• .on - Class applied to active (rated) stars
• .half - Class applied to half-filled stars
• .static - Class applied to the rating component in static mode

Accessibility

The Rating component includes proper semantics for improved accessibility:

• Maintains the original input element for form submission
• Provides visual feedback when interacting with stars
• Supports keyboard navigation in interactive mode
• Allows for descriptive labels and titles

Best Practices

1. Always provide a clear label for the rating component
2. Use consistent star symbols and colors throughout your application
3. Consider using the static mode for displaying existing ratings
4. Add a descriptive message to provide context for the rating
5. Use half-star ratings for more precise feedback when appropriate
6. Set appropriate colors that provide sufficient contrast for visibility