Item providers

Item providers are a means for accessing items from data sources. On this page, we provide more details about their characteristics and main advantages, and we 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 an item should be accessed.

Item providers allow you to bind form views to complex nested data structures and to fine tune such bindings. For example, if a form binds a contact address as a separate sub-form (a composite field in the Magnolia 5 UI context), a Magnolia user might want to:

  • Use a contact’s child node to store the data, in which case an item provider that resolves a sub-node can be used.

  • Store the properties directly on the contact node and keep it flat. This would represent a self-reference item provider use case.

Item providers get reference items as context. Applied to the contact address example, an address editor will get the root contact node so that it would be trivial to resolve the corresponding sub-node, if needed.

Typically, item providers are executed only:

  • When fetching data from the back-end (to populate a form).

  • When some updated data needs to be flushed from the Vaadin components back to the back-end (on a form commit).

Last but not least, item providers yield items wrapped into the Optional container, so it is fine not to return anything from the item provider implementation. In this case, however, the form data may not be populated or saved back to the back-end.

Main advantages

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

  • 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 Magnolia 6 UI, data updates should be piped into 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.

Where they can be used

Item providers can be used in:

  • 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.

Provider types

For any data source

$type Description

currentItemProvider

info.magnolia.ui.editor.CurrentItemProviderDefinition

Returns the parent node. Suitable for sub-forms only since it relies on a parent.

Do not use currentItemProvider with multi fields. The same nodes could be resolved by multiple fields that use currentItemProvider, which means their content would be overwritten. Additionally, if a multi field is not configured to resolve nodes strictly (the strict property is set to false by default), it will resolve irrelevant nodes from the parent and likely result in errors.

If you use currentItemProvider with composite or switchable fields, make sure that none of the inner field names clash with:

  • Other inner field names at the level where currentItemProvider is used

  • Other field names one level up where the composite or switchable field is defined

That is, every field at every level must have a unique name. Otherwise, nodes sharing the same name could be resolved by multiple fields that use currentItemProvider, which means their content would be overwritten.

Example name conflict
form:
  properties:
    first_compositeField:
      $type: compositeField
      itemProvider:
        $type: currentItemProvider
      properties:
        inner_simple: # duplicate name
          $type: textField # first text
        inner_simple2:
          $type: textField # second text
    second_compositeField:
      $type: compositeField
      itemProvider:
        $type: currentItemProvider
      properties:
        inner_simple3:
          $type: textField # third text
        inner_simple: # duplicate name
          $type: textField # fourth text

# Problem with using currentItemProvider
edited_node:
  inner_simple: fourth text # first text is overwritten by second inner_simple
  inner_simple2: second text
  inner_simple3: third text

# Using jcrChildNodeProvider with both composite fields would fix the problem
edited_node:
  first_compositeField:
    inner_simple: first text
    inner_simple2: second text
  second_compositeField:
    inner_simple3: third text
    inner_simple: fourth text # no name conflict

For JCR data source

$type Description

jcrChildNodeProvider

info.magnolia.ui.editor.JcrChildNodeProviderDefinition

Resolves a JCR child node from the parent. Suitable for sub-forms only since it relies on a parent.

jcrChildNodeProvider is used by default in info.magnolia.ui.field.JcrMultiFieldDefinition.

jcrChildNodeProvider always creates subnodes for content underneath, but these nodes are cleaned up on the first commit of a form if it remains empty (when no content is added). If you need to persist those empty nodes for any reason, please use removeIfEmpty: false in the configuration of the provider.

jcrBlockGetIndexedChildNode

Implementation class of info.magnolia.editor.block.jcr.JcrBlockChildNodeProviderStrategy that extends the JcrChildNodeProvider.

Resolves indexes of the child nodes in a block of a content editor app.

When info.magnolia.editor.block.jcr.MultiJcrBlockDefinition is used, info.magnolia.editor.block.MultiBlockView has multiple child blocks and needs the JcrBlockChildNodeProviderStrategy to resolve child block indexes.

This provider can only be used in block definitions of content editor apps based on the migrated Content Editor (version 2.0 and higher).

jcrGetProperty

info.magnolia.ui.editor.JcrPropertyProvider

Proposes a JCR node property as an item datasource. Typically used in complex fields with sub-editors where a single field entry needs to be exposed as an editor.

jcrGetProperty is used by default in info.magnolia.ui.field.JcrMultiValueFieldDefinition.

jcrNodeFromLocationProvider

info.magnolia.ui.editor.JcrNodeFromLocationResolutionDefinition

Resolves JCR node content from the current location.

For JSON data source

$type Description

jsonFieldPropertyProvider

info.magnolia.rest.ui.field.JsonFieldPropertyProviderDefinition

Proposes a JSON node property as an item data source. Typically used in complex fields with sub-editors where a single field entry needs to be exposed as an editor.

jsonMultiFieldPropertyProvider

info.magnolia.rest.ui.field.JsonMultiFieldPropertyProviderDefinition

Proposes a JSON node property as an item data source in a multi field context. Typically used in complex fields with sub-editors where a single field entry needs to be exposed as an editor.

jsonMultiFieldProvider

info.magnolia.rest.ui.field.JsonMultiFieldProviderDefinition

Resolves a JSON child node from the parent in a multi field context. Suitable for sub-forms only since it relies on a parent.

jsonProvider

info.magnolia.rest.ui.JsonItemProviderStrategyDefinition

Replaces the {id} path parameter with the one passed in the location and then fetches the result using a configured REST call.

In subapp definition

jcrNodeFromLocationProvider is used, for example, in the Pages app. This provider resolves a JCR node from its location context.

detail:
  class: info.magnolia.pages.app.detail.PageDetailDescriptor
  datasource:
    $type: jcrDatasource
    workspace: website
  itemProvider:
    $type: jcrNodeFromLocationProvider

For the full definition, see pages-app.yaml.

Using item providers is not limited only to operations related to JCR content. See the following definition where content items are provided from a JSON structure through jsonProvider.

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

In form definition

A provider strategy can be applied to handle data-read operations in forms with complex fields. For example, see jcrChildNodeProvider in the following definition of a complex field called address, composed of two simple fields (city and country).

Defining provider types in form definition

address:
  label: address
  i18n: true
  $type: compositeField
  itemProvider:
    $type: jcrChildNodeProvider
  properties:
    city:
      label: city
      $type: textField
    country:
      label: country
      i18n: true
      $type: textField

For the full definition, see contacts-v8.yaml.

Using jcrChildNodeProvider resolves the content of the child items city and country from the parent address.

JCR child and parent nodes

Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules