README

A Craft CMS plugin that provides advanced rating field types for Verbb's Formie form builder, including star, emoji, and NPS (Net Promoter Score) rating types.

Requirements

Craft CMS 5.0 or greater
PHP 8.2 or greater
Formie 3.0 or greater

Features

Three Rating Types

Star Rating: Classic star ratings with optional half-star support
Emoji Rating: Expressive emotion faces (😭 😢 😕 😐 😊 😍 🤩 🥰 😎 🤗 🥳) - supports 0-10 scale
NPS Rating: Net Promoter Score numeric boxes (0-10 scale)

Customizable Settings

Size Options: Small, medium, large, extra large
Flexible Range: Configurable min/max values
Half Ratings: Enable half-star selections (star type only)
Single Emoji Selection: Highlight only the selected emoji instead of cumulative (emoji type only)
Custom Labels: Define text labels for each rating value that display beneath selected emoji
Endpoint Labels: Add descriptive labels at scale endpoints (e.g., "Poor" / "Excellent")
Emoji Render Modes: Choose between system emojis, Noto Color Emoji (detailed), or Noto Emoji (simple)
Plugin Settings: Configure defaults for all new rating fields

Seamless Integration

Native Formie field with full validation support
GraphQL support for headless implementations
RTL support for Arabic sites
Backward compatible with existing forms

Statistics & Analytics

Comprehensive Analytics Dashboard: View rating statistics for all forms
Smart Grouping: Group ratings by product code, name, category, or any form field
Type-Aware Calculations: Automatic NPS scoring, star/emoji averages, and distributions
Performance Indicators: Scale-aware insights (Excellent/Good/Fair/Poor) that adapt to any min/max range
Date Range Filtering: Analyze trends across today, yesterday, last 7/30/90 days, or all time
CSV Export: Export filtered data with grouping for external analysis
File-Based Caching: Fast performance with automatic cache invalidation on new submissions
CLI Cache Management: Clear cache via command line tools

Installation

Via Composer

cd /path/to/project

composer require lindemannrock/craft-formie-rating-field

./craft plugin/install formie-rating-field

Using DDEV

cd /path/to/project

ddev composer require lindemannrock/craft-formie-rating-field

ddev craft plugin/install formie-rating-field

Via Control Panel

In the Control Panel, go to Settings → Plugins and click "Install" for Formie Rating Field.

Configuration

Plugin Settings

Navigate to Settings → Plugins → Formie Rating Field to configure default values for new rating fields:

Default Rating Type: Star, emoji, or NPS
Default Size: Small to extra large
Default Range: Min/max rating values
Default Labels: Start/end label text
Default Options: Half ratings, show labels, etc.

Config File

Create a config/formie-rating-field.php file to override default settings:

cp vendor/lindemannrock/craft-formie-rating-field/src/config.php config/formie-rating-field.php

Example configuration:

// config/formie-rating-field.php
return [
    'defaultRatingType' => 'emoji',
    'defaultRatingSize' => 'large',
    'defaultMinRating' => 0,
    'defaultMaxRating' => 10,
    'defaultAllowHalfRatings' => false,
    'defaultSingleEmojiSelection' => true,
    'defaultShowEndpointLabels' => true,
    'defaultStartLabel' => 'Not Likely',
    'defaultEndLabel' => 'Very Likely',
    'defaultEmojiRenderMode' => 'noto-simple',  // 'system', 'noto-color', 'noto-simple'
    'itemsPerPage' => 50,  // Number of items per page in statistics lists
];

See Configuration Documentation for all available options.

Statistics & Analytics

The plugin includes a comprehensive analytics dashboard for analyzing rating field submissions.

Accessing Statistics

Navigate to the plugin's CP section:

Forms Rating → Statistics in the main navigation
Select a form to view detailed statistics
Use filters to refine your analysis

Key Features

Smart Grouping

Group ratings by any field in your form (product code, category, hidden fields, etc.)
View performance breakdown for each group
Identify top performers and items needing attention

Date Range Filtering

