MultiDatePick User Guide

1. The three components — when to use each

MultiDatePick ships three Lightning Web Components on a shared base. Pick the one that matches your data shape:

Feature comparison

Features cascade upward: anything available on Dates is also available on DateTime and Booking. DateTime adds time. Booking adds resources + capacity on top of that.

2. Data shapes — when to use each

Data shape is the combination of three independent choices. Pick any combination — the wrapper supports them all.

Worked examples — walk through the 3 questions

For each scenario below, answer 3 questions to land on a data shape. This is the same flow the Setup Wizard walks you through.

The grid — every combination

Pick the row that matches your time + resource needs, then choose per-click or per-range based on whether endDateField is mapped. Every cell is a valid configuration.

Bottom line: any combination of the 3 steps works. If your scenario doesn't match one of the named patterns, just configure each step independently — the wrapper figures it out.

3. Setup Wizard walkthrough

The Setup Wizard turns a configuration into a reusable Custom Metadata record. Same wizard, same record — place anywhere with a configName reference. Five steps:

Step 0 — Path picker

The wizard greets new admins with three paths: Shape (pick from the 6 shapes above), Full (skip the shape picker and configure every prop manually), or Existing (load a saved config). Pick what fits.

Step 1 — Component Type, Config Name, Label

Pick which component you're configuring (Dates / DateTime / Booking). The Config Name is the developer name of the CMT record — admins reference it via the wrapper's configName property. Label is the human-readable name.

Tier note: If you pick DateTime or Booking but you're on the Dates tier, the wizard shows an info banner. You can still configure the component now — the saved config will start working as soon as you upgrade.

Step 2 — Object & Fields

The big one. Pick the related object (e.g. Schedule__c or your own), the Date Field, the Relationship Field back to the parent, and any optional fields (End Date for ranges, Sub-Block fields for parent+sub-block shape).

Step 3 — Resource & Capacity (Booking only)

Pick the Resource object, Capacity field, Business Hours fields, and (optional) Resource Filter to scope the picker (e.g. Active__c=true). The Dates and DateTime components grey out this step.

Step 4 — Status & Display

