Reference

Every Live Data instance is described by one JSON document. The "liveData" Macro and the Script Service build part of it from their parameters, merge the JSON written in the Macro content into it and add the default values. Macro parameters win when both set the same property.

It has three parts:

• query, what to fetch
• data, what was fetched
• meta, how to interact with it

{
  //
  // The query
  //

  "query": {
    // The list of properties to fetch.
    "properties": ["title", "year", ...],

    "source": {
      // The component hint of the live data source
      "id": "...",

      // Parameters specific to each live data source implementation. This can also be used to implement hidden filters, that the user cannot change from the live data UI.
      "customParam1": "...",
      ...
    },

    // Filter the live data entries.
    "filters": [
      {
        "property": "title",
        "matchAll": true,
        "constraints": [
          {"operator": "contains", "value": "help"},
        ],
      },
    ],

    // The list of properties to sort on.
    "sort": [
      {
        "property": "birthdate",
        "descending": false
      },
    ],

    // Indicates where the current page starts.
    "offset": 0,

    // The number of entries to fetch (the page size).
    "limit": 10
  },

  //
  // The data
  //

  "data": {
    // The total number of entries available (on the server side).
    "count": 54,

    "entries": [
      {
        // property: value
        "title": "Work from home",
        "year": 2020,
        ...
      },
      ...
    ],
  },

  //
  // The meta data (used to control how we interact with the data)
  //

  "meta": {
    "defaultLayout": "table",

    "layouts": [
      {
        "id": "table",
        "name": "Table",
        "icon": {"iconSetName": "Font Awesome", "cssClass": "fa fa-table"},
      },
      {
        "id": "cards",
        "name": "Cards",
        "icon": {"iconSetName": "Font Awesome", "cssClass": "fa fa-th"},
        "titleProperty": "doc_title",
      },
    ],

    // Describes the properties that may appear in the data set. This determines the list of known (available)
    // properties. Creating new properties, removing existing properties as well as editing the property descriptor
    // should be done through this array.
    "propertyDescriptors": [
      {
        // Identifies the property that this descriptor corresponds to.
        "id": "title",

        // The property name. Could be displayed before the property value.
        "name": "Title",

        // Could be displayed when hovering the property name.
        "description": "...",

        // Could be displayed before the property name, if specified.
        "icon": {...},

        // The property type, selected when creating the property. It is used to prefill the property descriptor.
        // Could be mapped to an xclass property type.
        "type": "String",

        // Whether the user can sort on this property or not.
        "sortable": true,

        // Whether to user can edit in-place this property (the user also need to have the right to edit a given entry to edit it).
        "editable": true,

        // Whether to show this property or not.
        "visible": true,

        // Displayer configuration.
        "displayer": {
          "id": "link",

          // Indicates the property whose value is the URL that should be used as the link target (e.g. 'doc.url').
          "propertyHref": "...",
          
          // Whether to allow HTML in the link content, used by the 'link' displayer
          "html": true
        },

        // Whether the user can filter by this property or not.
        "filterable": true,

        // Filter configuration.
        "filter": {
          "id": "text",

          // This is used only by the 'text' filter (which receives the property descriptor).
          "match": "prefix"
        },

        // Optional CSS class name to add to the HTML element used to display this property.
        "styleName": "..."
      }
    ],

    // The list of known property types. When creating a new property the user can select from this list and the
    // property descriptor will be prefilled based on the selected property type.
    "propertyTypes": [
      {"id": "string", "name": "String", "icon": {...}, "sortable": true, "displayer": {...}, "filterable": true, "filter": {...}},
      ...
    ],

    "defaultFilter": "text",

    // The list of known filters to choose from when editing the property descriptor.
    "filters": [
      {"id": "text", ...},
      {"id": "date", ...}, 
      {"id": "list", ...},
      {"id": "number", ...},
      {"id": "boolean", ...},
      ...
    ],

    // The list of known property displayers to choose from when editing the property descriptor.
    "displayers": [
      {"id": "text", ...},
      {"id": "html", ...},
      {"id": "link", ...},
      {"id": "actions", ...},
      {"id": "date", ...},
      {"id": "boolean", ...},
      {"id": "number", ...},
      {"id": "docTitle", ...},
      {"id": "xObjectProperty", ...},
      ...
    ],

    "defaultDisplayer": "text",

    // Configure the pagination display.
    "pagination": {
      // The maximum number of page links to display in the pagination.
      "maxShownPages": 10,
      "pageSizes": [15, 25, 50, 100],
      "showEntryRange": true,
      "showNextPrevious": true,
      "showFirstLast": false,
      "showPageSizeDropdown": false
    },

    "entryDescriptor": {
      // The property that can be used to identify a live data entry. This is used for entry selection.
      "idProperty": "doc.fullName",
    },

    // The list of actions known / supported by this live data instance. This is used by the actions displayer.
    "actions": [
      {
        "id": "view",
        "name": "View",
        "description": "View entry",
        "icon": {...},
        "allowProperty": "doc.viewable",
        "urlProperty": "doc.url"
      },
      // Specify the edit action with an allowProperty to control who can in-place edit the entries
      // By default, the action is allowed.
      {
        "id": "edit",
        "allowProperty": "doc.editable"
      }
      ...
    ],

    // Selection configuration.
    "selection": {
      // Whether to enable or not the entry selection (e.g. for batch actions). 
      "enabled": false
    }
  }
}

Actions

The action descriptors have a allowProperty field. This field references another property of the entry, holding a boolean value indicating whether the action is allowed for the current entry.
The example below declares an action A whose allow property is allowA.

{
  "data": {
    "count": 2,
    "entries": [
      {
        "title": "Allowed Entry",
        "allowA": true
      },
      {
        "title": "Disallowed Entry",
        "allowA": false
      }
    ]
  },
  "meta": {
    "propertyDescriptors": [
      {
        "id": "title",
        "type": "String"
      },
      {
        "id": "allowA",
        "type": "Boolean"
      },
      {
        "id": "_actions",
        "name": "_actions",
        "visible": true,
        "displayer": { "id": "actions", "actions": ["actionA"] }
      }
    ],
    "entryDescriptor": {
      "idProperty": "title"
    },
    "actions": [
      {
        "id": "actionA",
        "name": "Action A",
        "description": "Perform action A",
        "allowProperty": "allowA"
      }
    ]
  }
}

Asynchronous Actions

An action can be declared asynchronous. In this case, instead of following the link, the action will be performed in the background. The Live Data is refreshed once the asynchronous action is successful.

Parameters

The parameters are to be added to the async key of the action, located in the meta.actions array. The URL is the one resolved through the urlProperty of the action.

• httpMethod: the HTTP method to use to call the action URL
• loadingMessage: the localized message to display while the action is running asynchronously
• successMessage: the localized message to display once the action finished successfully
• failureMessage: the localized message to display once the action finished unsuccessfully
• body: (optional) a value to use in the request body
• headers (optional) a map of headers to use for the request

Example

{{liveData
  id="test"
  properties="name,_actions"
  source="liveTable"  sourceParameters="className=Space.MyClass"
}}{
  "meta": {
    "actions": [{
        "id": "delete",
        "async": {
          "httpMethod": "POST",
          "loadingMessage": "Loading",
          "successMessage": "Delete Success",
          "failureMessage": "Failed",
          "body": "newBacklinkTarget=&updateLinks=false&autoRedirect=false&form_token=${services.csrf.token}&confirm=1&async=true",
          "headers": {
            "Content-Type": "application/x-www-form-urlencoded"
          }
        }
      }]
  }
}
{{/liveData}}

Colored Icons

It is possible to add additional classes on icons (in addition to the one possible introduced by the icon sets) by adding the extraIconClasses property on icon descriptors.

On the example below, we add the text-danger class on the delete action, making the delete action icon displayed in the danger color (i.e., red by default).
{"id": "delete", "icon": "cross", "extraIconClasses": "text-danger"}

FAQ

Which wins, a Macro parameter or the same property in the Macro content?

The Macro parameter: the two configurations are merged and the one built from the parameters takes precedence.

How do I hide an action from some entries only?

By naming a Boolean property of the entry in the allowProperty field of the action descriptor.

How do I see the configuration actually applied?

By calling effectiveConfig on the Script Service, which normalises a configuration and fills in the defaults.

Can a source parameter act as a filter the reader cannot remove?

Yes. Parameters under query.source are passed to the source and never surfaced in the Filter panel.

Related

• Live Data Extension Points