Fields, Placeholders & Matching Rules

Define custom service components once, extract values automatically from raw text using regular expressions, and bind them directly to 16:9 canvas slide layouts.

Written for WorshipDeck 0.1.2

End-to-End Pipeline

Instead of manually retyping names, sermon topics, and announcements into individual slide text boxes each week, WorshipDeck connects intake text directly to presentation graphics through a six-stage pipeline:

1. ADMIN DEFINES FIELD & REGEX
   Artifacts → Layout & Fields → Predefined Fields & Regex
   Define variable_name (e.g. song_leader) and extraction_regex
                    │
                    ▼
2. ADMIN GROUPS FIELDS INTO CARDS
   Card Groupings & Layout → Assign field to a service form card
                    │
                    ▼
3. ADMIN TESTS IN THE SANDBOX
   Rundown Test Area & Sandbox → Test with real service text
                    │
                    ▼
4. ADMIN BINDS PLACEHOLDER TO CANVAS
   Main spine → Canvas Editor → Insert text: "Led by {song_leader}"
                    │
                    ▼
5. OPERATOR PASTES ORDER OF SERVICE
   Services → New → Paste raw rundown → Click Parse
                    │
                    ▼
6. RUNTIME HYDRATION & EXPORT
   {song_leader} resolves to extracted name on screen & PPTX

Predefined Field Definitions

Navigate to Artifacts → Layout & Fields and select the Predefined Fields & Regex sub-tab. Each custom field specifies how text is stored, edited, and matched:

Property Requirement Description
Variable Name ^[a-z][a-z0-9_]{1,63}$ Unique token key. Must start with a lowercase letter, contain only lowercase letters, digits, and underscores, and cannot use reserved system names (such as id, service_id, created_at, title).
Field Label 1 to 100 characters Human-readable display title rendered above the input control on the service intake form.
Field Type text or text_area Single-line text for short entries (names, scripture references), or multi-line text area for notes. Field type image is reserved for uploaded assets and does not support regular expressions.
Extraction Regex Valid RE2 pattern Regular expression used to scan raw order-of-service text line by line. Optional; fields without regex are entered manually by the operator.

After defining a field, switch to the Card Groupings & Layout sub-tab to assign the field to an existing service card or create a new card container. Fields not assigned to a card group will not appear on the service form.

RE2 Patterns and Named Groups

WorshipDeck uses the RE2 regular expression engine for fast, linear-time matching. Because RE2 is strictly regular, certain constructs found in other engines are intentionally unsupported:

  • Supported: Inline case-insensitive flags (?i), non-capturing groups (?:...), character classes, and standard quantifiers (*, +, ?).
  • Prohibited: Lookahead assertions ((?=...), (?!...)), lookbehind assertions ((?<=...), (?<!...)), and backreferences (\1). The server rejects invalid patterns with a descriptive error.

Named Capturing Groups

When a line matches your pattern, the parser extracts the target value using named groups. Use standard group syntax:

Group Name Purpose Example Syntax
value Primary text value to insert into the form field. If absent, the parser falls back to the first positional capturing group, or the full match. (?i)^Song\s+Leader\s*:\s*(?<value>.+)$
number Hymn number for hymn card slot entries. Automatically triggers local hymnal lookup. (?i)^Opening\s+Hymn\s*#?\s*(?<number>\d+)
book Optional songbook code (defaulting to SDAH if omitted). (?i)^Hymn\s*#?(?<number>\d+)\s*\((?<book>[A-Z]+)\)

Rundown Test Area & Sandbox

To verify regular expressions before saving changes to your live service schema, use the Rundown Test Area & Sandbox sub-tab under Artifacts → Layout & Fields. The sandbox operates entirely in memory and will not alter existing services or database records.

  1. Card A: Full Rundown Testing

    Paste an entire historical order of service into the test area and click Test Rundown. The sandbox displays each active field with a status indicator: Matched (showing the extracted value), Empty Regex (for manual fields), or Unmatched. Unmatched lines appear in a separate review box below the results.

  2. Card B: Single Regex Inspection

    Enter a single candidate line of text and a proposed regular expression pattern, then click Evaluate Pattern. The inspector shows whether the pattern matched, the extracted value, and a table of all populated named capturing groups with their respective character offsets.

Regular expressions are evaluated line by line with leading and trailing whitespace trimmed. The first line matching a pattern wins. If no individual line matches, the parser runs the pattern once across the entire multiline text block as a fallback.

Canvas Placeholder Binding

Once a field is established, bind its variable name to any text element on the visual layout canvas:

  1. Open Artifacts → Main spine and click a layout to edit, or create a new layout.
  2. Add a new text box or double-click an existing text element.
  3. Type the variable name enclosed in curly brackets, for example Led by {song_leader} or Speaker: {preacher}. Alternatively, click Insert placeholder from the toolbar to select from registered tokens.
  4. Click Save Layout. If a typed placeholder token does not exist in the field catalog, the canvas displays a yellow warning icon, but saving is not blocked.

Runtime Hydration Rules

When an operator clicks Parse on the New Service form, WorshipDeck populates each form field. When slides are presented in the operator console or exported to PowerPoint, the runtime engine hydrates each slide according to three rules:

Condition Engine Behavior
Value Present The token {variable_name} is replaced inline with the parsed or operator-edited text string, preserving all surrounding text, font styling, and alignment.
Value Empty (Optional Element) If an element contains only a placeholder token (e.g. {special_item}) and its extracted value is empty, the entire element is omitted from the rendered slide to prevent empty boxes or awkward spacing. If the element contains surrounding static text, the token is replaced with an empty string.
Value Empty (Required Element) If an element is marked as required in the layout and its bound placeholder has no value, slide generation fails with an explicit error: missing required placeholder: variable_name.

Built-In Seed Patterns

WorshipDeck includes 13 predefined seed fields covering standard Christian worship liturgy. Click Seed Defaults in the Predefined Fields panel to load them:

Variable Name Default Label Example Input Line Recommended Regex
song_leader Song Leader Song Leader: Br. Daniel (?i)^(?:Song\s+Leader|Pemimpin\s+Pujian)\s*[:\-]\s*(?<value>.+)$
preacher Preacher / Speaker Sermon: Pr. Arthur Pendelton (?i)^(?:Sermon|Speaker|Khotbah|Pembicara)\s*[:\-]\s*(?<value>.+)$
sermon_title Sermon Title Title: Steady Light (?i)^(?:Title|Judul\s+Khotbah|Tema)\s*[:\-]\s*(?<value>.+)$
scripture_reader Scripture Reader Scripture Reading: Sis. Sarah (?i)^(?:Scripture\s+Reading|Bacaan\s+Alkitab)\s*[:\-]\s*(?<value>.+)$
scripture_ref Scripture Reference Reading: John 3:16-17 (?i)^(?:Reading|Ayat\s+Alkitab|Nats)\s*[:\-]\s*(?<value>.+)$
Never paste confidential personal data, sensitive prayer requests, or private contact details into extraction templates or seed pattern examples in shared repositories.