Status Field (for color-coding), Status Colors mapping (e.g. Confirmed:#0176d3, Tentative:#fbbf24), Edit Mode toggle, display options, sub-block button label.

Step 5 — Constraints & Behavior

Max selections, allow past dates, recurring pattern, blocked dates source, conflict look-ahead days, preload mode.

Save & deploy

Click Save Configuration. The wizard fires an Apex deploy that creates the Custom Metadata Type record. Wait ~30–60 seconds for deploy to complete. Optionally add a description via the post-save card.

4. Click to Save vs Flow-Managed Save

The wrapper supports two persistence patterns. Pick the one that fits where you're placing it:

Click to Save — the 4 props

Set these on the wrapper (the Setup Wizard does it for you). When all four are populated, the Save button appears:

• relatedObjectApiName — the child object that records get inserted into
• dateFieldApiName — the Date field on that object
• relationshipFieldApiName — the lookup back to the parent record
• recordId (auto-injected on Record Pages) or staticRecordId (hardcoded for App Page / Home Page / Experience Site surfaces, which don't get a record context)

Flow-Managed Save — the output props

Leave the four Click-to-Save props blank. The wrapper hides its Save button and emits selections through these Flow output variables:

• selectedDates — Text collection of ISO date strings (YYYY-MM-DD)
• selectedDateRangesJson — JSON of grouped contiguous ranges
• selectedDatesWithTimesJson — JSON of dates with per-date times (DateTime only)
• bookingSuccessCount / bookingConflictDates — Booking-specific outputs after the wrapper's own save runs (only relevant if you mix the two modes)

Use the bundled Parse Date Entries from JSON invocable action to convert the JSON into a Flow-loopable MultiDatePickEntryCollection with .data[] of MultiDatePickEntry records (fields: fromDate, toDate, startTime, endTime, resourceId). Loop over .data, do whatever persistence pattern fits.

Additive-only save (applies to Click to Save)

By design, saveDateRecordsAdditive only INSERTs new dates — it never deletes existing records when the user deselects a date. To delete, admins use the standard Salesforce related-list UI on the parent record. This prevents accidental data loss when an admin clicks the wrong date.

5. Status colors & edit mode

Status colors

Map any picklist field on your child object to colors. The wrapper paints the calendar (and grid, if you choose) accordingly. Configure:

• statusField = Status__c (or your picklist API name)
• statusColors = Confirmed:#0176d3, Tentative:#fbbf24, Pending:#60a5fa, Cancelled:#a1a8b5
• statusColorDisplay = calendar, grid, or both
• hideBookingsWithStatus = Cancelled (CSV) to suppress those records from the calendar AND capacity counts

Edit mode

Set enableEditMode=true. The wrapper shows an Edit Dates button. Click it to toggle into edit mode, where:

• Existing records render as cards with their date and current status visible
• Click a date in the calendar to add it to the edit set
• Change a record's date or status — the wrapper updates the database
• Delete a record with a two-click confirm pattern (prevents accidents)

The status field stays in sync with the database after every edit.

6. Resource booking (Booking component only)

Single-resource mode

The wrapper renders a resource picker dropdown. Admins pick one resource, the time-slot grid loads with that resource's bookings + capacity. Each booked slot shows an X/Y capacity badge.

Multi-resource mode

Set allowMultipleResources=true. The picker becomes a checkbox list. Multiple checked resources show a combined capacity grid — sum of all bookings across selected resources, sum of all capacities.

Capacity aggregation modes

The capacityAggregation property controls the multi-resource math:

• Combined (default) — sum bookings + sum capacities. Example: 2 conference rooms each holding 5 = 0/10 capacity total.
• Distinct — count unique events (records sharing date+startTime+endTime across resources = ONE event). Uses MAX single-resource capacity. Example: a class booked across 4 rooms simultaneously reads as 1/5, not 4/20.

Conflict detection

conflictLookAheadDays controls how many days ahead the LWC scans for overlapping bookings. conflictBehavior controls what happens when conflicts are found: block (refuse to save), warn (toast then save), or skip (insert non-conflicting, skip the rest, report conflicts in bookingConflictDates).

7. Common gotchas (FAQ)

Real questions admins have hit. Skim these BEFORE filing a support ticket.

I see no calendar — just an amber banner

You have a component-type mismatch or parent-type mismatch. The banner explains what's wrong: either the CMT config was saved for a different component (e.g. a Dates config loaded into a DateTime wrapper), or the wrapper is on the wrong-object record page for the configured relationshipField. Fix the config or move the placement.

Past dates aren't being disabled even with allowPastDates=false

In Flow Builder, explicitly set the prop to {!$GlobalConstant.False} — don't rely on the JS default. Salesforce Flow passes null for unset Boolean props, which doesn't trigger the wrapper's "false" branch the way you'd expect.

My status colors aren't applying

Three things to check: (a) is statusField the exact picklist API name (case-sensitive, no quotes around the name)? (b) Does statusColors use the format Status:#hex, Status:#hex with NO quotes around values? Admins sometimes paste 'Confirmed':'#0176d3' — that breaks the parse silently. (c) Is the picklist value actually populated on the records?

The wrapper saves but records have wrong field values

Check recordNameField — if you mapped a long-text field, the wrapper writes the auto-generated name there but the field may be too short. Also check appendDateTimeToName: if ON, the wrapper appends the selected date/time to the record name — surprising if you didn't expect it.

How do I hide Cancelled records from the capacity grid?

Set hideBookingsWithStatus=Cancelled (or comma-separated list like Cancelled,Rejected). This filters Cancelled records from BOTH the calendar AND the capacity count.

The edit mode toggle isn't appearing

Edit mode requires enableEditMode=true AND a configured statusField. If either is missing, the toggle stays hidden.

I need a resource filter (only show conference rooms, not equipment)

Booking has resourceFilterField + resourceFilterValue. Single value: Active__c=true. IN-clause: Building__c=North,South. AND across fields: Type__c;Active__c=Conference Room;true.

Time selection mode in DateTime keeps reverting to shared

Two props can conflict: legacy timeSelectionMode and new timeDisplayMode. The setter ordering matters — timeDisplayMode='grid' wins per the priority guard, but if you set timeSelectionMode='shared' in App Builder and the LWC's setter order processes shared first, the legacy value can briefly override. Use timeDisplayMode exclusively.

How do I migrate from JSON output to auto-save?

Set recordId + relatedObjectApiName + dateFieldApiName + relationshipFieldApiName. Remove the downstream Apex action that parsed the JSON. The wrapper's own Save button now writes records directly.

I get a "AuraHandledException" but no detail message

Open browser DevTools → Console. Look for [MDP:ERROR]-prefixed logs. The wrapper always logs the underlying exception detail there, even when AuraHandledException strips it from the UI toast.

8. Object & field mapping

Each component page has the full Object/Field Mapping diagram. Quick links:

• multiDatePickDates — schema mapping
• multiDatePickDateTime — schema mapping
• multiDatePickBooking — schema mapping

Each diagram shows what wrapper prop maps to what object/field. The wrapper is fully object-agnostic — the bundled MDP_* object/field names are just defaults. Point any wrapper prop at any custom object with the right field shape.

9. Apex sample code

Reading selectedDates in a Flow

Use the bundled Parse Date Entries from JSON invocable action to convert the wrapper's JSON output into a Flow-loopable collection.

// Flow:
//   Screen with multiDatePickDateTime, outputs selectedDatesWithTimesJson
//   Action: Parse Date Entries from JSON, input = the JSON string
//   Output: MultiDatePickEntryCollection with .data[] of MultiDatePickEntry
//   Loop over .data, access .fromDate, .toDate, .startTime, .endTime per entry

Rollup MIN/MAX child dates to a parent field

A Record-Triggered Flow on the child object can roll up MIN/MAX dates to the parent. Example for Schedule__c rolling up to Event__c.Start_Date__c / End_Date__c:

trigger MDPScheduleRollup on Schedule__c (after insert, after update, after delete) {
    Set<Id> eventIds = new Set<Id>();
    if (Trigger.new != null) {
        for (Schedule__c s : Trigger.new) if (s.Event__c != null) eventIds.add(s.Event__c);
    }
    if (Trigger.old != null) {
        for (Schedule__c s : Trigger.old) if (s.Event__c != null) eventIds.add(s.Event__c);
    }
    if (eventIds.isEmpty()) return;

    Map<Id, Date> minByEvent = new Map<Id, Date>();
    Map<Id, Date> maxByEvent = new Map<Id, Date>();
    for (AggregateResult ar : [
        SELECT Event__c eventId, MIN(Schedule_Date__c) minD, MAX(Schedule_Date__c) maxD
        FROM Schedule__c
        WHERE Event__c IN :eventIds
        GROUP BY Event__c
    ]) {
        Id eid = (Id) ar.get('eventId');
        minByEvent.put(eid, (Date) ar.get('minD'));
        maxByEvent.put(eid, (Date) ar.get('maxD'));
    }

    List<Event__c> toUpdate = new List<Event__c>();
    for (Id eid : eventIds) {
        toUpdate.add(new Event__c(Id = eid,
            Start_Date__c = minByEvent.get(eid),
            End_Date__c = maxByEvent.get(eid)));
    }
    Database.update(toUpdate, false);
}

Replace Schedule__c / Event__c / Schedule_Date__c / etc. with your own schema.

10. Security & accessibility

• AppExchange Security Reviewed. The package passes Salesforce's Security Review and the sf code-analyzer AppExchange + Recommended:Security rule sets with zero violations.
• FLS-aware: every Apex method validates object + field access before SOQL/DML via validateObjectAndFieldAccess. All DML runs under Database.insert(records, AccessLevel.USER_MODE) so user permission checks are enforced at the database layer, not just the controller.
• Accessibility: WCAG 2.1 Level A/AA tested with axe-core. Full VPAT 2.5 at multidatepick.com/accessibility.html.
• 9 built-in languages: English, Spanish, French, German, Japanese, Hindi, Portuguese (Brazil), Italian, Chinese (Simplified).

11. Questions or bugs?

Found a gap in this guide, or something broken in the package? We want to hear about it.

Email: support@multidatepick.com