Item provider strategy and item providers

On this page we describe what item providers are, list their main advantages and show a few examples of using them.

Overview

Item providers are a means for accessing items from data sources. Developed for the Magnolia 6 UI, item providers help 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 item providers

Item providers represent a much simpler solution than the 5 UI field transformers.

Now, 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 6 UI, data updates should be piped into the back-end items via simple fields by means of Vaadin 8 data binding (Binder objects).
Unlike transformers, item providers do not have to deal with the deprecated Vaadin 7 Item API and do not require manual verifications that child properties are populated within an item.
Item providers have a clearer concept of chaining. They get a reference of an item from a previous level in the hierarchy, making the whole complex data binding process recursive.
The number of provider types is much lower in Magnolia 6 UI, compared to a relatively high number of field transformers in the 5 UI.
There's also provider implementations that can handle JSON structures, task and notifications items, assets or specific product content items.

Provider types

The following item provider types are currently available:

jcrNodeFromLocationProvider - Resolves node content from the current location.
jcrGetCurrentNodeProvider - Returns the parent node.
jcrGetChildNodeProvider - Resolves child JCR node from the parent.
jsonProvider - Usable mainly in REST -related contexts, for example in client definitions of the REST Client module, it replaces the {id} path parameter with the one passed in the location and then fetches the result using a configured REST call.

The jcrGetCurrentNodeProvider and jcrGetChildNodeProvider are suitable for sub forms only since a dependency on a parent node is presupposed to exist.

Used 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 provider type 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.)

Used 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
          itemProvider:
            $type: jcrChildNodeProvider
          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 jcrChildNodeProvider resolves the content of the child items city and country from the parent address:

Page tree