196 lines
4.4 KiB
Markdown
Executable File
196 lines
4.4 KiB
Markdown
Executable File
# Rating Stars Widget
|
|
|
|
## Overview
|
|
|
|
The Rating Stars widget is an interactive OWL component for Odoo 18 that provides a 5-star rating interface with full accessibility support.
|
|
|
|
## Features
|
|
|
|
- ⭐ **Interactive Star Selection**: Click any star to set the rating (1-5)
|
|
- 👆 **Hover Feedback**: Visual preview of rating on hover
|
|
- ⌨️ **Keyboard Navigation**: Full keyboard support with arrow keys, Enter, Home, and End
|
|
- ♿ **Accessibility**: ARIA labels and screen reader support
|
|
- 📱 **Touch-Friendly**: Optimized for mobile devices with larger touch targets
|
|
- 🎨 **Responsive Design**: Adapts to different screen sizes
|
|
- 🌓 **Theme Support**: Dark mode and high contrast mode support
|
|
|
|
## Usage
|
|
|
|
### In OWL Components
|
|
|
|
```javascript
|
|
import { RatingStars } from "@helpdesk_rating_five_stars/js/rating_stars";
|
|
|
|
// In your component template
|
|
<RatingStars
|
|
value="state.rating"
|
|
onChange.bind="onRatingChange"
|
|
size="'medium'"
|
|
readonly="false"
|
|
/>
|
|
|
|
// In your component class
|
|
onRatingChange(newValue) {
|
|
this.state.rating = newValue;
|
|
console.log(`Rating changed to: ${newValue}`);
|
|
}
|
|
```
|
|
|
|
### Props
|
|
|
|
| Prop | Type | Default | Description |
|
|
|------|------|---------|-------------|
|
|
| `value` | Number | 0 | Current rating value (0-5) |
|
|
| `readonly` | Boolean | false | Whether the widget is read-only |
|
|
| `onChange` | Function | undefined | Callback function when rating changes |
|
|
| `size` | String | 'medium' | Size variant: 'small', 'medium', or 'large' |
|
|
|
|
### In QWeb Templates
|
|
|
|
```xml
|
|
<t t-component="RatingStars"
|
|
t-props="{
|
|
value: rating,
|
|
onChange: (val) => this.updateRating(val),
|
|
size: 'large',
|
|
readonly: false
|
|
}"
|
|
/>
|
|
```
|
|
|
|
### Size Variants
|
|
|
|
- **Small** (`size="'small'"`): 16px stars, compact for list views
|
|
- **Medium** (`size="'medium'"`): 24px stars, default size
|
|
- **Large** (`size="'large'"`): 36px stars, prominent for forms
|
|
|
|
## Keyboard Navigation
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `Arrow Right` / `Arrow Up` | Increase rating by 1 star |
|
|
| `Arrow Left` / `Arrow Down` | Decrease rating by 1 star |
|
|
| `Home` | Jump to 1 star |
|
|
| `End` | Jump to 5 stars |
|
|
| `Enter` / `Space` | Confirm current selection |
|
|
| `Tab` | Move focus to/from widget |
|
|
|
|
## Accessibility
|
|
|
|
The widget includes comprehensive accessibility features:
|
|
|
|
- **ARIA Role**: `slider` role for the container
|
|
- **ARIA Labels**: Descriptive labels for each star (e.g., "Rate 3 stars out of 5")
|
|
- **ARIA Properties**:
|
|
- `aria-valuemin="1"`
|
|
- `aria-valuemax="5"`
|
|
- `aria-valuenow` (current value)
|
|
- `aria-readonly` (when readonly)
|
|
- **Keyboard Support**: Full keyboard navigation
|
|
- **Focus Indicators**: Clear visual focus indicators
|
|
- **Screen Reader Support**: Announces rating changes
|
|
|
|
## Styling
|
|
|
|
The widget uses SCSS for styling with the following features:
|
|
|
|
- CSS transitions for smooth animations
|
|
- Hover effects with scale transform
|
|
- Focus indicators for keyboard navigation
|
|
- Responsive breakpoints for mobile
|
|
- Support for reduced motion preferences
|
|
- High contrast mode support
|
|
- Dark mode support
|
|
|
|
### Custom Styling
|
|
|
|
You can override the default styles by targeting these CSS classes:
|
|
|
|
```scss
|
|
.rating-stars-container {
|
|
// Container styles
|
|
}
|
|
|
|
.rating-star {
|
|
// Individual star styles
|
|
}
|
|
|
|
.rating-star-filled {
|
|
// Filled star color
|
|
color: #ffc107;
|
|
}
|
|
|
|
.rating-star-empty {
|
|
// Empty star color
|
|
color: #e0e0e0;
|
|
}
|
|
|
|
.rating-star-interactive {
|
|
// Interactive star styles (hover, cursor)
|
|
}
|
|
|
|
.rating-star-focused {
|
|
// Focused star styles (keyboard navigation)
|
|
}
|
|
```
|
|
|
|
## Browser Support
|
|
|
|
- Chrome/Edge: ✅ Full support
|
|
- Firefox: ✅ Full support
|
|
- Safari: ✅ Full support
|
|
- Mobile browsers: ✅ Full support with touch optimization
|
|
|
|
## Examples
|
|
|
|
### Read-only Display
|
|
|
|
```javascript
|
|
<RatingStars
|
|
value="4"
|
|
readonly="true"
|
|
size="'small'"
|
|
/>
|
|
```
|
|
|
|
### Interactive Rating Form
|
|
|
|
```javascript
|
|
<RatingStars
|
|
value="state.customerRating"
|
|
onChange.bind="handleRatingChange"
|
|
size="'large'"
|
|
/>
|
|
```
|
|
|
|
### With Validation
|
|
|
|
```javascript
|
|
onRatingChange(newValue) {
|
|
if (newValue >= 1 && newValue <= 5) {
|
|
this.state.rating = newValue;
|
|
this.validateForm();
|
|
}
|
|
}
|
|
```
|
|
|
|
## Testing
|
|
|
|
The widget can be tested using the demo HTML file:
|
|
|
|
```
|
|
customaddons/helpdesk_rating_five_stars/static/description/widget_demo.html
|
|
```
|
|
|
|
Open this file in a browser to see interactive examples of the widget in action.
|
|
|
|
## Requirements
|
|
|
|
- Odoo 18
|
|
- OWL (Odoo Web Library) - included in Odoo 18
|
|
- Modern browser with ES6 support
|
|
|
|
## License
|
|
|
|
LGPL-3
|