diff --git a/17/umbraco-cms/.gitbook.yaml b/17/umbraco-cms/.gitbook.yaml index 0683e8964e1..15a796d982f 100644 --- a/17/umbraco-cms/.gitbook.yaml +++ b/17/umbraco-cms/.gitbook.yaml @@ -146,3 +146,4 @@ redirects: extending/content-apps: customizing/extending-overview/extension-types/workspaces/workspace-views.md extending/backoffice-setup/extension-types: customizing/extending-overview/extension-types/README.md customizing/extending-overview/extension-registry/extension-registry: customizing/extending-overview/extension-registry/register-extensions.md + fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date: fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/README.md diff --git a/17/umbraco-cms/SUMMARY.md b/17/umbraco-cms/SUMMARY.md index 3c7e1ebf076..559e4a7b771 100644 --- a/17/umbraco-cms/SUMMARY.md +++ b/17/umbraco-cms/SUMMARY.md @@ -56,7 +56,11 @@ * [Content Picker](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/content-picker.md) * [Document Picker](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/document-picker.md) * [DateTime](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time.md) - * [Date](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date.md) + * [Date Time Editors](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/README.md) + * [Date Only](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-only.md) + * [Time Only](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/time-only.md) + * [Date Time (with Time Zone)](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-with-time-zone.md) + * [Date Time (Unspecified)](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-unspecified.md) * [Decimal](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/decimal.md) * [Email Address](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/email-address.md) * [Eye Dropper Color Picker](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/eye-dropper-color-picker.md) diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/README.md b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/README.md new file mode 100644 index 00000000000..15918e61d59 --- /dev/null +++ b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/README.md @@ -0,0 +1,16 @@ +# Date Time Editors + +The Date Time property editors provide interfaces for selecting dates, times, and time zones. Each editor is designed for specific use cases, from basic date selection to comprehensive date/time handling with time zone support. + +{% hint style="info" %} +These property editors replace the legacy `[Date Time](../date-time.md)` property editor. They offer more focused functionality and specific return types (such as `DateOnly`, `TimeOnly`, `DateTime`, or `DateTimeOffset`). You can switch from the legacy Date Time editor by changing your properties to use the new editors. +{% endhint %} + +Umbraco CMS currently ships with four Date Time editors: + +| Editor | Purpose | Use Cases | Return Type | Preview | +|--------|---------|-----------|-------------|---------| +| [Date Only](date-only.md) | Date selection | Birthdays, deadlines, event dates | `DateOnly` | ![Date Only editor](./images/date-only-editor.png) | +| [Time Only](time-only.md) | Time selection | Business hours, schedules, time-based events | `TimeOnly` | ![Time Only editor](./images/time-only-time-format-hhmm.png) | +| [Date Time (with Time Zone)](date-time-with-time-zone.md) | Full date, time, and time zone support | International apps, timezone-aware scheduling | `DateTimeOffset` | ![Date Time with Time Zone editor](./images/date-time-with-time-zone-editor.png) | +| [Date Time (Unspecified)](date-time-unspecified.md) | Date and time without a defined time zone | Local events, compatibility with [Date Time](../date-time.md) | `DateTime` | ![Date Time Unspecified editor](./images/date-time-time-format-hhmm.png) | diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-only.md b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-only.md new file mode 100644 index 00000000000..1bc3d813531 --- /dev/null +++ b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-only.md @@ -0,0 +1,110 @@ +# Date Only + +`Schema Alias: Umbraco.DateOnly` + +`UI Alias: Umb.PropertyEditorUi.DateOnlyPicker` + +`Returns: DateOnly?` + +The Date Only property editor provides an interface for selecting dates without including time or time zone information. It focuses purely on date selection and returns a `DateOnly` value. + +## Configuration +You can configure this property editor in the same way as any standard property editor, using the *Data Types* admin interface. + +To set up a property using this editor, create a new *Data Type* and select **Date Only** from the list of available property editors. + +This editor has no configuration options. + +## Editing experience + +### Adding or editing a value + +You will be presented with a date input. + +![Date Only property editor interface](./images/date-only-editor-open.png) + +## Rendering + +The value returned will have the type `DateOnly?`. + +### Display the value + +With Models Builder: +```csharp +@Model.EventDate +``` + +Without Models Builder: +```csharp +@Model.Value("eventDate") +``` + +## Add values programmatically + +This property editor stores values as a JSON object. The object contains the date as an ISO 8601 string with midnight time and UTC offset. + +### Storage format + +The property editor stores values in this JSON format: +```json +{ + "date": "2025-01-01T00:00:00+00:00" +} +``` + +The property editor handles date-only values. Time is set to 00:00:00 and offset to +00:00 for storage consistency. These time components are ignored in the Date Only context. + +1. Create a C# model that matches the JSON schema. + + ```csharp + using System.Text.Json.Serialization; + + namespace UmbracoProject; + + public class DateOnlyValue + { + /// + /// The date value, represented as a for storage compatibility. + /// + [JsonPropertyName("date")] + public DateTimeOffset Date { get; init; } + } + ``` +2. Convert your existing date value to `DateTimeOffset` for storage. + + If you have a `DateOnly`: + ```csharp + DateOnly dateOnly = DateOnly.FromDateTime(DateTime.Today); // Your existing DateOnly value + DateTimeOffset dateTimeOffset = dateOnly.ToDateTime(TimeOnly.MinValue); + ``` + + If you have a `DateTime`: + ```csharp + DateTime dateTime = DateTime.Today; // Your existing DateTime value + DateOnly dateOnly = DateOnly.FromDateTime(dateTime); + DateTimeOffset dateTimeOffset = dateOnly.ToDateTime(TimeOnly.MinValue); + ``` + +3. Create an instance of the class with the `DateTimeOffset` value. + ```csharp + DateOnlyValue value = new DateOnlyValue + { + Date = dateTimeOffset + }; + ``` + +4. Inject the `IJsonSerializer` and use it to serialize the object. + ```csharp + string jsonValue = _jsonSerializer.Serialize(value); + ``` + +5. Inject the `IContentService` to retrieve and update the value of a property of the desired content item. + ```csharp + IContent content = _contentService.GetById(contentKey) ?? throw new Exception("Content not found"); + + // Set the value of the property with alias 'eventDate'. + content.SetValue("eventDate", jsonValue); + + // Save the change + _contentService.Save(content); + ``` diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-unspecified.md b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-unspecified.md new file mode 100644 index 00000000000..0011d662d47 --- /dev/null +++ b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-unspecified.md @@ -0,0 +1,115 @@ +# Date Time (Unspecified) + +`Schema Alias: Umbraco.DateTimeUnspecified` + +`UI Alias: Umb.PropertyEditorUi.DateTimePicker` + +`Returns: DateTime?` + +The Date Time (Unspecified) property editor provides an interface for selecting dates and times without including time zone information. + +## Configuration +You can configure this property editor in the same way as any standard property editor, using the *Data Types* admin interface. + +To set up a property using this editor, create a new *Data Type* and select **Date Time (Unspecified)** from the list of available property editors. + +You will see the configuration options as shown below. + +![Date Time Unspecified property editor configuration](./images/date-time-unspecified-property-editor-config.png) + +- **Time format** - Specifies the level of precision for time values shown and stored by the editor. + +### Time format + +- **HH:mm** - Displays hours and minutes (e.g., `14:30`). +Suitable for most general use cases. +![Date Time Unspecified property editor showing time format in HH:mm format (hours and minutes only)](./images/date-time-time-format-hhmm.png) +- **HH:mm:ss** - Displays hours, minutes, and seconds (e.g., `14:30:45`). +Use this when you need more precise timing. +![Date Time Unspecified property editor showing time format in HH:mm:ss format (hours, minutes, and seconds)](./images/date-time-time-format-hhmmss.png) + +## Editing experience + +### Adding or editing a value + +You will be presented with a date and time input. This editor focuses only on the date and time components, unlike the time zone version. + +![Date Time Unspecified property editor interface](./images/date-time-unspecified-editor.png) + +## Rendering + +The value returned will have the type `DateTime?`. + +### Display the value + +With Models Builder: +```csharp +@Model.EventDateTime.Value +``` + +Without Models Builder: +```csharp +@Model.Value("eventDateTime") +``` + +## Add values programmatically + +This property editor stores values as a JSON object. The object contains the date as an ISO 8601 string. + +### Storage format + +The property editor stores values in this JSON format: +```json +{ + "date": "2025-01-01T00:00:00+00:00" +} +``` + +The property editor handles unspecified date and time values without time zone information. The value is stored with offset +00:00 for consistency. The offset is ignored unless you replace this editor with the Date Time (with time zone) version. + +1. Create a C# model that matches the JSON schema. + + ```csharp + using System.Text.Json.Serialization; + + namespace UmbracoProject; + + public class DateTimeUnspecified + { + /// + /// The date and time value, represented as a for storage compatibility. + /// + [JsonPropertyName("date")] + public DateTimeOffset Date { get; init; } + } + ``` + +2. Convert your existing DateTime value to `DateTimeOffset` for storage. + ```csharp + DateTime dateTime = DateTime.Now; // Your existing DateTime value + DateTimeOffset dateTimeOffset = dateTime; // Explicit conversion + ``` + +3. Create an instance of the class with the `DateTimeOffset` value. + ```csharp + var value = new DateTimeUnspecified + { + Date = dateTimeOffset + }; + ``` + +4. Inject the `IJsonSerializer` and use it to serialize the object. + ```csharp + string jsonValue = _jsonSerializer.Serialize(value); + ``` + +5. Inject the `IContentService` to retrieve and update the value of a property of the desired content item. + ```csharp + IContent content = _contentService.GetById(contentKey) ?? throw new Exception("Content not found"); + + // Set the value of the property with alias 'eventDateTime'. + content.SetValue("eventDateTime", jsonValue); + + // Save the change + _contentService.Save(content); + ``` diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-with-time-zone.md b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-with-time-zone.md new file mode 100644 index 00000000000..b0a42f8d973 --- /dev/null +++ b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/date-time-with-time-zone.md @@ -0,0 +1,160 @@ +# Date Time (with Time Zone) + +`Schema Alias: Umbraco.DateTimeWithTimeZone` + +`UI Alias: Umb.PropertyEditorUi.DateTimeWithTimeZonePicker` + +`Returns: DateTimeOffset?` + +The Date Time with Time Zone property editor provides a comprehensive interface for selecting dates, times, and time zones. It stores values as ISO 8601 date/time strings with time zone information. This makes it ideal for applications that need accurate date handling across different time zones. + +## Configuration +You can configure this property editor in the same way as any standard property editor, using the *Data Types* admin interface. + +To set up a property using this editor, create a new *Data Type*. Select **Date Time (with time zone)** from the list of available property editors. + +You will see the configuration options as shown below. + +![Date Time with Time Zone property editor configuration](./images/date-time-with-time-zone-property-editor-config.png) + +- **Time format** - Specifies the level of precision for time values shown and stored by the editor. +- **Time zones** - Controls how time zones are available in the property editor. + +### Time format + +- **HH:mm** - Displays hours and minutes (e.g., `14:30`). +Suitable for most general use cases. +![Date Time with Time Zone property editor showing time format in HH:mm format (hours and minutes only)](./images/date-time-time-format-hhmm.png) +- **HH:mm:ss** - Displays hours, minutes, and seconds (e.g., `14:30:45`). +Use this when you need more precise timing. +![Date Time with Time Zone property editor showing time format in HH:mm:ss format (hours, minutes, and seconds)](./images/date-time-time-format-hhmmss.png) + +### Time zones + +- **All** - Displays the full list of [Internet Assigned Numbers Authority (IANA)](https://www.iana.org/time-zones) time zones (for example, `America/New_York`, `Europe/Stockholm`). +- **Local** - Displays only the local time zone of the user's browser/computer. +Useful for simplifying the UI when time entries should always be based on the user’s local context. +- **Custom** - Allows you to define a list of time zones. +When you select this option, a dropdown appears. You can search and select from the full IANA time zone list. Add multiple zones to restrict user selection to only the zones you specify. + - Example: + Selecting the following time zones: + - `Coordinated Universal Time (UTC)` + - `Europe/Copenhagen` + Will result in the following editing experience: + ![Date Time with Time Zone property editor showing custom time zone selection with UTC and Europe/Copenhagen options](./images/date-time-with-time-zone-custom.png) + +The selected time zone affects how the date/time is displayed and stored. +When you select a time zone, the value will be saved with the corresponding offset (e.g., `2025-01-01T14:30:00+01:00`). +Daylight saving time is also taken into account. + +## Editing experience + +### Adding or editing a value + +You will be presented with date, time, and time zone inputs. The time zone input allows typing, which filters the list of presented time zones. + +![Date Time with Time Zone property editor showing time zone dropdown with filtering functionality as user types](./images/date-time-with-time-zone-filtering.png) + +If your browser time zone appears in the list and no date is stored yet, it will be pre-selected by default. + +When you select a time zone different from your browser's local time zone, the editor displays a helpful conversion message. This shows what the selected date and time would be equivalent to in your local time zone, making it easier to understand the time difference. + +If only one time zone is available, you will see a label with the time zone name instead. + +![Date Time with Time Zone property editor displaying a single time zone as a static label instead of dropdown](./images/date-time-with-time-zone-single-time-zone.png) + +## Rendering + +The value returned will have the type `DateTimeOffset?`. This allows you to work with the date/time value while preserving time zone information. + +### Display the value + +With Models Builder: +```csharp +@Model.EventDateTime.Value +``` + +Without Models Builder: +```csharp +@Model.Value("eventDateTime") +``` + +### Value conversions + +Convert to local time: +```csharp +DateTimeOffset? localTime = Model.EventDateTime?.ToLocalTime(); +``` + +Convert to UTC time: +```csharp +DateTimeOffset? utcTime = Model.EventDateTime?.ToUniversalTime(); +``` + +Convert to DateTime: +```csharp +DateTime? dateTime = Model.EventDateTime?.DateTime; +DateTime? utcDateTime = Model.EventDateTime?.UtcDateTime; +``` + +## Add values programmatically + +This property editor stores values as a JSON object. The object contains both the date (as an ISO 8601 string) and the selected [IANA](https://www.iana.org/time-zones) time zone identifier. + +### Storage format + +The property editor stores values in this JSON format: +```json +{ + "date": "2025-01-01T00:01:00+01:00", + "timeZone": "Europe/Copenhagen" +} +``` + +1. Create a C# model that matches the JSON schema. + + ```csharp + using System.Text.Json.Serialization; + + namespace UmbracoProject; + + public class DateTimeWithTimeZone + { + /// + /// The date and time value, represented as a . + /// + [JsonPropertyName("date")] + public DateTimeOffset Date { get; init; } + + /// + /// The identifier of the time zone to pre-select in the editor. E.g., "Europe/Copenhagen". + /// + [JsonPropertyName("timeZone")] + public string TimeZone { get; init; } + } + ``` + +2. Create an instance of the created class with the desired values. + ```csharp + var value = new DateTimeWithTimeZone + { + Date = DateTimeOffset.Now, // The date and time value to store. + TimeZone = "Europe/Copenhagen" // The time zone to pre-select in the editor. + }; + ``` + +3. Inject the `IJsonSerializer` and use it to serialize the object. + ```csharp + var jsonValue = _jsonSerializer.Serialize(value); + ``` + +4. Inject the `IContentService` to retrieve and update the value of a property of the desired content item. + ```csharp + IContent content = _contentService.GetById(contentKey) ?? throw new Exception("Content not found"); + + // Set the value of the property with alias 'eventDateTime'. + content.SetValue("eventDateTime", jsonValue); + + // Save the change + _contentService.Save(content); + ``` diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-only-editor-open.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-only-editor-open.png new file mode 100644 index 00000000000..a25a76605ac Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-only-editor-open.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-only-editor.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-only-editor.png new file mode 100644 index 00000000000..fd10f8e2c69 Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-only-editor.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-time-format-hhmm.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-time-format-hhmm.png new file mode 100644 index 00000000000..37bdce336f3 Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-time-format-hhmm.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-time-format-hhmmss.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-time-format-hhmmss.png new file mode 100644 index 00000000000..f0398d8c07b Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-time-format-hhmmss.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-unspecified-editor.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-unspecified-editor.png new file mode 100644 index 00000000000..84d794f636b Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-unspecified-editor.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-unspecified-property-editor-config.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-unspecified-property-editor-config.png new file mode 100644 index 00000000000..b9427a4e10d Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-unspecified-property-editor-config.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-custom.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-custom.png new file mode 100644 index 00000000000..6a87e187029 Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-custom.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-editor.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-editor.png new file mode 100644 index 00000000000..ad9cfee9fb6 Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-editor.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-filtering.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-filtering.png new file mode 100644 index 00000000000..c8f435f1868 Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-filtering.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-property-editor-config.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-property-editor-config.png new file mode 100644 index 00000000000..eacc15fb90a Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-property-editor-config.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-single-time-zone.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-single-time-zone.png new file mode 100644 index 00000000000..e6c7d96577e Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/date-time-with-time-zone-single-time-zone.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-editor.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-editor.png new file mode 100644 index 00000000000..18a9b790957 Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-editor.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-property-editor-config.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-property-editor-config.png new file mode 100644 index 00000000000..79f019ba970 Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-property-editor-config.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-time-format-hhmm.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-time-format-hhmm.png new file mode 100644 index 00000000000..7d71ed9c6a4 Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-time-format-hhmm.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-time-format-hhmmss.png b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-time-format-hhmmss.png new file mode 100644 index 00000000000..324eccfee37 Binary files /dev/null and b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/images/time-only-time-format-hhmmss.png differ diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/time-only.md b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/time-only.md new file mode 100644 index 00000000000..20b694791ac --- /dev/null +++ b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time-editor/time-only.md @@ -0,0 +1,125 @@ +# Time Only + +`Schema Alias: Umbraco.TimeOnly` + +`UI Alias: Umb.PropertyEditorUi.TimeOnlyPicker` + +`Returns: TimeOnly?` + +The Time Only property editor provides an interface for selecting times. It excludes date and time zone information, and returns strongly-typed `TimeOnly` values. + +## Configuration +You can configure this property editor in the same way as any standard property editor, using the *Data Types* admin interface. + +To set up a property using this editor, create a new *Data Type* and select **Time Only** from the list of available property editors. + +You will see the configuration options as shown below. + +![Time Only property editor configuration](./images/time-only-property-editor-config.png) + +- **Time format** - Specifies the level of precision for time values shown and stored by the editor. + +### Time format + +- **HH:mm** - Displays hours and minutes (e.g., `14:30`). +Suitable for most general use cases. +![Time Only property editor showing time format in HH:mm format (hours and minutes only)](./images/time-only-time-format-hhmm.png) +- **HH:mm:ss** - Displays hours, minutes, and seconds (e.g., `14:30:45`). +Use this when you need more precise timing. +![Time Only property editor showing time format in HH:mm:ss format (hours, minutes, and seconds)](./images/time-only-time-format-hhmmss.png) + + +## Editing experience + +### Adding or editing a value + +You will be presented with a time input. Unlike date-time editors, this editor focuses only on the time component. + +![Time Only property editor interface](./images/time-only-editor.png) + +## Rendering + +The value returned will have the type `TimeOnly?`. + +### Display the value + +With Models Builder: +```csharp +@Model.StartHours +``` + +Without Models Builder: +```csharp +@Model.Value("startHours") +``` + +## Add values programmatically + +This property editor stores values as a JSON object. The object contains the time as an ISO 8601 string with a default date and UTC offset. + +### Storage format + +The property editor stores values in this JSON format: +```json +{ + "date": "0001-01-01T14:30:00+00:00" +} +``` + +The property editor handles time-only values. Date is set to a default value (0001-01-01) and offset to +00:00 for storage consistency. The date component is ignored in the Time Only context. + +1. Create a C# model that matches the JSON schema. + + ```csharp + using System.Text.Json.Serialization; + + namespace UmbracoProject; + + public class TimeOnlyValue + { + /// + /// The time value, represented as a for storage compatibility. + /// + [JsonPropertyName("date")] + public DateTimeOffset Date { get; init; } + } + ``` + +2. Convert your existing time value to `DateTimeOffset` for storage. + + If you have a `TimeOnly`: + ```csharp + TimeOnly timeOnly = TimeOnly.FromDateTime(DateTime.Now); // Your existing TimeOnly value + DateTimeOffset dateTimeOffset = new DateTimeOffset(DateOnly.MinValue, timeOnly, TimeSpan.Zero); + ``` + + If you have a `DateTime`: + ```csharp + DateTime dateTime = DateTime.Now; // Your existing DateTime value + TimeOnly timeOnly = TimeOnly.FromDateTime(dateTime); + DateTimeOffset dateTimeOffset = new DateTimeOffset(DateOnly.MinValue, timeOnly, TimeSpan.Zero); + ``` + +3. Create an instance of the class with the `DateTimeOffset` value. + ```csharp + TimeOnlyValue value = new TimeOnlyValue + { + Date = dateTimeOffset + }; + ``` + +4. Inject the `IJsonSerializer` and use it to serialize the object. + ```csharp + string jsonValue = _jsonSerializer.Serialize(value); + ``` + +5. Inject the `IContentService` to retrieve and update the value of a property of the desired content item. + ```csharp + IContent content = _contentService.GetById(contentKey) ?? throw new Exception("Content not found"); + + // Set the value of the property with alias 'startHours'. + content.SetValue("startHours", jsonValue); + + // Save the change + _contentService.Save(content); + ``` diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time.md b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time.md index 41a6b0bb150..9ef80dc8029 100644 --- a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time.md +++ b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date-time.md @@ -8,6 +8,10 @@ Displays a calendar UI for selecting dates which are saved as a DateTime value. +{% hint style="info" %} +New [Date Time property editors](date-time-editor/README.md) are available. They offer more focused functionality and time zone support. These editors will eventually replace the current Date Time property editor, so consider using them for new implementations. +{% endhint %} + ## Data Type Definition Example ![Data Type Definiton](images/date-time.png) diff --git a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date.md b/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date.md deleted file mode 100644 index f570390121e..00000000000 --- a/17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/date.md +++ /dev/null @@ -1,39 +0,0 @@ -# Date - -`Schema Alias: Umbraco.DateTime` - -`UI Alias: Umb.PropertyEditorUi.DatePicker` - -`Returns: Date` - -Displays a calendar UI for selecting dates which are saved as a DateTime value. - -## Data Type Definition Example - -![Data Type Definition Example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/DateTime-DataType.png) - -The only setting that is available for manipulating the Date property is to set a format. By default the format of the date in the Umbraco backoffice will be `YYYY-MM-DD`, but you can change this to something else. See [MomentJS.com](https://momentjs.com/) for the supported formats. - -## Content Example - -![Content Example](../../../../../../10/umbraco-cms/fundamentals/backoffice/property-editors/built-in-property-editors/images/Date-Time-Content.png) - -## MVC View Example - displays a datetime - -### Typed - -```csharp -@(Model.Content.GetPropertyValue("datePicker").ToString("dd MM yyyy")) -``` - -### Dynamic (Obsolete) - -{% hint style="warning" %} -See [Common pitfalls](../../../../reference/common-pitfalls.md) for more information about why the dynamic approach is obsolete. -{% endhint %} - -```csharp -@{ - @CurrentPage.datePicker.ToString("dd-MM-yyyy") -} -```