The term Item Provider Strategy refers to an abstract logic of accessing form datasource items. Several item provider implementations are available in Magnolia 6 UI, covering one of the following two generic uses:
- Data item provider definition in a sub app descriptor, usually in the detail sub app.
- Data item provider definition In a form containing composite and complex fields. In this use, the provider replaces the former field transformer functionality that is part of the UI framework 5.
In a sub app definition
In a sub app definition, a strategy is implemented for example in the Pages app, where the jcrNodeFromLocationProvider
is used (see line 16 below). This type of provider resolves a JCR node from location context:
detail: class: info.magnolia.pages.app.detail.PageDetailDescriptor extensionViews: title: class: info.magnolia.pages.app.detail.extension.PageTitleViewDefinition status: class: info.magnolia.pages.app.detail.extension.PublishingStatusViewDefinition link: class: info.magnolia.pages.app.detail.extension.NativePagePreviewLinkViewDefinition language: class: info.magnolia.pages.app.detail.extension.LanguageSelectorViewDefinition datasource: $type: jcrDatasource workspace: website itemProvider: $type: jcrNodeFromLocationProvider
(A snippet of an existing full definition, see https://git.magnolia-cms.com/projects/MODULES/repos/pages/browse/magnolia-pages-app/src/main/resources/pages-app/apps/pages-app.yaml.)
An item provider is not limited only to operations related to JCR content. See the following definition, where content items need to be provided from a JSON structure, requiring the use of the jsonProvider
(line 16):
view: label: View Commit class: info.magnolia.ui.contentapp.detail.DetailDescriptor datasource: $type: jsonDatasource restClient: bitbucket restCall: commit jsonPathExpressions: properties: author: '$.author.raw' actions: cancel: label: Cancel $type: closeAction itemProvider: $type: jsonProvider
(A snippet of an existing full definition, see https://git.magnolia-cms.com/projects/MODULES/repos/rest-client/browse/declarative-rest-demo/apps/commits.yaml#50-65.)
In a form definition
A strategy can be used to handle data-read operations in forms containing complex field. Item Provider Strategy is a much simpler solution than the 5 UI field transformers. An item provider only needs to know how to access the data. In contrast, the transformers in the 5 UI framework were responsible for both types of data operations - reading and writing. In addition to this:
- The 6 UI strategy is implemented in a much reduced number of item providers compared to a relatively high number of field transformers in the 5 UI.
- The implementations can handle also JSON structures, task and notifications items, assets or a specific product content items.
Consider the following definition of a complex field called address
, composed of two simple fields, city
and country
.
address: label: address i18n: true $type: compositeField description: > A composite field made by several components. Field layout can be changed by specifying a different layout definition itemProvider: $type: fetchJcrSubNodeProvider properties: city: label: city $type: textField country: label: country i18n: true $type: textField
(A snippet of an existing full definition, see https://git.magnolia-cms.com/projects/MODULES/repos/contacts-app/browse/src/main/resources/contacts/apps/contacts-v8.yaml#320-336.)
Using the fetchJcrSubNodeProvider
resolves the content of the child items city
and country
from the parent address
:
Item provider types
The following item provider types are currently available:
jcrNodeProvider
- Base definition of JCR node provider strategies. It extends theItemProviderDefinition
.jcrNodeFromLocationProvider
- Resolves node content fro the current location. This provider extends the extends theJcrNodeProviderDefinition
.delegateToSubNodeProvider
- Returns the parent node. It extends theJcrNodeProviderDefinition
.fetchJcrSubNodeProvider
- Resolves child JCR node from the parent. It extends theJcrNodeProviderDefinition
and is suitable for the sub-forms only, since it relies on the parent.jsonProvider
- Replaces the{id}
path parameter with the one passed in the location and then fetches the result using a configured rest call. This provider type extends theItemProviderDefinition
.