The data is made available under the specified name and can then be used in textual content by means of placeholders, or in DataLocators.
Makes external data 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, or in DataLocators.
Params
name (String) – The class name under which the external data will be available.params (Object) – An object with a connection key and an optional attributes key.
connection (Object | Promise) – An object containing asynchronous callbacks for fetching the external data – or a promise resolving to a connection object.get (Function) – A callback for fetching a single piece of data by a given ID.index (Function) – An optional callback for fetching a set of data.create (Function) – An optional callback for creating a single piece of data.update (Function) – An optional callback for updating a single piece of data.delete (Function) – An optional callback for deleting a single piece of 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 a promise. Keys of a schema are attribute names, and the values are attribute types (e.g. "string", "enum" and so on), or optional configurations objects. If no schema has been provided, Scrivito assumes that it is empty ({}).Returns
DataClass – A data class that can be used to provide an editing configuration for the external data.
Example
See Letting Editors Create Web Interfaces Utilizing Data for a detailed example.
get
The get callback is for fetching a single piece of data by a given ID. Scrivito executes the passed-in function and waits for the returned promise to resolve.
Params
id (String) – ID of the data to be fetched. Scrivito supports hexadecimal as well as numeric IDs.Returns
Promise<Object or null> – A plain JavaScript object representing the external data. If the promise resolves with null, the corresponding external data is assumed to be missing.Example
index
The index callback is for fetching a set of data. Scrivito executes the passed-in function, providing it with IndexParams, and waits for the returned promise to resolve with an IndexResponse object.
Params
params (IndexParams) – An object containing details about which data to fetch.Returns
Promise<IndexResponse | DataConnectionError>:
IndexResponse (Object) – A plain JavaScript object representing the response. This object can have the following properties:results (Array) – An array representing the results. Each result must either be an ID or an Object with an _id property containing the ID and the rest of the data as properties. For the ID format, see Data IDs.continuation (String) – An optional continuation token. It can be used to indicate to Scrivito that not all results have been fetched yet. Scrivito will then use the continuation token to fetch the next results.count (Number) – The optional total number of items matching params.filters() and params.search(), but ignoring params.limit(). If params.includeCount() is true, count must be present in the response for DataScope#count to return meaningful data.DataConnectionError – If an error occurs within the index callback (e.g. an HTTP 4xx/5xx response from the backend), you can resolve the callback with a Scrivito.DataConnectionError. This will trigger a Scrivito.DataScopeError when DataScope#take or DataScope#count is called – which can then be handled inside the app.Example
create
The create callback is for creating a single piece of data. Scrivito executes the passed-in function, providing it with data, and waits for the returned promise to resolve with a CreateResponse object.
Params
data (Object) – A plain JavaScript object representing the external data.Returns
CreateResponse (Object) – A plain JavaScript object representing the external data. This object must have the _id property containing the data ID of the new piece of data. If there are further properties available, the Scrivito SDK will use them to set the local state of the data.Example
update
The update callback is for updating a single piece of data. Scrivito executes the passed-in function, providing it with data, and waits for the returned promise to resolve with an UpdateResponse object.
Params
id (String) – ID of the data to be updated.data (Object) – A plain JavaScript object representing the external data.Returns
UpdateResponse (Object) – An optional plain JavaScript object representing the external data. If the object is present, the Scrivito SDK will use its properties to update the local state of the data.Example
delete
The delete callback is for deleting a piece of data. Scrivito executes the function passed in to the DataClass, providing it with the ID, and waits for the returned promise to resolve.
Params
id (String) – ID of the data to be deleted.Example
A schema can be provided as an object, as a promise that will resolve with a schema object, or as a function that returns such a promise. The keys of a schema object are attribute names, and the values are attribute types (e.g. string, date, etc.) or attribute configurations. The types supported are string, number, boolean, enum, date and reference.
Whenever an attribute is read, written or filtered, and there is a schema entry for this attribute, its value is matched against its attribute definition. If the value does not match the Scrivito type in the attribute definition, an error is logged and a default value is returned. However, if there is no schema entry for the attribute in question, it is not checked.
For some types, additional conditions are checked:
date – Must be an ISO 8601 string, i.e. have the format YYYY-MM-DDTHH:mm:ss.sssZ or YYYY-MM-DDTHH:mm:ssZreference – Must be a valid IDenum – Must be one of the values from the schemaWhen reading an attribute, Scrivito compares the JSON type of the attribute from the callback response with the Scrivito type from the provided attribute definition. If they are compatible as described in the table below, Scrivito returns the corresponding value as the app type. Otherwise, a default value is returned.
When writing data, Scrivito compares the type of the given value with the Scrivito type from the attribute definition. The value can be provided either as an app type, e.g., in case of a date attribute, as an instance of Date, or as a JSON type, an ISO 8601 string. If they are compatible, Scrivito forwards the corresponding value as a JSON type to the update callback. Otherwise, an error is thrown.
When filtering by an attribute, Scrivito forwards the provided filters to the IndexParams. When doing so, Scrivito matches the value of the provided filters (which can also be provided as either an app type or as a JSON type) against their attribute definitions. If they are compatible, Scrivito forwards the corresponding values as a JSON type to the index callback. If they are not, an error is thrown.
| Scrivito type | JSON type | App type | Default |
|---|---|---|---|
string | String | String | "" |
number | Number | Number | null |
boolean | Boolean | Boolean | false |
enum | String | String | null |
date | String | Date | null |
reference | String | DataItem | null |
Note that DataItem#get returns null for nonexistent attributes. An attribute is treated as nonexistent if it is not specified in the schema, and if the returned data contains no key or a key with the value undefined.
The keys of a schema object are attribute names, and the values are attribute types (string or date) or attribute configurations. An attribute configuration is an array with two elements where the first element is the attribute type, and the second one is a configuration object. Configuration objects are optional for the string, boolean, number and date types, but can be used to provide a schema localization. In addition to localization, configuration objects provide the necessary validation information, and are required for the enum and reference attribute types.
For an enum attribute, a configuration object must include the values option containing the values valid for this attribute:
For a reference attribute, a configuration object must include the to option containing the name of the class that can be assigned to the attribute as a reference:
An attribute configuration object can also contain localization information, for attributes as well as for enum values. For example:
This localization information can be used by the application (e.g. DataWidgets) when rendering UI elements related to attributes.
If the editing configuration also provides attribute localization (via the attributes key), the UI uses it and ignores the localization in the schema.
A reference attribute can be navigated in two directions, forward (from the source of the reference to its target) and backward (from a target of a reference to all sources). Forward navigation is also known as a belongs-to relationship, and backward navigation as a has-many relationship (RubyOnRails uses this notation, for example). For this reason, a reference attribute can have two localizations, one for each direction:
title: The localization of the reference when used in the normal (forward) way,reverseTitle: The localization of the has-many style relationship when navigating backwardsSince the schema definition for a data class may reside on an external system, it is possible to provide the schema in an async fashion, which enables lazy loading, meaning that the schema is only loaded if it is needed:
Scrivito expects external data to be passed in as plain JavaScript objects. The names of data object properties must be valid data identifiers.
[New in 1.46.0]The values can be of the String, Number, Boolean, Object or Array type. However, values of the Object type must not contain a property named _type. The same applies to the first element of values containing an array of Objects.
The ID of a piece of data can be one of:
String: A hexadecimal ID with at least eight characters (e.g. fedcba9876543210), or a composite ID with groups of hexadecimal or numeric IDs, optionally separated by dashes (e.g. a1b2c3d4-1-dea8be6f) Number: A numeric ID consisting of an integer value ≥0 (e.g. 1234). IDs of this data type must be a safe integer.IDs made up of any characters can be handled by converting them to hexadecimal character strings.