UFM updates for v15

15/umbraco-cms/reference/umbraco-flavored-markdown.md

@@ -12,42 +12,106 @@
 
 ## Syntax
 
-The essence of the UFM syntax is curly brackets with a marker prefix.
+The essence of the UFM syntax is curly brackets with an alias prefix delimited with a colon.
 
 ```markdown
-{<marker prefix> <contents> }
+{<alias prefix>: <contents>}
 ```
 
 For clarity...
 
-- The opening is `{` U+007B Left Curly Bracket
-- The closing is `}` U+007D Right Curly Bracket
-- The marker prefix can be any valid Unicode character(s), including emojis
+- The opening token is `{` U+007B Left Curly Bracket
+- The alias prefix can be any valid Unicode character(s), including emojis
+- Followed by `:` U+003A Colon, (not part of the alias prefix itself)
 - The contents within the curly brackets can include any Unicode characters, including whitespace
+- The closing token is `}` U+007D Right Curly Bracket
 
-An example of this syntax to render a value of a property by its alias is: `{= bodyText }`.
+An example of this syntax to render a value of a property by its alias is: `{umbValue: bodyText}`.
 
-The curly brackets indicate that the UFM syntax should be processed. The `=` marker prefix indicates which UFM component should be rendered, and the `bodyText` contents are the parameter that is passed to that UFM component.
+The curly brackets indicate that the UFM syntax should be processed. The `umbValue` alias prefix indicates which UFM component should be rendered, and the `bodyText` contents are the parameter that is passed to that UFM component.
 
-With this example, the syntax `{= bodyText }` would be processed and rendered as the following markup:
+With this example, the syntax `{umbValue: bodyText}` would be processed and rendered as the following markup:
 
 ```js
 <ufm-label-value alias="bodyText"></ufm-label-value>
 ```
 
 The internal working of the `ufm-label-value` component would then be able to access the property's value using the [Context API](../extending/backoffice-setup/working-with-data/context-api).
 
-## Available UFM components
 
-As for Umbraco 14.1.0, the following UFM components are available to use.
+### Filters
 
-| Name        | Marker | Example syntax    | Renders component                    |
-| ----------- | ------ | ----------------- | ------------------------------------ |
-| Label Value | `=`    | `{=bodyText}`     | `<ufm-label-value alias="bodyText">` |
-| Localize    | `#`    | `{#general_name}` | `<umb-localize key="general_name">`  |
+In addition, a filter syntax can be applied to UFM contents. This can be useful for formatting or transforming a value without needing to develop your own custom UFM component.
+
+The syntax for UFM filters by using a pipe character `|` (U+007C Vertical Line). Multiple filters may be applied. The value from the previous filter is passed onto the next.
+
+For example, to display a rich text value, stripping out the HTML markup and limiting it to the first 15 words could use the following filters:
+
+```markdown
+{umbValue: bodyText | strip-html | word-limit:15}
+```
+
+A list of available UFM filters is detailed below.
+
+
+## UFM components
+
+### Available UFM components
+
+As of Umbraco 15.0.0, the following UFM components are available to use.
+
+- Label Value
+- Localize
+- Content Name
 
 More UFM components will be available in upcoming Umbraco releases.
 
