Skip to content

Add documentation for the timestamp field's timezone option #620

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

Merged
AlexGaillard merged 2 commits into from
Apr 8, 2026
Merged

Add documentation for the timestamp field's timezone option #620

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ffe49eb
add timezone option to datetime interface section
robluton Apr 8, 2026
c9a2b96
formatting
robluton Apr 8, 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
121 changes: 61 additions & 60 deletions content/guides/01.data-model/3.interfaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,15 +152,17 @@ A checkbox input that allows user to toggle boolean values.

Date picker input that allows user to select a date and time.

| Configuration | Options |
| ------------------ | --------------------------------------- |
| Types | `DateTime`, `Date`, `Time`, `Timestamp` |
| Include Seconds | Show seconds in the interface. |
| Use 24-Hour Format | Use 24 hour time system. |
| Configuration | Options |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| Types | `DateTime`, `Date`, `Time`, `Timestamp` |
| Include Seconds | Show seconds in the interface. |
| Use 24-Hour Format | Use 24 hour time system. |
| Timezone | Select an IANA timezone identifier for display and input conversion. Only available for `Timestamp`. |

::callout{icon="material-symbols:info-outline"}
**Handling Timezones**
- `Timestamp` normalizes values to UTC and returns them in ISO 8601 format with the `Z` suffix (e.g. 2024-01-15T09:00:00.000Z).

- `Timestamp` normalizes values to UTC and returns them in ISO 8601 format with the `Z` suffix (e.g. 2024-01-15T09:00:00.000Z). When a **Timezone** is configured on a `Timestamp` field, the Data Studio converts stored UTC values to that timezone for display, and converts input back to UTC before saving. The API always returns UTC.
- `DateTime` stores values without timezone information and returns them in ISO 8601 format (e.g. 2024-01-15T10:00:00). The stored value depends on the database vendor's format and database timezone, while the returned value is dependent on the server's `TZ` environment variable.

System fields `date_created` and `date_updated` use `Timestamp`.
Expand Down Expand Up @@ -292,45 +294,46 @@ Nested tree of checkboxes that can be expanded or collapsed.
| Value Combining | Controls what value is stored when nested selections are made. `All`, `Branch`, `Leaf`, `Indeterminate`, `Exclusive`. |

