Skip to content

Add advanced datetime and range selection documentation #1495

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sbishel wants to merge 3 commits into
base: master
Choose a base branch
from
+316 −0
Open

Add advanced datetime and range selection documentation #1495

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0c52d3c
Add advanced datetime and range selection documentation
sbishel Feb 11, 2026
fa0a798
Merge branch 'master' into interactive-dialog
sbishel Feb 17, 2026
c886043
Merge branch 'master' into interactive-dialog
sbishel Mar 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
316 changes: 316 additions & 0 deletions site/content/integrate/plugins/interactive-dialogs/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -567,6 +567,322 @@ The full list of supported fields for `datetime` elements is included below:
- `time_interval: 60` creates options: 00:00, 01:00, 02:00, 03:00, etc.
- Invalid: `time_interval: 7` (7 is not a divisor of 1440)

#### Advanced DateTime Configuration (v11.6)

For more advanced datetime field features, use the `datetime_config` object to group related properties. This approach provides better organization and enables new features like timezone support and manual time entry.

**DialogDateTimeConfig Structure:**

```json
{
"display_name": "Event Time",
"name": "event_time",
"type": "datetime",
"help_text": "When is your event?",
"datetime_config": {
"time_interval": 30,
"location_timezone": "America/New_York",
"allow_manual_time_entry": true
}
}
```

**datetime_config Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `time_interval` | Integer | Time selection interval in minutes (1-1440, must be divisor of 1440). Default: 60. |
| `location_timezone` | String | IANA timezone for displaying times (e.g., "America/New_York", "Europe/London", "Asia/Tokyo"). When set, times are shown in this timezone with an indicator. Values are still stored in UTC. |
| `allow_manual_time_entry` | Boolean | When `true`, shows a text input for typing times instead of dropdown. Supports formats: `9am`, `3:45pm`, `14:30`, `12a`. Default: `false`. |
Comment on lines +592 to +596
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Clarify whether datetime submissions stay in UTC or preserve an offset.

This section says location_timezone values are stored in UTC and the example submits ...Z, but the existing submission docs later in the page say datetime values are sent as RFC3339 strings with an offset. Those two contracts are not interchangeable, and integrators will parse them differently. Please make the property description and examples match the actual submission format end-to-end.

Also applies to: 639-644, 684-688


**Backward Compatibility:**

The original flat structure is still supported:
```json
{
"type": "datetime",
"time_interval": 30, // Legacy format
"min_date": "today",
"max_date": "+7d"
}
```

New features require `datetime_config`:
```json
{
"type": "datetime",
"min_date": "today", // Can use legacy fields alongside datetime_config
"datetime_config": {
"time_interval": 30,
"location_timezone": "Asia/Tokyo"
}
}
```

**Timezone Support Example:**

Display event times in a specific timezone (useful for global teams):

```json
{
"display_name": "London Office Hours",
"name": "london_time",
"type": "datetime",
"help_text": "Times shown in GMT (with 🌍 indicator)",
"datetime_config": {
"location_timezone": "Europe/London",
"time_interval": 60
}
}
```

**Behavior:**
- User in Denver (UTC-7) sees times in London (GMT)
- Dropdown shows: 00:00, 01:00, 02:00 (London time)
- User selects 14:00 (2 PM London)
- Value submitted: `2024-03-15T14:00:00Z` (UTC)
- 🌍 indicator shows "Times in GMT"

Comment on lines +624 to +645
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Avoid DST-sensitive timezone labels in the London example.

Europe/London is not always GMT, and Denver is not always UTC-7. Hard-coding those labels makes the example wrong for part of the year. Using the IANA zone names in the prose, or anchoring the example to a specific date when GMT/UTC-7 applies, would keep this accurate year-round.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@site/content/integrate/plugins/interactive-dialogs/_index.md` around lines
624 - 645, The example uses DST-sensitive labels (the prose "GMT" and "UTC-7"
and the JSON "location_timezone": "Europe/London"), which can be incorrect part
of the year; update the prose and example so it uses the IANA zone name (e.g.,
reference "Europe/London" and "America/Denver") instead of fixed GMT/UTC offsets
or explicitly anchor the example to a specific date (e.g., include the date used
for the conversion like "2024-03-15") and adjust the displayed/returned time
accordingly; change the help_text/indicator from "Times shown in GMT" to
something like "Times shown in Europe/London (may observe DST)" or otherwise
clarify DST behavior so the fields "display_name", "help_text",
"datetime_config.location_timezone" and the prose around the 🌍 indicator are
consistent and accurate year-round.

**Manual Time Entry Example:**

Allow users to type exact times instead of selecting from dropdown:

```json
{
"display_name": "Precise Event Time",
"name": "event_time",
"type": "datetime",
"help_text": "Type exact time: 9am, 14:30, 3:45pm",
"datetime_config": {
"allow_manual_time_entry": true
}
}
```

**Behavior:**
- Text input shown instead of dropdown
- Accepts formats: `12a`, `3:45pm`, `14:30`, `9pm`
- No rounding - exact minutes preserved
- Respects user's 12h/24h display preference
- Shows placeholder `--:--` until time entered

**Combined Example (Timezone + Manual Entry):**

```json
{
"display_name": "Tokyo Meeting Time",
"name": "tokyo_meeting",
"type": "datetime",
"help_text": "Enter time in JST (Japan Standard Time)",
"datetime_config": {
"location_timezone": "Asia/Tokyo",
"allow_manual_time_entry": true
}
}
```

**Behavior:**
- Shows times in Tokyo timezone
- User can type exact time (e.g., `10:30am`)
- 🌍 indicator shows "Times in JST"
- Value stored in UTC after conversion

**Supported Time Formats (Manual Entry):**
- Short 12-hour: `9a`, `3p`
- Full 12-hour: `9:15am`, `3:45pm`, `12:30 PM`
- 24-hour: `14:30`, `09:15`, `00:00`
- Without minutes: `9am` → `09:00`, `14` → `14:00`

#### Date and DateTime Range Selection (v11.6)

Date and DateTime fields can be configured as range selectors, allowing users to select a start and end date (and optionally time). This is useful for booking systems, event scheduling, and time-period selections.

##### Date Range Configuration

Date ranges use the `datetime_config` object to enable range functionality:

```json
{
"display_name": "Event Date Range",
"name": "event_dates",
"type": "date",
"help_text": "Select start and end dates for your event",
"optional": false,
"datetime_config": {
"is_range": true,
"allow_single_day_range": false
}
}
```

**Date Range Behavior:**
- Users select both a start date and end date using a single calendar picker
- The calendar allows drag-selection for quickly choosing a range
- Once a start date is selected, users can click to select the end date
- Submitted as an array: `["2024-03-15", "2024-03-20"]`

##### DateTime Range Configuration

DateTime ranges display separate start and end fields with both date and time selection:

```json
{
"display_name": "Meeting Time Range",
"name": "meeting_times",
"type": "datetime",
"help_text": "Select start and end times for your meeting",
"optional": false,
"datetime_config": {
"is_range": true,
"range_layout": "horizontal",
"allow_single_day_range": true,
"time_interval": 30
}
}
```

**DateTime Range Behavior:**
- Displays two separate datetime pickers labeled "Start Date & Time" and "End Date & Time"
- Each picker has independent date and time selection
- End date picker automatically disables dates before the start date
- Submitted as an array: `["2024-03-15T09:00:00-05:00", "2024-03-15T17:00:00-05:00"]`

##### Range Configuration Options

The `datetime_config` object supports the following range-specific properties:

| Field | Type | Description |
|-------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------|
| `is_range` | Boolean | Set to `true` to enable range selection. Default is `false`. |
| `range_layout` | String | (DateTime ranges only) Layout for start/end fields: `"horizontal"` (side-by-side) or `"vertical"` (stacked). Default is `"horizontal"`. |
| `allow_single_day_range`| Boolean | Set to `true` to allow selecting the same day for start and end dates. Default is `false`. |
| `time_interval` | Integer | (DateTime ranges only) Time selection interval in minutes. Applies to both start and end time pickers. Default is 60. |

**Note:** When using `datetime_config` for ranges, the `time_interval` property within `datetime_config` takes precedence over the top-level `time_interval` field.

##### Range Usage Examples

**Basic date range (vacation booking):**
```json
{
"display_name": "Vacation Dates",
"name": "vacation",
"type": "date",
"help_text": "Select your vacation start and end dates",
"optional": false,
"min_date": "today",
"max_date": "+365d",
"datetime_config": {
"is_range": true,
"allow_single_day_range": false
}
}
```

**DateTime range with horizontal layout (meeting scheduler):**
```json
{
"display_name": "Meeting Window",
"name": "meeting_window",
"type": "datetime",
"help_text": "Select the meeting start and end times",
"optional": false,
"min_date": "today",
"max_date": "+30d",
"datetime_config": {
"is_range": true,
"range_layout": "horizontal",
"allow_single_day_range": true,
"time_interval": 15
}
}
```

**DateTime range with vertical layout (conference session):**
```json
{
"display_name": "Session Time Slot",
"name": "session_slot",
"type": "datetime",
"help_text": "Select when your session starts and ends",
"optional": false,
"datetime_config": {
"is_range": true,
"range_layout": "vertical",
"allow_single_day_range": true,
"time_interval": 30
}
}
```

**Date range allowing single-day events:**
```json
{
"display_name": "Event Duration",
"name": "event_duration",
"type": "date",
"help_text": "Select event dates (can be a single day)",
"optional": false,
"min_date": "today",
"datetime_config": {
"is_range": true,
"allow_single_day_range": true
}
}
```

##### Range Validation

**Required Range Fields:**
- Both start and end dates must be selected for required fields
- Submitting with only a start date will show a validation error with code `"range_incomplete"`
- Optional range fields with only a start date are considered valid

**Date Constraints:**
- For datetime ranges, the end date picker automatically disables dates before the start date
- If `allow_single_day_range` is `false`, the start date itself is also disabled in the end picker
- If `allow_single_day_range` is `true`, users can select the same date for both start and end

**Form Submission Format:**
- Date ranges submit as string arrays: `["2024-03-15", "2024-03-20"]`
- DateTime ranges submit as string arrays with timezone: `["2024-03-15T09:00:00-05:00", "2024-03-15T17:00:00-05:00"]`
- Empty optional range fields submit as `null` or empty array
Comment on lines +836 to +849
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Document the payload for a partially filled optional range.

These lines say an optional range with only a start date is valid, but the submission section only shows full two-value arrays and empty/null cases. Please spell out the exact payload shape for the partial case as well, otherwise consumers cannot implement reliable parsing or validation.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@site/content/integrate/plugins/interactive-dialogs/_index.md` around lines
836 - 849, Update the "Form Submission Format" section to document the partial
payload shape: state that an optional range with only a start date submits as a
single-element array (e.g. ["2024-03-15"] for date ranges and
["2024-03-15T09:00:00-05:00"] for datetime ranges), and clarify this contrasts
with empty optional ranges (null or []) and full ranges (two-element arrays).
Reference the existing headings "Required Range Fields", "Date Constraints", and
the allow_single_day_range examples so readers can see how the partial case
relates to optional fields and datetime handling.


##### Combining Range with Other Features

Range functionality can be combined with other `datetime_config` properties:

**Range with timezone:**
```json
{
"display_name": "Global Meeting Window",
"name": "global_meeting",
"type": "datetime",
"help_text": "Select times in London timezone",
"datetime_config": {
"is_range": true,
"range_layout": "horizontal",
"location_timezone": "Europe/London",
"time_interval": 30
}
}
```

**Range with manual time entry:**
```json
{
"display_name": "Precise Event Timeframe",
"name": "event_timeframe",
"type": "datetime",
"help_text": "Type exact start and end times",
"datetime_config": {
"is_range": true,
"allow_manual_time_entry": true,
"allow_single_day_range": true
}
}
```

## Dialog submission

When a user submits a dialog, Mattermost will perform client-side input validation to make sure:
Expand Down
Loading