Filter by: Today, Yesterday, Last 7/30/90 days, or All time
Analyze trends over specific periods
Compare performance across time ranges

Performance Insights

Scale-aware indicators (Excellent/Good/Fair/Poor) that adapt to any rating range
Reliability warnings for products with insufficient reviews (<5)
Visual progress bars showing relative performance
NPS score calculation with promoter/passive/detractor breakdown

Data Export

Export filtered data to CSV
Grouped exports show aggregated stats per group
Non-grouped exports show raw submission data
Includes average and median values for comprehensive analysis

Analytics Views

When Not Grouped (Default)

Overall statistics across all submissions
Distribution charts showing rating patterns
Summary metrics (average, median, mode)

When Grouped by Field

Summary cards showing total groups, overall average, top/bottom performers
Detailed table with performance indicators for each group
Sortable columns (Product Name, Reviews, Average, Performance)
Client-side search with instant filtering
Click any group to drill down to individual submissions

Drill-Down View

Click any product/group to see individual submissions
Full submission data displayed (all form fields)
Search, sort, and paginate through submissions
Export submissions for specific group to CSV
Direct links to view full submissions in Formie

CLI Commands

Manage statistics cache via command line:

# Clear all statistics cache
php craft formie-rating-field/cache/clear

# Clear cache for specific form
php craft formie-rating-field/cache/clear-form --formId=34

# View cache information
php craft formie-rating-field/cache/info

Or with DDEV:

ddev craft formie-rating-field/cache/clear
ddev craft formie-rating-field/cache/info

Cache Behavior

Location: storage/runtime/formie-rating-field/cache/statistics/
Invalidation: Automatic on submission save/delete
Manual Refresh: Use CLI commands or "Refresh" button in CP
No TTL: Cache persists until invalidated (optimal performance)

Usage

Adding a Rating Field

Open your form in the Formie form builder
Click "Add Field" and select "Rating" from the field types
Configure the field settings:
- Rating Type: Choose star, emoji, or NPS display
- Size: Control the visual size of rating elements
- Rating Range: Set minimum and maximum values
- Allow Half Ratings: Enable for star type (stars only)
- Single Emoji Selection: Enable for single emoji highlighting (emoji only)
- Custom Labels: Define labels for each value (shows when using single emoji selection)
- Endpoint Labels: Add descriptive text at scale ends

Using Single Emoji Selection with Custom Labels

When Single Emoji Selection is enabled for emoji ratings:

Only the clicked emoji is highlighted (not cumulative)
A custom label displays beneath the selected emoji
Define labels in the Custom Labels table that appears

Example: For a 1-5 rating scale:

Value	Label
1	Terrible
2	Bad
3	Okay
4	Good
5	Excellent

Important:

Define a label for each value in your rating range (e.g., if min=0 and max=10, define labels for values 0-10)
Labels display only when an emoji is selected
If no custom label is defined for a value, the numeric value displays instead

Templating

In your templates, rating fields are rendered automatically by Formie:

