RRule Builder for Rails

A Stimulus-based RRULE (iCalendar recurrence rule) builder component for Rails applications. This provides a user-friendly interface for creating recurring event schedules without requiring external dependencies like jQuery UI or React.

Overview

This RRule builder generates iCalendar-compliant RRULE strings that can be used with libraries like rrule (Ruby gem) or rrule.js (JavaScript) to calculate recurring event occurrences.

Features:

• ✅ Pure Stimulus controller (no jQuery UI or React dependencies)
• ✅ Declarative data-action attributes (idiomatic Stimulus)
• ✅ Supports daily, weekly, monthly, and yearly frequencies
• ✅ Flexible interval support (every N days/weeks/months/years)
• ✅ Weekday selection for weekly patterns
• ✅ Month day selection for monthly patterns
• ✅ Yearly patterns with month/day selection
• ✅ End conditions (count or until date)
• ✅ Parses and displays existing RRULE strings
• ✅ Integrates with Rails forms seamlessly

Dependencies

Ruby Gems

# Gemfile
gem 'rrule'  # For parsing and generating occurrences from RRULE strings

JavaScript

• Stimulus (already included in Rails 7+ with Hotwire)
• No additional JavaScript dependencies required

Installation

1. Copy the Stimulus Controller

Copy app/javascript/controllers/rrule_builder_controller.js to your Rails app:

# In your Rails app
cp /path/to/rrule_builder_controller.js app/javascript/controllers/

2. Register the Controller

Ensure the controller is registered in app/javascript/controllers/index.js:

import RruleBuilderController from "./rrule_builder_controller"
application.register("rrule-builder", RruleBuilderController)

3. Add Model Support

Add the necessary fields to your model:

# Migration
class AddScheduleFieldsToYourModel < ActiveRecord::Migration[7.0]
  def change
    add_column :your_models, :dtstart, :datetime
    add_column :your_models, :rrule, :string
    add_column :your_models, :duration, :string  # ISO8601 duration format (e.g., "PT1H30M")
  end
end

Update your model:

# app/models/your_model.rb
class YourModel < ApplicationRecord
  # Parse RRULE and generate occurrences
  def occurrences(limit: nil)
    return [dtstart] if rrule.blank?
    
    options = { dtstart: dtstart }
    options[:tzid] = timezone if respond_to?(:timezone) && timezone.present?
    
    rrule_instance = RRule::Rule.new(rrule, **options)
    limit ? rrule_instance.all(limit: limit) : rrule_instance.all
  end
  
  def has_schedule?
    dtstart.present? || rrule.present?
  end
end

4. Update Strong Parameters

Add schedule fields to your controller's strong parameters:

# app/controllers/your_controller.rb
def your_model_params
  params.require(:your_model).permit(:dtstart, :rrule, :duration, ...)
end

Usage

Basic Form Integration

Add the RRule builder to your form:

