On this page we describe what Item Provider Strategy and item providers are, list the main advantages of using item providers, and show a few examples of item providers in use.
Overview
The term Item Provider Strategy refers to an abstract logic of accessing data source items. In Magnolia 6 UI, the strategy is implemented in the form of item providers . The item providers cover one or more of the following two generic use cases:
- Item provider definition in a sub app descriptor, usually in the detail sub app.
- 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, but no longer part of the Magnolia 6 UI.
Advantages of using item providers
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.
The following item provider types are currently available:
jcrNodeProvider
- Base definition of JCR node provider strategies. It extends theItemProviderDefinition
.jcrNodeFromLocationProvider
- Resolves node content from the current location. This provider 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
.
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 7 below). This type of provider resolves a JCR node from location context:
detail: class: info.magnolia.pages.app.detail.PageDetailDescriptor 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 are provided from a JSON structure through 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. 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
: