Recurring Events

Overview

Nigall supports recurring event series via recurrence_series_id, recurrence_rule JSON, and cloned event instances—created at event save time with configurable frequency and occurrence count.

Purpose

Reduce duplicate data entry for weekly meetups, monthly workshops, and multi-date programs while keeping independent capacity and RSVPs per instance.

Who should use it

  • Community organizers (weekly/biweekly meetups)
  • Training coordinators (monthly sessions)
  • Venue programs with repeating slots

Benefits

  • One form creates N linked events
  • Series edit scopes (single vs all future)
  • recurrence_summary() display on event cards
Action Path
Create with recurrence /events/create/ → Set up recurring event
Edit series instance /events/<pk>/<tag>/edit/
Series members Derived via event.series_members()

Prerequisites

  • Event create/edit permission as host
  • Clear start/end datetime for anchor event
  • Understand per-instance URLs (each clone has own pk and event_tag)

Step-by-step — Create recurring series

  1. Create Event → fill details.
  2. Check Set up recurring event (setup_recurrence).
  3. Select Frequency: daily, weekly, biweekly, monthly.
  4. Enter Occurrences count (total events in series).
  5. Save → materialize_recurring_events() clones instances.
  6. Flash message: "Created N recurring events successfully!"

[SCREENSHOT: Recurrence options on create form]

Step-by-step — Edit recurring event

  1. Edit any instance in series.
  2. Choose Edit scope:
    - This event only
    - This and future events
    - Entire series (when rescheduling)
  3. Frequency/occurrence changes may call reschedule_recurring_series().

Field descriptions

Field Description
recurrence_series_id UUID linking series members
recurrence_parent FK to parent event (if child)
recurrence_index 0 = anchor instance
recurrence_rule JSON: frequency, occurrences
setup_recurrence Form-only flag on create
recurrence_frequency daily / weekly / biweekly / monthly
recurrence_occurrences Integer count
recurrence_edit_scope Scope on edit POST

Recurrence summary labels

Frequency Label
daily Daily
weekly Weekly
biweekly Every 2 weeks
monthly Monthly

Business rules

Rule Detail
Anchor recurrence_index == 0 is series anchor
Independent RSVPs Each instance has own guest list
Tags Each clone gets unique event_tag
is_recurring True when recurrence_series_id set
Materialize on create Clones created in same transaction batch

Validation rules

  • Occurrences must be positive integer
  • Frequency required when setup_recurrence checked
  • End date after start date on anchor

User permissions

Action Host Staff
Create series ✅ ✅
Edit scope ✅ ✅
RSVP per instance ✅ ✅

Workflow

flowchart TD Create[Create anchor event] --> Flag[setup_recurrence=true] Flag --> Materialize[materialize_recurring_events] Materialize --> Instances[N events with shared series_id] Instances --> Share[Share per-instance URLs]

Examples

Weekly yoga: 12 occurrences, biweekly, private RSVP links per date.

Monthly webinar: Public registration series; Discover shows each dated instance.

Best practices

  • Set capacity per instance based on room size
  • Share correct instance URL in each calendar invite
  • Use series edit scope carefully to avoid unintended date shifts

Tips

  • series_members() queryset for admin scripts
  • Recurrence summary shown on event cards in My Events

Common mistakes

Mistake Result Fix
One link for whole series Wrong date RSVPs Share instance-specific URLs
Edit all when meaning one Mass date change Use single scope
Expecting shared guest list Per-event data Export per instance

FAQs

Do clones share modules?
Module toggles copied at creation; configure anchor before materialize when possible.

Can I add occurrences later?
Edit series or create new series extension (manual process).

Troubleshooting

Symptom Cause Fix
Only one event created Recurrence not checked Re-edit with setup_recurrence
Wrong dates Timezone / scope Verify anchor start_date

Screenshot placeholders

  • [SCREENSHOT: Recurrence checkbox and frequency dropdown]
  • [SCREENSHOT: My Events showing series summary badge]
  • [SCREENSHOT: Edit scope modal]

Administrator notes

  • Service: events/recurrence_services.py
  • Session flash: event_recurring_total in session

Developer/API notes

Function Purpose
materialize_recurring_events() Create clones
reschedule_recurring_series() Bulk date shift
recurrence_rule_values() Parse rule for forms

Mobile API treats each instance as separate event record.

See also: Event Field Reference

Help home Back to Nigall