::callout{icon="material-symbols:info-outline"}
**Understanding Value Combining Options**
In a Checkboxes (Tree) interface, checkboxes can exist within a parent checkbox. Value combining determines the final value when selecting items in a tree.
- `All` returns all checked values.
:::collapsible{name="examples" class="mt-2"}
| Selection | Final Value |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[child1]` |
| :icon{name="material-symbols:check-box"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box"} `child2` | `[child1, child2, parent]` |
:::
- `Branch` returns the top-most values that are selected.
:::collapsible{name="examples" class="mt-2"}
| Selection | Final Value |
| ------------------------------------------------------------------------------------------------------------------------ | ----------- |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[child1]` |
| :icon{name="material-symbols:check-box"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box"} `child2` | `[parent]` |
:::
- `Leaf` returns the deepest values that are selected
:::collapsible{name="examples" class="mt-2"}
| Selection | Final Value |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------ |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[child1]` |
| :icon{name="material-symbols:check-box"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box"} `child2` | `[child1, child2]` |
:::
- `Indeterminate` returns checked items, and always returns a parent when one or more children are selected.
:::collapsible{name="examples" class="mt-2"}
| Selection | Final Value |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[child1, parent]` |
| :icon{name="material-symbols:check-box"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box"} `child2` | `[child1, child2, parent]` |
:::
- `Exclusive` returns either the parent or child elements, but not both.
:::collapsible{name="examples" class="mt-2"}
| Selection | Final Value |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------ |
| :icon{name="material-symbols:check-box"} `parent`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[parent]` |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[child1]` |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box"} `child2` | `[child1, child2]` |
:::
::
**Understanding Value Combining Options**
In a Checkboxes (Tree) interface, checkboxes can exist within a parent checkbox. Value combining determines the final value when selecting items in a tree.

- `All` returns all checked values.
:::collapsible{name="examples" class="mt-2"}
| Selection | Final Value |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[child1]` |
| :icon{name="material-symbols:check-box"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box"} `child2` | `[child1, child2, parent]` |
:::
- `Branch` returns the top-most values that are selected.
:::collapsible{name="examples" class="mt-2"}
| Selection | Final Value |
| ------------------------------------------------------------------------------------------------------------------------ | ----------- |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[child1]` |
| :icon{name="material-symbols:check-box"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box"} `child2` | `[parent]` |
:::
- `Leaf` returns the deepest values that are selected
:::collapsible{name="examples" class="mt-2"}
| Selection | Final Value |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------ |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[child1]` |
| :icon{name="material-symbols:check-box"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box"} `child2` | `[child1, child2]` |
:::
- `Indeterminate` returns checked items, and always returns a parent when one or more children are selected.
:::collapsible{name="examples" class="mt-2"}
| Selection | Final Value |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[child1, parent]` |
| :icon{name="material-symbols:check-box"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box"} `child2` | `[child1, child2, parent]` |
:::
- `Exclusive` returns either the parent or child elements, but not both.
:::collapsible{name="examples" class="mt-2"}
| Selection | Final Value |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------ |
| :icon{name="material-symbols:check-box"} `parent`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[parent]` |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box-outline"} `child2` | `[child1]` |
| :icon{name="material-symbols:check-box-outline"} `parent`<br>&emsp; :icon{name="material-symbols:check-box"} `child1`<br>&emsp; :icon{name="material-symbols:check-box"} `child2` | `[child1, child2]` |
:::
::

### Radio Buttons

Expand Down Expand Up @@ -492,18 +495,16 @@ Special relational interface designed specifically to handle translations. When

A configurable header section that provides rich page headers with titles, subtitles, contextual help information and intertactive action buttons within collections. Can be positioned anywhere in the form layout to guide users and provide quick access to relevant actions.


| Configuration | Options |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Title | Title text displayed at the top of the header section. |
| Icon | Icon displayed beside the button label. |
| Color | Color of the icon displayed when using an icon. |
| Subtitle | Optional subtitle text displayed below the title for additional context. Note this can contain dynamic values. |
| Help | Rich text content providing contextual guidance to users. Supports formatting, images, and can be translated. |
| Help Display | Controls how help content is displayed. Options may include inline, collapsible, or modal views. |
| Enable Help Translations | Toggle to enable multilingual support for the help content. |
| Links | Configure action buttons/links. Each can trigger a flow or open a URL, with customizable labels, icons, and button types. |

| Configuration | Options |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Title | Title text displayed at the top of the header section. |
| Icon | Icon displayed beside the button label. |
| Color | Color of the icon displayed when using an icon. |
| Subtitle | Optional subtitle text displayed below the title for additional context. Note this can contain dynamic values. |
| Help | Rich text content providing contextual guidance to users. Supports formatting, images, and can be translated. |
| Help Display | Controls how help content is displayed. Options may include inline, collapsible, or modal views. |
| Enable Help Translations | Toggle to enable multilingual support for the help content. |
| Links | Configure action buttons/links. Each can trigger a flow or open a URL, with customizable labels, icons, and button types. |

### Divider

Expand Down Expand Up @@ -553,9 +554,9 @@ User-controlled showing and hiding of fields within the group by clicking on eac

Display fields or groups as tabs. Selecting a tab shows only the fields within that group.

| Configuration | Options |
| ------------- | -------------------------------------------------------- |
| Fill Width | Allow the tab group to fill the full width of the page. |
| Configuration | Options |
| ------------- | ------------------------------------------------------- |
| Fill Width | Allow the tab group to fill the full width of the page. |

### Detail Group

Expand Down