From 6ea6ca902b251f4056b8285511af5b6807665723 Mon Sep 17 00:00:00 2001 From: leekelleher Date: Thu, 14 Nov 2024 15:47:06 +0000 Subject: [PATCH 1/9] Updates UFM with "alias prefix" info --- .../reference/umbraco-flavored-markdown.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/15/umbraco-cms/reference/umbraco-flavored-markdown.md b/15/umbraco-cms/reference/umbraco-flavored-markdown.md index c9aa518f8f2..787b00531d4 100644 --- a/15/umbraco-cms/reference/umbraco-flavored-markdown.md +++ b/15/umbraco-cms/reference/umbraco-flavored-markdown.md @@ -12,24 +12,25 @@ UFM is built on top of [GitHub Flavored Markdown](https://github.github.com/gfm/ ## 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 -{ } +{: } ``` 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 @@ -57,7 +58,7 @@ If you wish to develop your own custom UFM component, you can use the `ufmCompon name: 'My Custom UFM Component', api: () => import('./components/my-custom.component.js'), meta: { - marker: '%', + alias: 'myCustom', }, } ``` @@ -75,7 +76,8 @@ export class MyCustomUfmComponentApi implements UmbUfmComponentBase { export { MyCustomUfmComponentApi as api }; ``` -Using the syntax `{% myCustomText }` would render the markup ``. 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 ``. Then inside the `ufm-custom-component` component code, you can perform any logic to render your required markup. + ## Post-processing and sanitization From d3efc898da22dc5615904754baaa4c1b718ec904 Mon Sep 17 00:00:00 2001 From: leekelleher Date: Thu, 14 Nov 2024 15:47:57 +0000 Subject: [PATCH 2/9] Updates "Available UFM components" --- .../reference/umbraco-flavored-markdown.md | 44 ++++++++++++++++--- 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/15/umbraco-cms/reference/umbraco-flavored-markdown.md b/15/umbraco-cms/reference/umbraco-flavored-markdown.md index 787b00531d4..4d0e9585065 100644 --- a/15/umbraco-cms/reference/umbraco-flavored-markdown.md +++ b/15/umbraco-cms/reference/umbraco-flavored-markdown.md @@ -38,17 +38,49 @@ With this example, the syntax `{umbValue: bodyText}` would be processed and rend 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. -| Name | Marker | Example syntax | Renders component | -| ----------- | ------ | ----------------- | ------------------------------------ | -| Label Value | `=` | `{=bodyText}` | `` | -| Localize | `#` | `{#general_name}` | `` | + +## 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 ``. + +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 ``. + +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 ``. + +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. + + If you wish to develop your own custom UFM component, you can use the `ufmComponent` extension type: ```json From a98d6fd8fac0b24f6176857a541b98c73d73c573 Mon Sep 17 00:00:00 2001 From: leekelleher Date: Thu, 14 Nov 2024 15:49:29 +0000 Subject: [PATCH 3/9] Documents UFM Filters --- .../reference/umbraco-flavored-markdown.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/15/umbraco-cms/reference/umbraco-flavored-markdown.md b/15/umbraco-cms/reference/umbraco-flavored-markdown.md index 4d0e9585065..9f0138fa462 100644 --- a/15/umbraco-cms/reference/umbraco-flavored-markdown.md +++ b/15/umbraco-cms/reference/umbraco-flavored-markdown.md @@ -39,6 +39,19 @@ With this example, the syntax `{umbValue: bodyText}` would be processed and rend 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). +### Filters + +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 @@ -81,6 +94,21 @@ The alias prefix is `umbContentName` An example of the syntax is `{umbContentNa 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. + If you wish to develop your own custom UFM component, you can use the `ufmComponent` extension type: ```json From dc703e8c09b28a40f45aa237895cfd0b8e37f3fe Mon Sep 17 00:00:00 2001 From: leekelleher Date: Thu, 14 Nov 2024 15:49:45 +0000 Subject: [PATCH 4/9] Heading amends --- 15/umbraco-cms/reference/umbraco-flavored-markdown.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/15/umbraco-cms/reference/umbraco-flavored-markdown.md b/15/umbraco-cms/reference/umbraco-flavored-markdown.md index 9f0138fa462..07a53ddddd3 100644 --- a/15/umbraco-cms/reference/umbraco-flavored-markdown.md +++ b/15/umbraco-cms/reference/umbraco-flavored-markdown.md @@ -109,6 +109,9 @@ As of Umbraco 15.0.0, the following UFM filters are available to use. 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 @@ -151,7 +154,8 @@ The sanitized markup will be... - 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: From a440004742c691e9e103d3d086d0afb78bf42bf6 Mon Sep 17 00:00:00 2001 From: leekelleher Date: Thu, 14 Nov 2024 16:00:12 +0000 Subject: [PATCH 5/9] Documents `ufmFilter` extension type --- .../reference/umbraco-flavored-markdown.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/15/umbraco-cms/reference/umbraco-flavored-markdown.md b/15/umbraco-cms/reference/umbraco-flavored-markdown.md index 07a53ddddd3..af235779d5a 100644 --- a/15/umbraco-cms/reference/umbraco-flavored-markdown.md +++ b/15/umbraco-cms/reference/umbraco-flavored-markdown.md @@ -142,6 +142,39 @@ export { MyCustomUfmComponentApi as api }; Using the syntax `{myCustom: myCustomText}` would render the markup ``. 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 When the markdown has been converted to HTML, the markup will be run through post-processing sanitization to ensure security and consistency within the backoffice. From 23a118c9cd6441fe02dd7ac0e3df04d62ce9b287 Mon Sep 17 00:00:00 2001 From: leekelleher Date: Thu, 14 Nov 2024 16:00:32 +0000 Subject: [PATCH 6/9] Code snippet amends --- 15/umbraco-cms/reference/umbraco-flavored-markdown.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/15/umbraco-cms/reference/umbraco-flavored-markdown.md b/15/umbraco-cms/reference/umbraco-flavored-markdown.md index af235779d5a..2010ebc5d89 100644 --- a/15/umbraco-cms/reference/umbraco-flavored-markdown.md +++ b/15/umbraco-cms/reference/umbraco-flavored-markdown.md @@ -121,14 +121,16 @@ If you wish to develop your own custom UFM component, you can use the `ufmCompon name: 'My Custom UFM Component', api: () => import('./components/my-custom.component.js'), meta: { - alias: 'myCustom', - }, + 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! @@ -139,7 +141,7 @@ export class MyCustomUfmComponentApi implements UmbUfmComponentBase { export { MyCustomUfmComponentApi as api }; ``` -Using the syntax `{myCustom: myCustomText}` would render the markup ``. 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 ``. Then inside the `ufm-custom-component` component code, you can perform any logic to render your required markup. ### Custom UFM filters From e68543bb57c8fcbd3375fb55942a0e1972d74c6f Mon Sep 17 00:00:00 2001 From: Lee Kelleher Date: Tue, 19 Nov 2024 11:58:32 +0000 Subject: [PATCH 7/9] Apply suggestions from code review Thanks @sofietoft! Co-authored-by: sofietoft --- .../reference/umbraco-flavored-markdown.md | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/15/umbraco-cms/reference/umbraco-flavored-markdown.md b/15/umbraco-cms/reference/umbraco-flavored-markdown.md index 2010ebc5d89..0696aeef813 100644 --- a/15/umbraco-cms/reference/umbraco-flavored-markdown.md +++ b/15/umbraco-cms/reference/umbraco-flavored-markdown.md @@ -43,9 +43,9 @@ The internal working of the `ufm-label-value` component would then be able to ac 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. +The syntax for UFM filters uses a pipe character `|` (U+007C Vertical Line). Multiple filters may be applied, and 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: +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} @@ -58,7 +58,7 @@ A list of available UFM filters is detailed below. ### Available UFM components -As of Umbraco 15.0.0, the following UFM components are available to use. +The following UFM components are available to use. - Label Value - Localize @@ -73,7 +73,7 @@ The Label Value component will render the current value of a given property alia The alias prefix is `umbValue`. An example of the syntax is `{umbValue: bodyText}`, which would render the component as ``. -For brevity and backwards-compatibility (with Umbraco 14.1.0), the `=` marker prefix can be used, e.g. `{=bodyText}`. +For brevity and backwards-compatibility, the `=` marker prefix can be used, e.g. `{=bodyText}`. #### Localize @@ -82,7 +82,7 @@ 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 ``. -Similarly, for brevity and backwards-compatibility (with Umbraco 14.1.0), the `#` marker prefix can be used, e.g. `{#general_name}`. +Similarly, for brevity and backwards-compatibility, the `#` marker prefix can be used, e.g. `{#general_name}`. #### Content Name @@ -96,7 +96,7 @@ As of Umbraco 15.0.0, the Content Name component supports the content-based pick ### Available UFM filters -As of Umbraco 15.0.0, the following UFM filters are available to use. +The following UFM filters are available to use. | Name | Alias | Example syntax | | ---------- | ------------ | -------------------------------------- | @@ -107,7 +107,6 @@ As of Umbraco 15.0.0, the following UFM filters are available to use. | 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 @@ -141,12 +140,12 @@ export class MyCustomUfmComponentApi implements UmbUfmComponentBase { export { MyCustomUfmComponentApi as api }; ``` -Using the syntax `{myCustom: myCustomText}` would render the markup ``. Then inside the `ufm-custom-component` component code, you can perform any logic to render your required markup. +Using the `{myCustom: myCustomText}` syntax would render the following markup: ``. 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: +If you wish to develop custom UFM filter, you can use the `ufmFilter` extension type: ```json { @@ -174,7 +173,7 @@ class UmbUfmReverseFilterApi extends UmbUfmFilterBase { 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`. +Using the `{umbValue: headline | reverse}` syntax where `headline` having a value of `Hello world` would be transformed to `dlrow olleH`. ## Post-processing and sanitization @@ -190,7 +189,7 @@ The sanitized markup will be... - Only web components that have a prefix of `ufm-`, `umb-` or `uui-` will be allowed to render -## Rendering UFM in your own components +## Rendering UFM in custom 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: From 167e1c6794633a007e62391c77156f911551a65c Mon Sep 17 00:00:00 2001 From: leekelleher Date: Tue, 19 Nov 2024 12:01:30 +0000 Subject: [PATCH 8/9] Moved the "Available UFM filters" higher up --- .../reference/umbraco-flavored-markdown.md | 26 +++++++------------ 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/15/umbraco-cms/reference/umbraco-flavored-markdown.md b/15/umbraco-cms/reference/umbraco-flavored-markdown.md index 0696aeef813..1b7fe8dcfde 100644 --- a/15/umbraco-cms/reference/umbraco-flavored-markdown.md +++ b/15/umbraco-cms/reference/umbraco-flavored-markdown.md @@ -51,7 +51,16 @@ To display a rich text value, stripping out the HTML markup and limiting it to t {umbValue: bodyText | strip-html | word-limit:15} ``` -A list of available UFM filters is detailed below. +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}` | ## UFM components @@ -94,21 +103,6 @@ The alias prefix is `umbContentName` An example of the syntax is `{umbContentNa 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 - -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}` | - - - ### Custom UFM components If you wish to develop your own custom UFM component, you can use the `ufmComponent` extension type: From 48732e3c3d5c69fbae5b0d5601654a566b579e42 Mon Sep 17 00:00:00 2001 From: Lee Kelleher Date: Wed, 20 Nov 2024 08:10:26 +0000 Subject: [PATCH 9/9] Update 15/umbraco-cms/reference/umbraco-flavored-markdown.md Co-authored-by: sofietoft --- 15/umbraco-cms/reference/umbraco-flavored-markdown.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15/umbraco-cms/reference/umbraco-flavored-markdown.md b/15/umbraco-cms/reference/umbraco-flavored-markdown.md index 1b7fe8dcfde..2bcdd826bc4 100644 --- a/15/umbraco-cms/reference/umbraco-flavored-markdown.md +++ b/15/umbraco-cms/reference/umbraco-flavored-markdown.md @@ -100,7 +100,7 @@ The Content Name component will render the name of a content item, (either Docum The alias prefix is `umbContentName` An example of the syntax is `{umbContentName: pickerAlias}`, which would render the component as ``. -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. +The Content Name component supports content-based pickers, such as the Document Picker, Content Picker (formerly known as Multinode Treepicker), and Member Picker. Support for the advanced Media Picker will be available in an upcoming Umbraco release. ### Custom UFM components