<!-- app/views/your_models/_form.html.erb -->
<%= form_with model: [@account, @your_model] do |form| %>
  
  <!-- Start Date/Time Field -->
  <div class="form-group">
    <%= form.label :dtstart, "Start Date/Time", class: "form-label" %>
    <%= form.datetime_local_field :dtstart, 
          class: "form-control", 
          data: { 
            action: "change->rrule-builder#dtstartChange" 
          } %>
  </div>

  <!-- RRule Builder -->
  <div class="form-group" 
       data-controller="rrule-builder" 
       data-rrule-builder-initial-rrule-value="<%= @your_model.rrule || '' %>">
    
    <%= form.label :rrule, "Recurrence Rule", class: "form-label" %>
    <%= form.hidden_field :rrule,
          data: { 
            "rrule-builder-target": "input"
          } %>

    <div class="space-y-4 rounded-lg border border-gray-200 p-4">
      <!-- Recurring Toggle -->
      <div class="space-y-2">
        <p class="text-sm font-medium text-gray-700">Recurring Event?</p>
        <div class="flex items-center gap-4 text-sm text-gray-700">
          <label class="inline-flex items-center gap-2">
            <input type="radio" 
                   name="event-recurring" 
                   value="no" 
                   checked="checked" 
                   data-action="change->rrule-builder#recurringToggle">
            <span>No</span>
          </label>
          <label class="inline-flex items-center gap-2">
            <input type="radio" 
                   name="event-recurring" 
                   value="yes" 
                   data-action="change->rrule-builder#recurringToggle">
            <span>Yes</span>
          </label>
        </div>
      </div>

      <!-- Recurring Rules (shown when "Yes" is selected) -->
      <div id="recurring-rules" 
           class="space-y-4" 
           style="display:none;" 
           data-rrule-builder-target="recurringRules">
        
        <!-- Frequency Selection -->
        <div class="space-y-2">
          <label class="text-sm font-medium text-gray-700">Frequency</label>
          <select name="freq" 
                  class="form-select w-full" 
                  data-action="change->rrule-builder#frequencyChange">
            <option value="daily" class="days">Daily</option>
            <option value="weekly" class="weeks">Weekly</option>
            <option value="monthly" class="months">Monthly</option>
            <option value="yearly" class="years">Yearly</option>
          </select>
        </div>

        <!-- Interval -->
        <div class="space-y-2">
          <label class="text-sm font-medium text-gray-700">Interval</label>
          <div class="flex items-center gap-2 text-sm text-gray-700">
            <span>Every</span>
            <input type="number" 
                   name="interval" 
                   value="1" 
                   min="1" 
                   class="form-control w-20" 
                   data-action="input->rrule-builder#intervalChange">
            <span class="freq-selection" 
                  data-rrule-builder-target="freqSelection">day(s)</span>
          </div>
        </div>

        <!-- Weekday Selection (shown for weekly) -->
        <div id="weekday-select" 
             class="weeks-choice space-y-2" 
             style="display:none;" 
             data-rrule-builder-target="weekdaySelect">
          <p class="text-sm font-medium text-gray-700">Days of the week</p>
          <div class="flex flex-wrap gap-2">
            <% %w[SU MO TU WE TH FR SA].each do |day| %>
              <button type="button" 
                      class="rounded border px-3 py-1 text-sm font-medium text-gray-700" 
                      id="<%= day %>" 
                      data-action="click->rrule-builder#weekdayClick">
                <%= day %>
              </button>
            <% end %>
          </div>
        </div>

        <!-- End Condition -->
        <div id="until-rules" 
             class="space-y-4" 
             style="display:none;" 
             data-rrule-builder-target="untilRules">
          <p class="text-sm font-medium text-gray-700">End condition</p>
          
          <label class="flex flex-col gap-2 rounded border border-gray-200 p-3 text-sm text-gray-700" 
                 for="count-select">
            <span class="inline-flex items-center gap-2">
              <input type="radio" 
                     name="end-select" 
                     value="count" 
                     id="count-select" 
                     checked="checked" 
                     data-action="change->rrule-builder#endSelect">
              <span>Number of occurrences</span>
            </span>
            <input type="number" 
                   name="count" 
                   min="1" 
                   max="50" 
                   value="1" 
                   step="1" 
                   class="form-control w-28" 
                   data-action="input->rrule-builder#countChange">
          </label>
          
          <label class="flex flex-col gap-2 rounded border border-gray-200 p-3 text-sm text-gray-700" 
                 for="until-select">
            <span class="inline-flex items-center gap-2">
              <input type="radio" 
                     name="end-select" 
                     value="until" 
                     id="until-select" 
                     data-action="change->rrule-builder#endSelect">
              <span>Specific date</span>
            </span>
            <input type="datetime-local" 
                   name="until" 
                   class="form-control" 
                   disabled 
                   data-action="change->rrule-builder#untilDateChange">
          </label>
        </div>
      </div>
    </div>

    <p class="text-sm text-gray-500 mt-1">Leave blank for one-off events</p>
  </div>

  <%= form.submit "Save", class: "btn btn-primary" %>
<% end %>

Controller Targets

The Stimulus controller uses the following targets:

• input - The hidden field that stores the generated RRULE string
• recurringRules - Container for recurring rule options
• untilRules - Container for end condition options
• freqSelection - Span that displays the frequency label (day/week/month/year)
• weekdaySelect - Container for weekday selection buttons
• monthdaySelect - Container for month day selection
• bymonthSelect - Container for yearly month selection
• yearlyMultipleMonthsButtons - Container for yearly multiple month buttons

Controller Values

• initialRrule - An existing RRULE string to parse and display (optional)

Action Methods

All interactions use Stimulus data-action attributes:

• recurringToggle - Toggle between recurring and one-off
• frequencyChange - Change frequency (daily/weekly/monthly/yearly)
• intervalChange - Update interval value
• weekdayClick - Toggle weekday selection
• monthdayClick - Toggle month day selection
• monthdayPosSelect - Switch between specific days and relative patterns
• monthBydayChange - Update monthly relative pattern
• yearlyOptions - Switch yearly pattern type
• yearlyMonthClick - Toggle yearly month selection
• yearlySelectsChange - Update yearly select values
• endSelect - Switch between count and until date
• countChange - Update occurrence count
• untilDateChange - Update until date
• dtstartChange - Update when start date changes

Generated RRULE Format

The controller generates RRULE strings in iCalendar format:

FREQ=DAILY;INTERVAL=1;DTSTART=20240101T040000Z;COUNT=10
FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE,FR;DTSTART=20240101T040000Z;UNTIL=20241231T235959Z
FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15;DTSTART=20240101T040000Z;COUNT=12

Key Points:

• Property names are uppercase (FREQ, INTERVAL, BYDAY, etc.)
• FREQ values are uppercase (DAILY, WEEKLY, MONTHLY, YEARLY)
• DTSTART format: YYYYMMDDTHHMMSSZ
• UNTIL format: YYYYMMDDTHHMMSSZ
• Multiple values are comma-separated (e.g., BYDAY=MO,WE,FR)

Styling

The component uses Tailwind CSS classes. You can customize the styling by:

1. Modifying the classes in your form partial
2. Adding custom CSS for the .active class on buttons
3. Adjusting the border, padding, and spacing classes

Example button styling:

/* Active state for weekday/monthday buttons */
button.active {
  @apply bg-primary text-white;
}

Advanced Features

Monthly Patterns

The builder supports two monthly pattern types:

1. Specific Days - Select specific days of the month (1-31)
2. Relative Patterns - "First Monday", "Last Friday", etc.

Yearly Patterns

Three yearly pattern types:

1. One Month - Specific month and day (e.g., "January 15")
2. Multiple Months - Select multiple months with the same day
3. Precise Pattern - "First Monday of January", "Last Friday of December", etc.

Integration with Other Controllers

The RRULE builder can trigger other Stimulus controllers when the RRULE changes:

<%= form.hidden_field :rrule,
      data: { 
        "rrule-builder-target": "input",
        action: "input->your-controller#handleRruleChange"
      } %>

Example: Displaying Occurrences

# In your controller
def show
  @your_model = YourModel.find(params[:id])
  @occurrences = @your_model.occurrences(limit: 50) if @your_model.has_schedule?
end

<!-- In your view -->
<% if @your_model.has_schedule? %>
  <h3>Upcoming Sessions</h3>
  <ul>
    <% @occurrences.each do |occurrence| %>
      <li><%= occurrence.strftime("%B %d, %Y at %I:%M %p") %></li>
    <% end %>
  </ul>
<% end %>

Troubleshooting

RRULE not generating

• Ensure the dtstart field has a value
• Check that "Recurring Event?" is set to "Yes"
• Verify the hidden field has the correct data-rrule-builder-target="input" attribute

Existing RRULE not parsing

• Ensure the RRULE string is in valid iCalendar format
• Check that data-rrule-builder-initial-rrule-value is set correctly
• Verify the RRULE includes both FREQ and DTSTART

Styling issues

• Ensure Tailwind CSS is properly configured
• Check that button .active class styles are defined
• Verify form control classes match your design system

Credits

Based on the logic from rrule-generator-form but rewritten as a modern Stimulus controller without jQuery UI dependencies.