The term Item Provider Strategy refers to a Magnolia 6 UI abstract logic of accessing form datasource items. It exists in several item provider implementations covering one of the following two uses:
- In a subapp descriptor, usually the detail view.
- In a form definition for composite and complex fields, where a provider replaces the former field transformer functionality that is part of the UI framework 5.
In a subapp definition
In a subapp 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 complex field forms. 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 <link-tasks app> and notifications <notifications app> related items, assets or a specific product items from a defined product location.
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
.