+
+#### Label Value
+
+The Label Value component will render the current value of a given property alias.
+
+The alias prefix is `umbValue`. An example of the syntax is `{umbValue: bodyText}`, which would render the component as `<ufm-label-value alias="bodyText"></ufm-label-value>`.
+
+For brevity and backwards-compatibility (with Umbraco 14.1.0), the `=` marker prefix can be used, e.g. `{=bodyText}`.
+
+
+#### Localize
+
+The Localize component will render a localization for a given term key.
+
+The alias prefix is `umbLocalize`. An example of the syntax is `{umbLocalize: general_name}`, which would render the component as `<ufm-localize alias="general_name"></ufm-localize>`.
+
+Similarly, for brevity and backwards-compatibility (with Umbraco 14.1.0), the `#` marker prefix can be used, e.g. `{#general_name}`.
+
+
+#### Content Name
+
+The Content Name component will render the name of a content item, (either Document, Media or Member), from the value of a given property alias. Multiple values will render the names as a comma-separated list.
+
+The alias prefix is `umbContentName`  An example of the syntax is `{umbContentName: pickerAlias}`, which would render the component as `<ufm-content-name alias="pickerAlias"></ufm-content-name>`.
+
+As of Umbraco 15.0.0, the Content Name component supports the content-based pickers, e.g. Document Picker, Content Picker (formerly known as Multinode Treepicker) and Member Picker. Support for the advanced Media Picker will be available in upcoming Umbraco release.
+
+
+### Available UFM filters
+
+As of Umbraco 15.0.0, the following UFM filters are available to use.
+
+| Name       | Alias        | Example syntax                         |
+| ---------- | ------------ | -------------------------------------- |
+| Lowercase  | `lowercase`  | `{umbValue: headline | lowercase}`     |
+| Strip HTML | `strip-html` | `{umbValue: bodyText | strip-html}`    |
+| Title Case | `title-case` | `{umbValue: headline | title-case}`    |
+| Truncate   | `truncate`   | `{umbValue: intro | truncate:30:...}`  |
+| Uppercase  | `uppercase`  | `{umbValue: headline | uppercase}`     |
+| Word Limit | `word-limit` | `{umbValue: intro | word-limit:15}`    |
+
+More UFM filters may be available in upcoming Umbraco releases.
+
+
+### Custom UFM components
+
 If you wish to develop your own custom UFM component, you can use the `ufmComponent` extension type:
 
 ```json
@@ -57,14 +121,16 @@
   name: 'My Custom UFM Component',
   api: () => import('./components/my-custom.component.js'),
   meta: {
-    marker: '%',
-  },
+    alias: 'myCustom'
+  }
 }
 ```
 
 The corresponding JavaScript/TypeScript API would contain a method to render the custom label/markup.
 
 ```js
+import { UmbUfmComponentBase } from '@umbraco-cms/backoffice/ufm';
+
 export class MyCustomUfmComponentApi implements UmbUfmComponentBase {
   render(token: Tokens.Generic) {
     // You could do further regular expression/text processing here!
@@ -75,7 +141,41 @@
 export { MyCustomUfmComponentApi as api };
 ```
 
-Using the syntax `{% myCustomText }` would render the markup `<ufm-custom-component text="myCustomText">`. Then inside the `ufm-custom-component` component code, you can perform any logic to render your required markup.
+Using the syntax `{myCustom: myCustomText}` would render the markup `<ufm-custom-component text="myCustomText"></ufm-custom-component>`. Then inside the `ufm-custom-component` component code, you can perform any logic to render your required markup.
+
+
+### Custom UFM filters
+
+If you wish to develop your own custom UFM filter, you can use the `ufmFilter` extension type:
+
+```json
+{
+  type: 'ufmFilter',
+  alias: 'My.UfmFilter.Reverse',
+  name: 'Reverse UFM Filter',
+  api: () => import('./reverse.filter.js'),
+  meta: {
+    alias: 'reverse'
+  }
+}
+```
+
+The corresponding JavaScript/TypeScript API would contain a function to transform the value.
+
+```js
+import { UmbUfmFilterBase } from '@umbraco-cms/backoffice/ufm';
+
+class UmbUfmReverseFilterApi extends UmbUfmFilterBase {
+	filter(str?: string) {
+		return str?.split("").reverse().join("");
+	}
+}
+
+export { UmbUfmReverseFilterApi as api };
+```
+
+Using the syntax `{umbValue: headline | reverse}`, e.g. where `headline` having a value of `Hello world` would be transform to `dlrow olleH`.
+
 
 ## Post-processing and sanitization
 
@@ -89,7 +189,8 @@
 - Anchor links will have their target set to `_blank`
 - Only web components that have a prefix of `ufm-`, `umb-` or `uui-` will be allowed to render
 
-## Using UFM in your own components
+
+## Rendering UFM in your own components
 
 If you would like to render UFM within your own web components in the Umbraco CMS backoffice, you can use the `umb-ufm-render` component: