Merge branch 'main' into cms/new-date-time-property-editors

Author: lauraneto

.lycheeignore

@@ -8,6 +8,7 @@
 ^https://github\.com/Shazwazza/Articulate/blob/.*/.*#L.*
 ^https://github\.com/umbraco/Umbraco-CMS/blob/.*
 ^https://github\.com/.*/issues/[0-9]+#issuecomment-[0-9]+
+^https://github\.com/umbraco/.*/discussions/.*
 
 # Anchor/fragment links causing false positives
 ^https://apidocs\.umbraco\.com/.*/#.*
@@ -20,6 +21,7 @@
 ^https://nginx\.org/.*/#.*
 ^https://azure\.microsoft\.com/en-gb/services/media-services/.*
 ^https://www\.tiny\.cloud/docs/.*
+^https://api\.cloud\.umbraco\.com/?$
 
 # TinyMCE anchors
 ^https://github\.com/tinymce/tinymce/issues/.*#.*
@@ -30,3 +32,6 @@
 # Timeout-prone Umbraco issue links
 ^https://issues\.umbraco\.org/issue/.*
 ^https://issues\.umbraco\.org/issues/.*
+
+# Ignore specific troubleshooting anchor as Lychee is stripping special characters and replacing spaces with hyphens
+^file:///home/runner/work/UmbracoDocs/UmbracoDocs/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md#unable-to-determine-environment-by-its-environment-id

13/umbraco-workflow/workflow-section/approval-groups.md

@@ -44,6 +44,10 @@ This feature is useful where the approval group membership is a single user who
 
 Offline approval requires a user to exist in the Backoffice and be assigned to a workflow group. They do not need to know how to use Umbraco or even know their login credentials.
 
+{% hint style="info" %}
+Offline approval can not be used when the approval group has a group email set.
+{% endhint %}
+
 ## Roles
 
 The **Roles** tab provides an overview of the current workflow roles for the Group:

14/umbraco-cms/customizing/extending-overview/extension-types/modals/confirm-dialog.md

