Skip to content

Commit 4a92347

Browse files
sofietoftsofietoft
authored
Merge pull request #6673 from leekelleher/v15/ufm-updates
UFM updates for v15
2 parents 5886eed + 48732e3 commit 4a92347

File tree

1 file changed

+112
-18
lines changed

1 file changed

+112
-18
lines changed

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

Lines changed: 112 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,42 +12,99 @@ UFM is built on top of [GitHub Flavored Markdown](https://github.github.com/gfm/
1212

1313
## Syntax
1414

15-
The essence of the UFM syntax is curly brackets with a marker prefix.
15+
The essence of the UFM syntax is curly brackets with an alias prefix delimited with a colon.
1616

1717
```markdown
18-
{<marker prefix> <contents> }
18+
{<alias prefix>: <contents>}
1919
```
2020

2121
For clarity...
2222

23-
- The opening is `{` U+007B Left Curly Bracket
24-
- The closing is `}` U+007D Right Curly Bracket
25-
- The marker prefix can be any valid Unicode character(s), including emojis
23+
- The opening token is `{` U+007B Left Curly Bracket
24+
- The alias prefix can be any valid Unicode character(s), including emojis
25+
- Followed by `:` U+003A Colon, (not part of the alias prefix itself)
2626
- The contents within the curly brackets can include any Unicode characters, including whitespace
27+
- The closing token is `}` U+007D Right Curly Bracket
2728

28-
An example of this syntax to render a value of a property by its alias is: `{= bodyText }`.
29+
An example of this syntax to render a value of a property by its alias is: `{umbValue: bodyText}`.
2930

30-
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.
31+
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.
3132

32-
With this example, the syntax `{= bodyText }` would be processed and rendered as the following markup:
33+
With this example, the syntax `{umbValue: bodyText}` would be processed and rendered as the following markup:
3334

3435
```js
3536
<ufm-label-value alias="bodyText"></ufm-label-value>
3637
```
3738

3839
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).
3940

40-
## Available UFM components
4141

42-
As for Umbraco 14.1.0, the following UFM components are available to use.
42+
### Filters
4343

44-
| Name | Marker | Example syntax | Renders component |
45-
| ----------- | ------ | ----------------- | ------------------------------------ |
46-
| Label Value | `=` | `{=bodyText}` | `<ufm-label-value alias="bodyText">` |
47-
| Localize | `#` | `{#general_name}` | `<umb-localize key="general_name">` |
44+
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.
45+
46+
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.
47+
48+
To display a rich text value, stripping out the HTML markup and limiting it to the first 15 words could use the following filters:
49+
50+
```markdown
51+
{umbValue: bodyText | strip-html | word-limit:15}
52+
```
53+
54+
The following UFM filters are available to use.
55+
56+
| Name | Alias | Example syntax |
57+
| ---------- | ------------ | -------------------------------------- |
58+
| Lowercase | `lowercase` | `{umbValue: headline | lowercase}` |
59+
| Strip HTML | `strip-html` | `{umbValue: bodyText | strip-html}` |
60+
| Title Case | `title-case` | `{umbValue: headline | title-case}` |
61+
| Truncate | `truncate` | `{umbValue: intro | truncate:30:...}` |
62+
| Uppercase | `uppercase` | `{umbValue: headline | uppercase}` |
63+
| Word Limit | `word-limit` | `{umbValue: intro | word-limit:15}` |
64+
65+
66+
## UFM components
67+
68+
### Available UFM components
69+
70+
The following UFM components are available to use.
71+
72+
- Label Value
73+
- Localize
74+
- Content Name
4875

4976
More UFM components will be available in upcoming Umbraco releases.
5077

78+
79+
#### Label Value
80+
81+
The Label Value component will render the current value of a given property alias.
82+
83+
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>`.
84+
85+
For brevity and backwards-compatibility, the `=` marker prefix can be used, e.g. `{=bodyText}`.
86+
87+
88+
#### Localize
89+
90+
The Localize component will render a localization for a given term key.
91+
92+
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>`.
93+
94+
Similarly, for brevity and backwards-compatibility, the `#` marker prefix can be used, e.g. `{#general_name}`.
95+
96+
97+
#### Content Name
98+
99+
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.
100+
101+
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>`.
102+
103+
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.
104+
105+
106+
### Custom UFM components
107+
51108
If you wish to develop your own custom UFM component, you can use the `ufmComponent` extension type:
52109

53110
```json
@@ -57,14 +114,16 @@ If you wish to develop your own custom UFM component, you can use the `ufmCompon
57114
name: 'My Custom UFM Component',
58115
api: () => import('./components/my-custom.component.js'),
59116
meta: {
60-
marker: '%',
61-
},
117+
alias: 'myCustom'
118+
}
62119
}
63120
```
64121

65122
The corresponding JavaScript/TypeScript API would contain a method to render the custom label/markup.
66123

67124
```js
125+
import { UmbUfmComponentBase } from '@umbraco-cms/backoffice/ufm';
126+
68127
export class MyCustomUfmComponentApi implements UmbUfmComponentBase {
69128
render(token: Tokens.Generic) {
70129
// You could do further regular expression/text processing here!
@@ -75,7 +134,41 @@ export class MyCustomUfmComponentApi implements UmbUfmComponentBase {
75134
export { MyCustomUfmComponentApi as api };
76135
```
77136

78-
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.
137+
Using the `{myCustom: myCustomText}` syntax would render the following markup: `<ufm-custom-component text="myCustomText"></ufm-custom-component>`. Inside the `ufm-custom-component` component code, you can perform any logic to render your required markup.
138+
139+
140+
### Custom UFM filters
141+
142+
If you wish to develop custom UFM filter, you can use the `ufmFilter` extension type:
143+
144+
```json
145+
{
146+
type: 'ufmFilter',
147+
alias: 'My.UfmFilter.Reverse',
148+
name: 'Reverse UFM Filter',
149+
api: () => import('./reverse.filter.js'),
150+
meta: {
151+
alias: 'reverse'
152+
}
153+
}
154+
```
155+
156+
The corresponding JavaScript/TypeScript API would contain a function to transform the value.
157+
158+
```js
159+
import { UmbUfmFilterBase } from '@umbraco-cms/backoffice/ufm';
160+
161+
class UmbUfmReverseFilterApi extends UmbUfmFilterBase {
162+
filter(str?: string) {
163+
return str?.split("").reverse().join("");
164+
}
165+
}
166+
167+
export { UmbUfmReverseFilterApi as api };
168+
```
169+
170+
Using the `{umbValue: headline | reverse}` syntax where `headline` having a value of `Hello world` would be transformed to `dlrow olleH`.
171+
79172
80173
## Post-processing and sanitization
81174
@@ -89,7 +182,8 @@ The sanitized markup will be...
89182
- Anchor links will have their target set to `_blank`
90183
- Only web components that have a prefix of `ufm-`, `umb-` or `uui-` will be allowed to render
91184
92-
## Using UFM in your own components
185+
186+
## Rendering UFM in custom components
93187
94188
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:
95189

0 commit comments

Comments
 (0)