diff --git a/14/umbraco-cms/extending/property-editors/README.md b/14/umbraco-cms/extending/property-editors/README.md index 5c819f70695..b3b100dcfdf 100644 --- a/14/umbraco-cms/extending/property-editors/README.md +++ b/14/umbraco-cms/extending/property-editors/README.md @@ -4,6 +4,10 @@ description: Guide on how to work with and create Property Editors in Umbraco # Property Editors +{% hint style="info" %} +[This tutorial](../../tutorials/creating-a-property-editor/README.md) contains step-by-step instructions for building a custom Property editor. +{% endhint %} + {% hint style="warning" %} The Property Editor articles are a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. {% endhint %} @@ -36,5 +40,5 @@ Learn how to extend Property editors to track entity references inside the prope ## More information -* [Built in Property Editors](../../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/) -* [Creating a property editor](../../tutorials/creating-a-property-editor/) +* [Built in Property Editors](../../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/README.md) +* [Creating a property editor](../../tutorials/creating-a-property-editor/README.md) diff --git a/14/umbraco-cms/extending/property-editors/build-a-block-editor.md b/14/umbraco-cms/extending/property-editors/build-a-block-editor.md index a8997eedbf1..5bf1b0501bd 100644 --- a/14/umbraco-cms/extending/property-editors/build-a-block-editor.md +++ b/14/umbraco-cms/extending/property-editors/build-a-block-editor.md @@ -4,44 +4,63 @@ This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. {% endhint %} -Before reading this document we highly recommend that you familiarise yourself with[the basics of developing a custom Property Editor for Umbraco](../../tutorials/creating-a-property-editor/). - -{% hint style="info" %} -[Click here for an overview with a working example and references back to the relevant documention.](https://umbraco.com/blog/deep-dive-the-block-list-editor/) -{% endhint %} +Before reading this document we highly recommend that you familiarise yourself with [the basics of developing a custom Property Editor for Umbraco](../../tutorials/creating-a-property-editor/). ## Setup your Property Editor as a Block Property Editor -In order for your editor to become a Block Editor you must setup your property editor through C#. The constructor of the class can be auto generated by your Integrated Development Environment (IDE). +In order for your editor to become a Block Editor, you must first declare it using C#: + +{% code title="UnicornBlocksPropertyEditor.cs" %} +```csharp +using Umbraco.Cms.Core.IO; +using Umbraco.Cms.Core.Serialization; +using Umbraco.Cms.Core.PropertyEditors; + +namespace UmbracoDocs.Samples; + +[DataEditor("MyOwn.UnicornBlocksEditor", ValueType = ValueTypes.Json, ValueEditorIsReusable = false)] +public class UnicornBlocksPropertyEditor : BlockListPropertyEditorBase +{ + private readonly IIOHelper _ioHelper; + + public UnicornBlocksPropertyEditor( + IDataValueEditorFactory dataValueEditorFactory, + IBlockValuePropertyIndexValueFactory blockValuePropertyIndexValueFactory, + IJsonSerializer jsonSerializer, + IOHelper ioHelper) + : base(dataValueEditorFactory, blockValuePropertyIndexValueFactory, jsonSerializer) + => _ioHelper = ioHelper; + + protected override IConfigurationEditor CreateConfigurationEditor() => + new UnicornBlocksConfigurationEditor(_ioHelper); +} +``` +{% endcode %} +{% code title="UnicornBlocksConfigurationEditor.cs" %} ```csharp -using Umbraco.Cms.Core; +using Umbraco.Cms.Core.IO; using Umbraco.Cms.Core.PropertyEditors; -using Umbraco.Cms.Core.WebAssets; -using Umbraco.Cms.Infrastructure.WebAssets; - -namespace MyNamespace; - -[DataEditor( - "MyOwn.UnicornBlocksEditor", - "Unicorn Blocks", - "unicornblocks", - ValueType = ValueTypes.Json, - Group = Constants.PropertyEditors.Groups.Lists, - Icon = "icon-thumbnail-list")] -[PropertyEditorAsset(AssetType.Javascript, "/App_Plugins/UnicornBlocks/UnicornBlocks.controller.js")] -public class UnicornBlocksPropertyEditor : BlockEditorPropertyEditor + +namespace UmbracoDocs.Samples; + +public class UnicornBlocksConfigurationEditor : ConfigurationEditor { - public UnicornBlocksPropertyEditor(IDataValueEditorFactory dataValueEditorFactory, PropertyEditorCollection propertyEditors) - : base(dataValueEditorFactory, propertyEditors) + public UnicornBlocksConfigurationEditor(IIOHelper ioHelper) + : base(ioHelper) { } } ``` +{% endcode %} + +{% hint style="info" %} +It is not strictly necessary to define your own property editor in C#. As outlined in the [Composition](composition/README.md) article, all Umbraco core property editors can be reused. -Notice how the `PropertyEditorAsset` attribute is used to load the `UnicornBlocks.controller.js` JavaScript file. +The code sample above inherits all functionality from Block List and adds no new functionality. If this is sufficient, you can use the Block List property editor alias `"Umbraco.BlockList"` as Property Editor Schema in your [package manifest](./package-manifest.md). -Your Property Editor will need a `PropertyValueConverter`. Read more about [Property Value Converters](property-value-converters.md). +It is, however, recommended to declare your own Block Editors in C#. As you will see in the following, the property editor alias (`"MyOwn.UnicornBlocksEditor"`) will be part of the data structure. For any eventual future extensibility, it is good to have the correct alias in the content structure from the beginning. +{% endhint %} ## Data structure of Block Editors diff --git a/14/umbraco-cms/extending/property-editors/declaring-your-property-editor.md b/14/umbraco-cms/extending/property-editors/declaring-your-property-editor.md deleted file mode 100644 index 1bbde8fc00d..00000000000 --- a/14/umbraco-cms/extending/property-editors/declaring-your-property-editor.md +++ /dev/null @@ -1,330 +0,0 @@ -# Declaring your property editor - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -Generally Umbraco supports two different ways to declare a property editor. Most commonly one would create a `package.manifest` file, and then use it for declaring one or more property editors. But as an alternative, property editors can also be declared using C#. - -A property editor consists of a number of mandatory properties, and some optional ones as well. As such, the outer JSON object for the property editor has the following properties: - -| Name | Type | Required | Description | -| ---- | ---- | ---- | ---- | -| `alias` | string | Yes | A unique alias that identifies the property editor. | -| `name` | string | Yes | The friendly name of the property editor, shown in the Umbraco backoffice. | -| `editor` | object | Yes | This describes details about the editor. See the table below for further information. | -| `icon` | string | No | A CSS class for the icon to be used in the **Select Editor** dialog - eg: `icon-autofill`. | -| `group` | string | No | The group to place this editor in within the **Select Editor** dialog. Use a new group name or alternatively use an existing one such as **Pickers**. | -| `defaultConfig` | object | No | Provides a collection of default configuration values, in cases the property editor is not configured. The object is a key/value collection and must match the prevalue fields keys. | - -The `editor` object then has the following properties: - -| Name | Type | Required | Description | -| ---- | ---- | ---- | ---- | -| `view` | string | Yes | This is the full path to the HTML view for your property editor. | -| `hideLabel` | bool | Yes | If set to `true`, this hides the label for the property editor when used in Umbraco on a Document Type. | -| `valueType` | object | No | This is the type of data you want your property editor to save to Umbraco. Possible values are `STRING`, `JSON`, `DATETIME`, `TEXT` and `INT`. Default is `STRING`. | -| `validation` | object | No | Object describing required validators on the editor. | -| `isReadOnly` | boolean | No | If set to true this makes the property editor read only. | - -## Using a Package Manifest - -A package manifest is a file specific to your package or custom code. This file is always stored in a folder in `/App_Plugins/{YourPackageName}`, and with the name `package.manifest` : - -```json -{ - "propertyEditors": [ - { - "alias": "Sir.Trevor", - "name": "Sir Trevor", - "editor": { - "view": "/App_Plugins/SirTrevor/SirTrevor.html", - "hideLabel": true, - "valueType": "JSON" - } - } - ], - "javascript": [ - "/App_Plugins/SirTrevor/SirTrevor.controller.js" - ] -} -``` - -This example manifest specifies a **Sir Trevor** property editor via the `propertyEditors` collection, and also adds a single JavaScript file via the `javascript` property. - -The actual **Sir Trevor** property editor has some additional configuration. It's a block based editor, so for instance it has a prevalue for setting the maximum amount of blocks allowed. In full, the `package.manifest` file for the Sir Trevor package looks like: - -```json -{ - "propertyEditors": [ - { - "alias": "Sir.Trevor", - "name": "Sir Trevor", - "editor": { - "view": "/App_Plugins/SirTrevor/SirTrevor.html", - "hideLabel": true, - "valueType": "JSON" - }, - "prevalues": { - "fields": [ - { - "label": "Maximum number of blocks", - "description": "The total maximum number of blocks (of any type) that can be displayed (0 = infinite).", - "key": "blockLimit", - "view": "requiredfield", - "validation": [ - { - "type": "Required" - } - ] - }, - { - "label": "Align editor centered", - "description": "If the editor doesn't span the entire width of the content editing area, center it. Otherwise left aligned.", - "key": "editorAlignCentered", - "view": "boolean" - }, - { - "label": "Editor width", - "description": "The width the Sir Trevor editor will expand to, most likely 100%.", - "key": "editorWidth", - "view": "requiredfield", - "validation": [ - { - "type": "Required" - } - ] - }, - { - "label": "Maximum editor width", - "description": "The maximum width the Sir Trevor editor will expand to, i.e. 500px or 80%.", - "key": "editorMaxWidth", - "view": "requiredfield", - "validation": [ - { - "type": "Required" - } - ] - }, - { - "label": "Block types", - "description": "Configure the block types available to the user.", - "key": "blocktypes", - "view": "~/App_Plugins/SirTrevor/settings/blocktypes.html" - } - ] - } - } - ], - "javascript": [ - "/App_Plugins/SirTrevor/SirTrevor.controller.js", - "/App_Plugins/SirTrevor/settings/settings.blocktypes.controller.min.js", - "/App_Plugins/SirTrevor/settings/settings.resource.min.js" - ] -} -``` - -## Using Csharp - -The same property editor can be declared using C# instead using the `DataEditor` class and decorating the class with the `DataEditor` attribute: - -```csharp -using Umbraco.Cms.Core.PropertyEditors; -using Umbraco.Cms.Core.WebAssets; -using Umbraco.Cms.Infrastructure.WebAssets; - -namespace UmbracoEightExamples.PropertyEditors; - -[DataEditor( - "Sir.Trevor", - EditorType.PropertyValue, - "Sir Trevor", - "/App_Plugins/SirTrevor/SirTrevor.html", - ValueType = ValueTypes.Json, - HideLabel = true)] -[PropertyEditorAsset(AssetType.Javascript, "/App_Plugins/SirTrevor/SirTrevor.controller.js")] -public class SirTrevorEditor : DataEditor -{ - public SirTrevorEditor( - IDataValueEditorFactory dataValueEditorFactory, - EditorType type = EditorType.PropertyValue) - : base(dataValueEditorFactory, type) - { - } -} -``` - -Also notice how the `PropertyEditorAsset` attribute is used to load the `SirTrevor.controller.js` JavaScript file. - -### DataEditor attribute - -The [DataEditor](https://apidocs.umbraco.com/v14/csharp/api/Umbraco.Cms.Core.PropertyEditors.DataEditorAttribute.html) attribute shown in the example above is the primary component to declaring the property editor in C#. Notice that the first four properties must be set through the constructor. - -| Name | Type | Required | Description | -|----------------| ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | -| `Alias` | string | Yes | Gets the unique alias of the editor. | -| `EditorType` | [EditorType](https://apidocs.umbraco.com/v14/csharp/api/Umbraco.Cms.Core.PropertyEditors.EditorType.html) | Yes | Gets the type of the editor. Possible values are `EditorType.PropertyValue` or `EditorType.Nothing`. | -| `Name` | string | Yes | Gets the friendly name of the editor. | -| `View` | string | Yes | Gets the view to use to render the editor. | -| `ValueType` | string | No | Gets or sets the type of the edited value. | -| `HideLabel` | boolean | No | Gets or sets a value indicating whether the editor should be displayed without its label. | -| `Icon` | string | No | Gets or sets an optional icon. | -| `Group` | string | No | Gets or sets an optional group. | -| `IsDeprecated` | boolean | No | Gets or sets a value indicating whether the value editor is deprecated. | - -### DataEditor class - -In the example above, the `SirTrevorEditor` class doesn't really do much. For more basic property editors, the C# approach may require a bit more work compared to that of `package.manifest` files. But as property editors grow in complexity, using C# becomes a bit more useful - and also lets you do things not possible with `package.manifest` files. - -The [DataEditor](https://apidocs.umbraco.com/v14/csharp/api/Umbraco.Cms.Core.PropertyEditors.DataEditor.html) class defines a virtual `CreateConfigurationEditor` method. It returns a model which is used for the Angular view when editing the prevalues of a Data Type. - -Virtual methods are methods declared in a parent class. These methods have a default implementation that can be overridden in classes that inherit from the parent class. For instance in the example below, we can override the method and provide our own `SirTrevorConfigurationEditor` instead of what Umbraco returns by default. - -```csharp -using Umbraco.Cms.Core.PropertyEditors; -using Umbraco.Cms.Core.WebAssets; -using Umbraco.Cms.Infrastructure.WebAssets; - -namespace UmbracoEightExamples.PropertyEditors; - -[DataEditor( - "Sir.Trevor", - EditorType.PropertyValue, - "Sir Trevor", - "/App_Plugins/SirTrevor/SirTrevor.html", - ValueType = ValueTypes.Json, - HideLabel = true)] -[PropertyEditorAsset(AssetType.Javascript, "/App_Plugins/SirTrevor/SirTrevor.controller.js")] -public class SirTrevorEditor : DataEditor -{ - public SirTrevorEditor( - IDataValueEditorFactory dataValueEditorFactory, - EditorType type = EditorType.PropertyValue) - : base(dataValueEditorFactory, type) - { - } - - protected override IConfigurationEditor CreateConfigurationEditor() => new SirTrevorConfigurationEditor(); - -} -``` - -In this case, the `SirTrevorConfigurationEditor` class doesn't do much either - but notice that it inherits from `ConfigurationEditor`, meaning the configuration will be of type `SirTrevorConfiguration`: - -```csharp -using Umbraco.Cms.Core.IO; -using Umbraco.Cms.Core.PropertyEditors; -using Umbraco.Cms.Core.Services; - -namespace UmbracoEightExamples.PropertyEditors; - -public class SirTrevorConfigurationEditor : ConfigurationEditor -{ - public SirTrevorConfigurationEditor(IIOHelper ioHelper, IEditorConfigurationParser editorConfigurationParser) : base(ioHelper, editorConfigurationParser) - { - } -} -``` - -The referenced `SirTrevorConfiguration` class is then what declares the configuration fields of when editing a Data Type using the Sir Trevor property editor: - -```csharp -using Umbraco.Cms.Core.PropertyEditors; - -namespace UmbracoEightExamples.PropertyEditors; - -public class SirTrevorConfiguration -{ - [ConfigurationField("blockLimit", "Maximum number of blocks", "requiredfield", - Description = "The total maximum number of blocks (of any type) that can be displayed (0 = infinite).")] - public int BlockLimit { get; set; } - - [ConfigurationField("editorAlignCentered", "Align editor centered", "boolean", - Description = - "If the editor doesn't span the entire width of the content editing area, center it. Otherwise left aligned.")] - public bool EditorAlignCentered { get; set; } - - [ConfigurationField("editorWidth", "Editor width", "requiredfield", - Description = "The width the Sir Trevor editor will expand to, most likely 100%.")] - public int EditorWidth { get; set; } - - [ConfigurationField("editorMaxWidth", "Maximum editor width", "requiredfield", - Description = "The maximum width the Sir Trevor editor will expand to, i.e. 500px or 80%.")] - public int EditorMaxWidth { get; set; } - - [ConfigurationField("blocktypes", "Block types", "/App_Plugins/SirTrevor/settings/blocktypes.html", - Description = "Configure the block types available to the user.")] - public object BlockTypes { get; set; } -} -``` - -A benefit of this approach (opposed to `package.manifest` files) is that we can now refer to the configuration using a strongly typed model - eg. as in this example Razor view: - -```csharp -@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage -@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels; -@using Umbraco.Cms.Core.Services -@using UmbracoEightExamples.PropertyEditors -@inject IDataTypeService DataTypeService - -@{ - var dt = DataTypeService.GetDataType(1234); - - if (dt is not null) - { - 
@dt.Name
- - 
@(dt.Configuration as SirTrevorConfiguration)
- - 
@(dt.ConfigurationAs())
- } -} -``` - -Both instances of `IDataType` and `PublishedDataType` have a `Configuration` property. -When looking across all data types and property editors, there is no common type for the configuration, so the return value is `object`. -To get the strongly typed model, you can either cast the configuration value on your own, or use the generic `ConfigurationAs` extension method as shown above. - -Like mentioned before, the `SirTrevorConfigurationEditor` class doesn't really do much in this example with the Sir Trevor property editor. But the **Multi Node Tree Picker** and others of Umbraco's build in property editors also override the `ToValueEditor` method. - -This method is used when the strongly typed configuration value is converted to the model used by the Angular logic in the backoffice. So with the implementation of the [MultiNodePickerConfigurationEditor]( https://github.com/umbraco/Umbraco-CMS/blob/ade9bb73246caf25a7073f2b9e5262641a201863/src/Umbraco.Web/PropertyEditors/MultiNodePickerConfigurationEditor.cs) class, some additional configuration fields are sent along. For instance that it's a multi picker and that the ID type should be URI's. These are configuration values that the user should not be able to edit, but the property editor may still rely on them. - -```csharp -using Umbraco.Cms.Core.IO; -using Umbraco.Cms.Core.Services; - -namespace Umbraco.Cms.Core.PropertyEditors; - -/// -/// Represents the configuration for the multinode picker value editor. -/// -public class MultiNodePickerConfigurationEditor : ConfigurationEditor -{ - public MultiNodePickerConfigurationEditor(IIOHelper ioHelper, IEditorConfigurationParser editorConfigurationParser) - : base(ioHelper, editorConfigurationParser) => - Field(nameof(MultiNodePickerConfiguration.TreeSource)) - .Config = new Dictionary { { "idType", "udi" } }; - - /// - public override Dictionary ToConfigurationEditor(MultiNodePickerConfiguration? configuration) - { - // sanitize configuration - Dictionary output = base.ToConfigurationEditor(configuration); - - output["multiPicker"] = configuration?.MaxNumber > 1; - - return output; - } - - /// - public override IDictionary ToValueEditor(object? configuration) - { - IDictionary d = base.ToValueEditor(configuration); - d["multiPicker"] = true; - d["showEditButton"] = false; - d["showPathOnHover"] = false; - d["idType"] = "udi"; - return d; - } -} -``` diff --git a/14/umbraco-cms/extending/property-editors/full-examples-value-converters.md b/14/umbraco-cms/extending/property-editors/full-examples-value-converters.md index 50f247dc15e..9a8b8ef0b5a 100644 --- a/14/umbraco-cms/extending/property-editors/full-examples-value-converters.md +++ b/14/umbraco-cms/extending/property-editors/full-examples-value-converters.md @@ -1,97 +1,51 @@ # Content Picker Value Converter Example -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - +{% code title="ContentPickerPropertyConverter.cs" %} ```csharp -using System; using Umbraco.Cms.Core; using Umbraco.Cms.Core.Models.PublishedContent; using Umbraco.Cms.Core.PropertyEditors; using Umbraco.Cms.Core.PublishedCache; -using Umbraco.Extensions; -namespace MyConverters; +namespace UmbracoDocs.Samples; public class ContentPickerPropertyConverter : IPropertyValueConverter { private readonly IPublishedSnapshotAccessor _publishedSnapshotAccessor; - //Injecting the PublishedSnapshotAccessor for fetching content + // Injecting the PublishedSnapshotAccessor for fetching content public ContentPickerPropertyConverter(IPublishedSnapshotAccessor publishedSnapshotAccessor) - { - _publishedSnapshotAccessor = publishedSnapshotAccessor; - } + => _publishedSnapshotAccessor = publishedSnapshotAccessor; public bool IsConverter(IPublishedPropertyType propertyType) - { - return propertyType.EditorAlias.Equals("Umbraco.ContentPicker"); - } + => propertyType.EditorAlias.Equals("Umbraco.ContentPicker"); - public bool? IsValue(object value, PropertyValueLevel level) + public bool? IsValue(object? value, PropertyValueLevel level) { - switch (level) + return level switch { - case PropertyValueLevel.Source: - return value != null && (!(value is string) || string.IsNullOrWhiteSpace((string) value) == false); - default: - throw new NotSupportedException($"Invalid level: {level}."); - } + PropertyValueLevel.Source => value is string stringValue && string.IsNullOrWhiteSpace(stringValue) is false, + _ => throw new NotSupportedException($"Invalid level: {level}.") + }; } public Type GetPropertyValueType(IPublishedPropertyType propertyType) - { - return typeof(IPublishedContent); - } + => typeof(IPublishedContent); public PropertyCacheLevel GetPropertyCacheLevel(IPublishedPropertyType propertyType) - { - return PropertyCacheLevel.Elements; - } - - public object ConvertSourceToIntermediate(IPublishedElement owner, IPublishedPropertyType propertyType, object source, bool preview) - { - if (source == null) return null; - - var attemptConvertInt = source.TryConvertTo(); - if (attemptConvertInt.Success) - return attemptConvertInt.Result; - - var attemptConvertUdi = source.TryConvertTo(); - if (attemptConvertUdi.Success) - return attemptConvertUdi.Result; - - return null; - } - - public object ConvertIntermediateToObject(IPublishedElement owner, IPublishedPropertyType propertyType, PropertyCacheLevel referenceCacheLevel, object inter, bool preview) - { - if (inter == null) - return null; - - if ((propertyType.Alias != null) == false) - { - IPublishedContent content; - if (inter is int id) - { - content = _publishedSnapshotAccessor.PublishedSnapshot.Content.GetById(id); - if (content != null) - return content; - } - else - { - var udi = inter as GuidUdi; - if (udi == null) - return null; - content = _publishedSnapshotAccessor.PublishedSnapshot.Content.GetById(udi.Guid); - if (content != null && content.ContentType.ItemType == PublishedItemType.Content) - return content; - } - } - - return inter; - } + => 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; + + 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) + => inter is GuidUdi guidUdi + ? _publishedSnapshotAccessor.GetRequiredPublishedSnapshot().Content?.GetById(guidUdi.Guid) + : null; } - ``` +{% endcode %} diff --git a/14/umbraco-cms/extending/property-editors/package-manifest.md b/14/umbraco-cms/extending/property-editors/package-manifest.md index 028cc95f4fe..fd460863332 100644 --- a/14/umbraco-cms/extending/property-editors/package-manifest.md +++ b/14/umbraco-cms/extending/property-editors/package-manifest.md @@ -10,10 +10,6 @@ This page is a work in progress and may undergo further revisions, updates, or a A Package is declared via an Umbraco Package Manifest. This describes the Package and declares one or more UI Extensions. -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - ### UI Extensions JSON file format is used to describe one or more custom Umbraco extensions such as property editors, dashboards, sections, or entity actions. This page outlines the file format and properties found in the JSON. @@ -52,12 +48,6 @@ Before Umbraco 14, the manifest was declared in a `package.manifest` file instea {% endcode %} -## Sample Manifest with Csharp - -{% hint style="warning" %} -This is a work in progress. It's currently not possible to register a manifest with Csharp such as it was supported in previous versions of Umbraco CMS. -{% endhint %} - ## Root properties The manifest takes four fields: diff --git a/14/umbraco-cms/extending/property-editors/property-value-converters.md b/14/umbraco-cms/extending/property-editors/property-value-converters.md index 236568e9004..2714b18cfe1 100644 --- a/14/umbraco-cms/extending/property-editors/property-value-converters.md +++ b/14/umbraco-cms/extending/property-editors/property-value-converters.md @@ -5,14 +5,8 @@ description: "A guide to creating a custom property value converter in Umbraco" # Property Value Converters -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - A Property Value Converter converts a property editor's database-stored value to another type. The converted value can be accessed from MVC Razor or any other Published Content API. -For example the standard Umbraco Core "Content Picker" stores a nodeId as `String` type. However if you implement a converter it could return an `IPublishedContent` object. - Published property values have four "Values": - **Source** - The raw data stored in the database, this is generally a `String` diff --git a/14/umbraco-cms/extending/property-editors/tracking.md b/14/umbraco-cms/extending/property-editors/tracking.md index 75961dd4455..0bab78d5db7 100644 --- a/14/umbraco-cms/extending/property-editors/tracking.md +++ b/14/umbraco-cms/extending/property-editors/tracking.md @@ -6,10 +6,6 @@ description: >- # Tracking References -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - Property editors can be extended further to track entity references that may be selected or referenced inside the property editor. For example in the core of the CMS we have added this to numerous property editors. A good example of this is the Media Picker. The CMS stores a reference to the selected media item, enabling the identification of content nodes that use that particular media item. This avoids it being accidentally deleted if it is being used. @@ -45,36 +41,24 @@ When a content node is saved it will save the entity references as relations. The following example shows how to implement tracking for the inbuilt CMS property editor **Content Picker**. It will always add a specific media reference, regardless of what value is picked in the content picker. In your own implementations, you will need to parse the value stored from the property editor you are implementing. You will also need to find any references to picked items in order to track their references. +{% code title="TrackingExample.cs" %} ```csharp -using System; -using System.Collections.Generic; using Umbraco.Cms.Core; -using Umbraco.Cms.Core.Composing; -using Umbraco.Cms.Core.DependencyInjection; using Umbraco.Cms.Core.Models; using Umbraco.Cms.Core.Models.Editors; using Umbraco.Cms.Core.PropertyEditors; -using Umbraco.Extensions; - -namespace Umbraco.Web.PropertyEditors; -public class ExampleComposer : IComposer -{ - public void Compose(IUmbracoBuilder builder) - { - builder.DataValueReferenceFactories().Append(); - } -} +namespace UmbracoDocs.Samples; public class TrackingExample : IDataValueReferenceFactory, IDataValueReference { public IDataValueReference GetDataValueReference() => this; // Which Data Editor (Data Type) does this apply to - in this example it is the built in content picker of Umbraco - public bool IsForEditor(IDataEditor dataEditor) => dataEditor.Alias.InvariantEquals(Constants.PropertyEditors.Aliases.ContentPicker); + public bool IsForEditor(IDataEditor? dataEditor) + => dataEditor?.Alias.InvariantEquals(Constants.PropertyEditors.Aliases.ContentPicker) is true; - - public IEnumerable GetReferences(object value) + public IEnumerable GetReferences(object? value) { // Value contains the raw data that is being saved for a property editor // You can then analyse this data be it a complex JSON structure or something more trivial @@ -84,7 +68,7 @@ public class TrackingExample : IDataValueReferenceFactory, IDataValueReference // This will always ADD a specific media reference to the collection list // When it's a ContentPicker datatype var references = new List(); - var udiType = ObjectTypes.GetUdiType(UmbracoObjectTypes.Media); + var udiType = UmbracoObjectTypes.Media.GetUdiType(); var udi = Udi.Create(udiType, Guid.Parse("fbbaa38d-bd93-48b9-b1d5-724c46b6693e")); var entityRef = new UmbracoEntityReference(udi); references.Add(entityRef); @@ -92,3 +76,20 @@ public class TrackingExample : IDataValueReferenceFactory, IDataValueReference } } ``` +{% endcode %} + +You'll need a Composer to enable the tracking example: + +{% code title="TrackingExampleComposer.cs" %} +```csharp +using Umbraco.Cms.Core.Composing; + +namespace UmbracoDocs.Samples; + +public class TrackingExampleComposer : IComposer +{ + public void Compose(IUmbracoBuilder builder) + => builder.DataValueReferenceFactories().Append(); +} +``` +{% endcode %}