Item provider strategy and item providers

Item providers are a means for accessing items from data sources. On this page, we provide more information about what item providers are, list their main advantages and show a few examples of using them.

Overview

The concept of Item providers is an abstraction aiming to give developers a flexible way to specify which item a form field (simple or complex) should bind to and how the item schould be accessed.

It allows to bind form views to complex nested datastructures and fine tune such binding. E.g. if a form binds a contact address as a separate sub-form (in M5 words - e.g. as a composite field), the Magnolia user might want to use a contact's child node to store the data (item provider that resolves a sub-node can be used), or store the properties directly on the contact node keeping it flat (self-reference item provider case).
item providers get reference items as context. I.e. an address editor from the example upon data binding will get the root contact node so that it would be trivial to resolve the corresponding sub-node if needed. Forms are always populated and persisted from top of the hierarchy to the bottom.
Item providers kick in the form lifecycle only twice (typically): when the data is fetched from the backend (to populate the form) and when the updated data needs to be flushed from the Vaadin components back to the backend (on form commit).
item providers yield items wrapped into Optional container, so it is fine not to return anything from the item provider implementation (in such case though, the form data may not be populated or saved back to the backend).

Where are they used

Item providers are used in the following two use cases:

Item provider definition in a detail subapp.
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 its 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