@@ -0,0 +1,63 @@
+---
+description: Ask the user for confirmation
+---
+
+# Confirm Dialog
+
+This example shows how to open a confirm dialog. The `UMB_CONFIRM_MODAL` is a token that represents the confirm dialog. The `open` method takes the token and an object with the data for the confirm dialog. The `onSubmit` method returns a promise that resolves when the user confirms the dialog and rejects when the user cancels the dialog.
+
+The confirm modal itself is built-in and does not need to be registered in the extension registry.
+
+The modal token describes the options that you can pass to the modal. The confirm modal token has the following properties:
+
+* `headline` - The headline of the modal.
+* `content` - The content of the modal, which can be a TemplateResult or a string.
+* `color` - (Optional) The color of the modal. This can be `positive` or `danger`.
+* `confirmLabel` - (Optional) The label of the confirm button.
+
+## Basic Usage
+
+{% code title="my-element.ts" %}
+```typescript
+import { html, LitElement, customElement } from "@umbraco-cms/backoffice/external/lit";
+import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
+import { UMB_MODAL_MANAGER_CONTEXT, UMB_CONFIRM_MODAL } from '@umbraco-cms/backoffice/modal';
+
+@customElement('my-element')
+export class MyElement extends UmbElementMixin(LitElement) {
+
+
+    async #onRequestDisable() {
+        const context = await this.getContext(UMB_MODAL_MANAGER_CONTEXT)
+
+        const modal = context?.open(
+            this, UMB_CONFIRM_MODAL,
+            {
+                data: {
+                    headline: `#actions_disable`,
+                    content: `#defaultdialogs_confirmdisable`,
+                    color: "danger",
+                    confirmLabel: "Disable",
+                }
+            }
+        );
+        
+        modal?.onSubmit()
+            .then(() => {
+                console.log("User has approved");
+            })
+            .catch(() => {
+                console.log("User has rejected");
+            });
+    }
+
+    render() {
+        return html`<uui-button
+                            look="primary"
+                            color="danger"
+                            @click=${this.#onRequestDisable}
+                            label=${this.localize.term("actions_disable")}></uui-button>`;
+    }
+}
+```
+{% endcode %}

15/umbraco-cms/SUMMARY.md

@@ -217,10 +217,10 @@
     * [Property Editor Schema](customizing/property-editors/composition/property-editor-schema.md)
     * [Property Editor UI](customizing/property-editors/composition/property-editor-ui.md)
   * [Property Value Converters](customizing/property-editors/property-value-converters.md)
+  * [Property Value Converter Example](customizing/property-editors/full-examples-value-converters.md)
   * [Property Actions](customizing/property-editors/property-actions.md)
   * [Integrate Property Editors](customizing/property-editors/integrate-property-editors.md)
   * [Tracking References](customizing/property-editors/tracking.md)
-  * [Content Picker Value Converter Example](customizing/property-editors/full-examples-value-converters.md)
   * [Property Dataset](customizing/property-editors/property-dataset.md)
 * [Workspaces](customizing/workspaces.md)
 * [Umbraco Package](customizing/umbraco-package.md)

15/umbraco-cms/customizing/property-editors/full-examples-value-converters.md

@@ -1,6 +1,6 @@
-# Content Picker Value Converter Example
+# Property Value Converter full example
+This page includes an example of a complete Property Value Converter. The example is that of a Property Value Converter for a Content Picker, where the user picks a node from the Umbraco tree.
 
-{% include "../../.gitbook/includes/obsolete-warning-snapshot-publishedcache.md" %}
 
 {% code title="ContentPickerPropertyConverter.cs" %}
 
@@ -12,44 +12,56 @@ using Umbraco.Cms.Core.PublishedCache;
 
 namespace UmbracoDocs.Samples;
 
-public class ContentPickerPropertyConverter : IPropertyValueConverter
+// Injecting the IPublishedContentCache for fetching content from the Umbraco cache
+public class ContentPickerPropertyConverter(IPublishedContentCache publishedContentCache) : IPropertyValueConverter
 {
-    private readonly IPublishedSnapshotAccessor _publishedSnapshotAccessor;
-
-    // Injecting the PublishedSnapshotAccessor for fetching content
-    public ContentPickerPropertyConverter(IPublishedSnapshotAccessor publishedSnapshotAccessor)
-        => _publishedSnapshotAccessor = publishedSnapshotAccessor;
-
+    // Make sure the Property Value Converter only applies to the Content Picker property editor
     public bool IsConverter(IPublishedPropertyType propertyType)
-        => propertyType.EditorAlias.Equals("Umbraco.ContentPicker");
+        => propertyType.EditorAlias.Equals(Constants.PropertyEditors.Aliases.ContentPicker);
 
+
+    // We consider the value to be a value only when we have the actual IPublishedContent object,
+    // meaning that there is a valid picked content item.
     public bool? IsValue(object? value, PropertyValueLevel level)
     {
         return level switch
         {
-            PropertyValueLevel.Source => value is string stringValue && string.IsNullOrWhiteSpace(stringValue) is false,
-            _ => throw new NotSupportedException($"Invalid level: {level}.")
+            PropertyValueLevel.Source => null,
+            PropertyValueLevel.Inter => null,
+            PropertyValueLevel.Object => value is IPublishedContent,
+            _ => throw new ArgumentOutOfRangeException(nameof(level), level, $"Invalid level: {level}.")
         };
     }
 
+    // The type returned by this converter is IPublishedContent
+    // And the Models Builder will take care of returning the actual generated type
     public Type GetPropertyValueType(IPublishedPropertyType propertyType)
         => typeof(IPublishedContent);
 
+    // Because we have a reference to another content item, we need to use the Elements cache level,
+    // to make sure that changes to the referenced item are detected and the cache invalidated accordingly.
     public PropertyCacheLevel GetPropertyCacheLevel(IPublishedPropertyType propertyType)
         => PropertyCacheLevel.Elements;
 
-    public object? ConvertSourceToIntermediate(IPublishedElement owner, IPublishedPropertyType propertyType, object? source, bool preview)
-        // parse the source string to a GuidUdi intermediate value
-        => source is string stringValue && UdiParser.TryParse(stringValue, out GuidUdi? guidUdi)
-            ? guidUdi
-            : null;
+    // Converts the source value (string) to an intermediate value (GuidUdi)
+    public object? ConvertSourceToIntermediate(IPublishedElement owner, IPublishedPropertyType propertyType, 
+        object? source, bool preview)
+    {
+        if (source is not string { Length: > 0 } stringValue)
+            return null;
+            
+        return UdiParser.TryParse(stringValue, out GuidUdi? guidUdi) ? guidUdi : null;
+    }
 
-    public object? ConvertIntermediateToObject(IPublishedElement owner, IPublishedPropertyType propertyType, PropertyCacheLevel referenceCacheLevel, object? inter, bool preview)
-        // inter is expected to be a GuidUdi at this point (see ConvertSourceToIntermediate)
+    // Converts the intermediate value (GuidUdi) to the actual object value (IPublishedContent)
+    public object? ConvertIntermediateToObject(IPublishedElement owner, IPublishedPropertyType propertyType,
+        PropertyCacheLevel referenceCacheLevel, object? inter, bool preview)
         => inter is GuidUdi guidUdi
-            ? _publishedSnapshotAccessor.GetRequiredPublishedSnapshot().Content?.GetById(guidUdi.Guid)
+            ? publishedContentCache.GetById(guidUdi.Guid)
             : null;
 }
+
+
 ```
 
 {% endcode %}