New in 1.43.0 (BETA)

provideDataItem(name, getCallback | connection | params)

Makes external data globally available to the application.

The data is made available under the specified name and can then be used in textual content by means of placeholders.

Params

  • name (String) – The name under which the external data should be made available globally.
  • [New in 1.44.0]params (Function | Object | Promise)
    • A function the SDK uses as the get callback (see connection below).
    • A connection object or a promise resolving to one (see connection below).
    • An object with a connection key, and an optional attributes key.
      • connection (Object | Promise) – An object containing a callback for fetching and optionally one for updating the item data – or a promise resolving to a connection object.
        • get (Function) – An asynchronous callback for fetching the external data.
        • update (Function) – An optional asynchronous callback for updating the external data.
      • attributes (Object, Promise or Function) – an optional schema. The schema can be provided as an object, as a promise that will resolve with a schema object, or as a function that returns such promise. Keys of a schema are attribute names and the values are attribute types (e.g. "string", "enum", etc.), or optional configuration objects. If no schema has been provided, Scrivito will assume that it is empty ({}). See Scrivito.provideDataClass for further details about schemas.

Callbacks

get

The get callback retrieves external data. Scrivito executes the passed-in function and awaits the outcome of the returning promise. It is required to provide this callback to provideDataItem as shown above.

Returns

  • Promise<Object | null> – A plain JavaScript object containing the external data that can be used to provide an editing configuration. If the promise resolves with null, the external data is assumed to be missing.

Example

Make external data available under the name LoggedInUser:

The external data can be referenced within textual content via placeholders:

When this text is rendered using Scrivito.ContentTag, the placeholder is replaced with the referenced external data:

update

The optional update callback updates the piece of external data passed in via the data argument, and waits for the promise to resolve.

Params

  •  data (Object) – A plain JavaScript object containing the external data.

Returns

  • Promise<unknown>

Example

Update the external data available under the name LoggedInUser:

Remarks

As an alternative to providing a connection object containing the get callback function, the latter can be provided to provideDataItem directly as the second argument:

The connection object can also be provided to provideDataItem directly as the second argument:

In-place editing

The external data is also available when content is being edited in place. Here’s how the object returned by Scrivito.provideDataItem can be used to configure user-interface-related aspects:

See also Scrivito.provideEditingConfig.

What is a placeholder?

A placeholder consists of two underscores, followed by a valid identifier, a dot, then another valid identifier and another two underscores.

The first identifier references the name under which the external data was made available, e.g. LoggedInUser or ProductDetails, while the second identifier references the attribute name of the external data, e.g. email or price:

What is a valid identifier?

The key parts of a placeholder are its identifiers. They allow Scrivito to determine the value the placeholder stands for. Identifiers must follow these rules:

  • The first character must be a letter (a-zA-Z).
  • Subsequent characters may also be digits (0-9) and underscores (_).
  • Two consecutive underscores are not allowed.
  • The last character must not be an underscore.
  • No whitespace or other characters are allowed.
  • Only standard ASCII letters, no umlauts or Unicode characters are allowed.
  • The length of an identifier must not exceed 50 characters.