Item provider strategy and item providers

The term Item Provider Strategy refers to an abstract logic of accessing 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 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. 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 the ItemProviderDefinition.
• jcrNodeFromLocationProvider - Resolves node content fro the current location. This provider extends the extends the JcrNodeProviderDefinition.
• delegateToSubNodeProvider -  Returns the parent node. It extends the JcrNodeProviderDefinition. 
• fetchJcrSubNodeProvider -  Resolves child JCR node from the parent. It extends the JcrNodeProviderDefinition 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 the ItemProviderDefinition.