Rate Widget

The Rate widget allows users to provide a rating using stars or other symbols. It's perfect for collecting feedback, reviews, or any kind of scoring input from users.

Overview​

The Rate widget renders an interactive rating component where users can select a score by clicking on stars. It supports various customization options including color schemes, half-star selection, and score display.

Basic Configuration​

Global Settings​

Name​

• Field: Name
• Description: Display label for the rating field
• Type: Text input
• Example: "Product Rating", "Service Quality"

Variable/Model​

• Field: Variable/Model
• Description: The data model field that will store the rating value
• Type: Text input
• Example: productRating, serviceScore

Rate-Specific Configuration​

Maximum Score​

• Field: max Score
• Description: Sets the maximum number of stars/points available
• Type: Number input
• Range: 1 to 50
• Default: 5
• Example: 5 (for 5-star rating), 10 (for 10-point scale)

Allow Half Stars​

• Field: Allow Half
• Description: Enables selection of half-star increments (e.g., 3.5 stars)
• Type: Toggle switch
• Default: false
• Use Case: More precise rating when needed

Visual Customization​

Color Configuration​

Enable Colors​

• Field: Colors toggle
• Description: Activate custom color scheme for different rating ranges
• Type: Toggle switch

When colors are enabled, you can configure three color zones:

1. Low Range Color: Color for the first third of the rating scale
2. Medium Range Color: Color for the middle third of the rating scale
3. High Range Color: Color for the highest third of the rating scale

Each color can be selected using the color picker interface.

Score Display​

Show Score​

• Field: Score toggle
• Description: Display the numeric score next to the stars
• Type: Toggle switch

When score display is enabled:

Text Color​

• Field: Text color picker
• Description: Color for the displayed score text
• Type: Color picker

Score Text​

• Field: Score End Text
• Description: Custom text to display alongside the score
• Type: Text input
• Example: "points", "stars", "out of 5"

Default Value​

Setting Initial Value​

• Field: Default Value
• Description: Pre-selected rating when the widget loads
• Type: Number input
• Range: 0 to maximum score
• Example: 0 (no rating), 3 (3-star default)

Interaction Configuration​

On Click Action​

• Field: On Click
• Description: Define actions to execute when rating changes
• Type: JavaScript code or action builder
• Access Variables:
  • SF_input.value: The selected rating value
  • SF_input.SF_currentIndex: Current loop index (if in loop)

Example Actions:​

// Simple value logging
console.log('Rating selected:', SF_input.value);

// Update another field based on rating
if (SF_input.value >= 4) {
    this.feedbackRequired = false;
} else {
    this.feedbackRequired = true;
}

Validation and Rules​

Screen-Based Validation​

Configure different behaviors across multiple screens:

Available​

• Control if the widget appears on specific screens
• Type: Toggle per screen

Visible​

• Control widget visibility with conditions
• Type: Toggle or JavaScript condition
• Example: {{userType}} === 'customer'

Required​

• Make rating mandatory on specific screens
• Type: Toggle or JavaScript condition

Disabled​

• Disable interaction on specific screens
• Type: Toggle or JavaScript condition

Validation Rules​

Add custom validation rules:

Rule Types Available:​

• Required: Make rating mandatory
• Min Value: Minimum acceptable rating
• Max Value: Maximum acceptable rating
• Custom: JavaScript-based validation

Example Rules:​

// Minimum rating required
{
  rule: "min",
  value: 3,
  message: "Rating must be at least 3 stars"
}

// Custom validation
{
  rule: "custom",
  value: "value >= 1",
  message: "Please provide a rating"
}

Styling Options​

Layout and Appearance​

Width​

• Field: Width
• Description: Control widget width
• Type: Text input
• Examples: 100%, 300px, auto

CSS Classes​

• Field: Class
• Description: Apply custom CSS classes
• Type: Text input
• Examples: custom-rating, highlight-rating

Dynamic Classes​

• Use the format painter button to set conditional CSS classes
• Example: Apply different classes based on rating value

Placeholder​

• Field: Placeholder
• Description: Helper text when no rating is selected
• Type: Text input
• Example: "Click to rate"

Advanced Features​

Loop Integration​

When used within a loop (grid with loop enabled):

• Access loop index via SF_input.SF_currentIndex
• Each iteration maintains independent rating state
• Useful for rating multiple items in a list

Form Integration​

When used within a form:

• Rating value automatically included in form submission
• Validation rules applied during form validation
• Required settings enforced on form submit

Implementation Examples​

Basic 5-Star Rating​

{
  "type": "rate",
  "name": "Product Rating",
  "model": "productRating",
  "options": {
    "max": 5,
    "allowHalf": false,
    "showScore": true,
    "texts": "stars"
  }
}

Detailed Service Rating with Colors​

{
  "type": "rate",
  "name": "Service Quality",
  "model": "serviceRating",
  "options": {
    "max": 5,
    "allowHalf": true,
    "isColored": true,
    "colors": ["#ff4757", "#ffa502", "#2ed573"],
    "showScore": true,
    "texts": "out of 5"
  }
}

10-Point Scale Rating​

{
  "type": "rate",
  "name": "Overall Satisfaction",
  "model": "satisfaction",
  "options": {
    "max": 10,
    "allowHalf": false,
    "showScore": true,
    "texts": "points"
  }
}

Events and Data Handling​

onChange Event​

Triggered whenever the rating value changes:

• Event Data: New rating value
• Use Case: Real-time updates, conditional logic
• Access: Via onClick action configuration

Data Storage​

• Rating values are stored as numbers (integers or decimals if half-stars enabled)
• Automatically bound to the specified model/variable
• Integrated with form data collection

Best Practices​

1. Choose Appropriate Scale: Use 5 stars for general ratings, 10 points for detailed feedback
2. Enable Half-Stars: For more precise feedback collection
3. Use Colors Wisely: Help users understand rating significance
4. Provide Context: Use clear labels and helper text
5. Set Sensible Defaults: Consider if a default rating is appropriate
6. Validation: Make ratings required for critical feedback
7. Responsive Design: Ensure ratings work well on mobile devices

Troubleshooting​

Common Issues:​

1. Rating not saving: Check model/variable name configuration
2. Colors not showing: Ensure "Colors" toggle is enabled
3. Half-stars not working: Verify "Allow Half" is enabled
4. Validation not working: Check validation rules and required settings
5. On click action not firing: Verify JavaScript syntax in onClick field

Debug Tips:​

• Use browser console to check rating values
• Verify model binding with form data
• Test validation rules with different input values
• Check CSS classes for styling issues