{# Render the entire form #}
{{ craft.formie.renderForm('contactForm') }}

{# Or render a specific field #}
{% set form = craft.formie.forms.handle('contactForm').one() %}
{{ craft.formie.renderField(form, 'ratingField') }}

GraphQL Support

Query rating field data via GraphQL:

query {
  formieSubmissions(form: "contactForm") {
    ... on contactForm_Submission {
      ratingField
    }
  }
}

Field Settings Reference

Setting	Description	Options
Rating Type	Visual style of the rating	`star`, `emoji`, `nps`
Emoji Render Mode	How emojis are displayed	`system`, `noto-color`, `noto-simple` (emoji only)
Size	Visual size of rating elements	`small`, `medium`, `large`, `xlarge`
Min Value	Minimum rating value	0-1 (NPS is always 0)
Max Value	Maximum rating value	3-10 (NPS is always 10)
Allow Half Ratings	Enable half-star selections	true/false (star only)
Single Emoji Selection	Highlight only selected emoji (not cumulative)	true/false (emoji only)
Custom Labels	Define text labels for each rating value	Table with Value/Label pairs
Show Endpoint Labels	Display labels at scale ends	true/false
Start Label	Text for lowest value	Any text
End Label	Text for highest value	Any text
Show Selected Label	Display selected rating as text	true/false

Google Review Integration

Automatically prompt high-rating customers to leave Google Reviews:

Setting	Description
Enable Google Review Prompt	Show Google Review link for high ratings
Rating Threshold	Minimum rating to trigger prompt (e.g., 9 for NPS)
Google Place ID Field	Handle of field containing Place ID
Review URL Template	Customizable URL (supports different regions)
Button Label	Text on review button
Button Alignment	start/center/end
High/Medium/Low Messages	Custom messages per rating tier

How it works:

High ratings (≥ threshold): Shows Google Review button
Medium ratings (threshold - 2): Generic thank you message
Low ratings (< medium): Improvement message

All messages are translatable through Formie's translation system.

Styling

For custom CSS styling options and examples, see CSS Customization Guide.

File Structure

plugins/formie-rating-field/
├── docs/
│   ├── CONFIGURATION.md                   # Configuration guide
│   └── CSS_CUSTOMIZATION.md               # CSS customization guide
├── src/
│   ├── console/
│   │   └── controllers/
│   │       └── CacheController.php        # CLI cache management
│   ├── controllers/
│   │   ├── StatisticsController.php       # Statistics & analytics
│   │   └── SettingsController.php         # Settings pages
│   ├── fields/
│   │   └── Rating.php                     # Main field class
│   ├── integrations/
│   │   └── feedme/
│   │       └── fields/
│   │           └── Rating.php             # Feed Me integration
│   ├── models/
│   │   └── Settings.php                   # Plugin settings model
│   ├── services/
│   │   └── StatisticsService.php          # Statistics calculations
│   ├── templates/
│   │   ├── _components/
│   │   │   └── plugin-credit.twig
│   │   ├── _layouts/
│   │   │   └── settings.twig              # Settings layout with sidebar
│   │   ├── fields/
│   │   │   └── rating/
│   │   │       ├── input.twig             # Field input template
│   │   │       ├── value.twig             # Value display
│   │   │       └── email.twig             # Email template
│   │   ├── settings/
│   │   │   ├── general.twig               # General settings tab
│   │   │   └── interface.twig             # Interface settings tab
│   │   ├── statistics/
│   │   │   ├── index.twig                 # Forms list
│   │   │   └── form.twig                  # Form statistics detail
│   │   ├── settings.twig                  # Settings redirect
│   │   └── index.twig                     # Plugin index redirect
│   ├── twigextensions/
│   │   └── PluginNameExtension.php        # Twig helper (ratingHelper)
│   ├── web/
│   │   └── assets/
│   │       └── field/
│   │           ├── RatingFieldAsset.php
│   │           ├── rating.css
│   │           └── rating.js
│   ├── config.php                         # Config file template
│   ├── icon.svg                           # Plugin icon
│   └── FormieRatingField.php              # Main plugin class
├── CHANGELOG.md
├── LICENSE.md
├── README.md
└── composer.json

Support

Documentation: https://github.com/LindemannRock/craft-formie-rating-field
Issues: https://github.com/LindemannRock/craft-formie-rating-field/issues
Email: support@lindemannrock.com

License

This plugin is licensed under the MIT License. See LICENSE for details.

Developed by LindemannRock

Built for use with Formie by Verbb

lindemannrock / craft-formie-rating-field

Maintainers

Details

README

Requirements

Features

Three Rating Types

Customizable Settings

Seamless Integration

Statistics & Analytics

Installation

Via Composer

Using DDEV

Via Control Panel

Configuration

Plugin Settings

Config File

Statistics & Analytics

Accessing Statistics

Key Features

Analytics Views

CLI Commands

Cache Behavior

Usage

Adding a Rating Field

Using Single Emoji Selection with Custom Labels

Templating

GraphQL Support

Field Settings Reference

Google Review Integration

Styling

File Structure

Support

License