SINCE VERSION 5.0 DRAFT

1 What is the List Framework?
2 List Input Model
- 2.1 Row items as JSON Array
- 2.2 Row items as JSON Object
3 List Schema (JSON Schema)
4 List Config
5 Edit a row item
6 Server side search

What is the List Framework?

The List Framework in PIPEFORCE renders a given JSON Array as HTML table list in the web portal. This table can then ordered, searched and filtered.

The JSON Array is called the list input model and is returned by a pipeline which consolidates data from any combination of different locations and returns this data as JSON Array. The portal finally renders this array to a HTML table:

This is how such a table will look like in the portal:

In order to implement a list in PIPEFORCE, you have to create two JSON documents:

List Schema
Defines the structure of row items and columns of the table. For example the header, the data type and the conversion rules if required. This document is typically located at $APP_HOME/object/<type>/v1/schema.json.
List Config
Defines form which pipeline to load the JSON Array for the list from. This document is typically located at $APP_HOME/list/<type>.

After these two JSON documents have been created, the list is shown in the app view as list tile. When clicking this tile, the list will be loaded.

List Input Model

The input model to the list is always a JSON Array. The items of this JSON Array are the rows items whereas they can be of one of:

JSON Array values
JSON Object values

Row items as JSON Array

The list input model can be of this format where each row is itself is a JSON Array containing the cell data as items:

[
    ["Value 1", "Value 2", "Value 3"],
    ["Value 4", "Value 5", "Value 6"],
    ["Value 7", "Value 8", "Value 9"],
]

The “root array” contains a list of arrays where each item of it represents the row with the values to be rendered in the list similar to this example structure:

Value 1	Value 2	Value 3
Value 4	Value 5	Value 6
Value 7	Value 8	Value 9

The JSON array format is the most effective format and should be preferred whenever possible.

Row items as JSON Object

Another option for the list input model could be to contain a list of JSON Objects whereas the name of the object fields correspond to the column headers and the value will become the cell value:

[
  {
     "make": "Mercedes",
     "maxspeed": "250",
     "type": "S300",
   },
  {
     "make": "BMW",
     "maxspeed": "260",
     "type": "530",
   },
  {
     "make": "Tesla",
     "maxspeed": "260",
     "type": "ModelS",
   }
]

Each JSON object in the array will finally be rendered as a single row to the list as this example shows:

Mercedes	250	S300
BMW	260	530
Tesla	260	ModelS

Since this input data format is very “noisy” (it repeats the attribute names for each single cell), you should prefer the nested array format whenever possible since it is better performing.

List Schema (JSON Schema)

The List Schema is a JSON Schema file which defines the structure of each row item. Additionally it configures how the columns must be displayed in the list. It is a JSON document which follows the schema specification from json-schema.org.

The List Schema is typically located in the property store at $APP_HOME/object/$TYPE/v1/schema.json whereas $APP_HOME stands for the home path of your app and $TYPE stands for the JSON object type your schema describes. For example: global/myapp/object/person/v1/schema.json.

Here is a simple example of a person object described in a List Schema (JSON Schema):

{
    "type": "object",
    "properties": {
        "firstName": {
            "title": "First Name",
            "type": "string",
            "description": "This is the first name of the person."
        },
        "lastName": {
            "title": "Last Name",
            "type": "string",
            "description": "This is the last name of the person."
        },
        "age": {
            "title": "Age",
            "type": "number",
            "description": "This is the age of the person."
        },
        "gender": {
            "title": "Gender",
            "type": "string",
            "description": "This is the gender of the person.",
            "enum": ["Female", "Male"]
        }
    }
}

Each properties entry in this JSON Schema defines a single column in the list. The title of a property will be used as the caption for a column. Therefore, finally we expect to have a table with these columns and headers:

First Name	Last Name	Age	Gender

First Name	Last Name	Age	Gender

The List Schema describes the row item of the source JSON Array, not the array structure. This way a Form Schema can also be used as a List Schema since they can define the same, shared entity. Both are based on the JSON Schema format.

Hide a column (hidden)

You can hide a column in the table by setting the custom attribute piStyle with value "hidden": true as this example shows:

{
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string",
            "piStyle": {"hidden": true}
        },
        ...
    }
}

Render cell content as link (href)

In order to show the cell content as link, you have to set the custom attribute piStyle accordingly. See this example:

{
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string",
            "piStyle": {"href": "https://host/edit?name=${row.firstName}"}
        },
        ...
    }
}

You can use the variable ${row.<field>} to access the value of a field of the current row by replacing <field> with the id of the field those value to access.

Show nested values as badges

Until now we assumed that the input data is always a JSON array with flat primitive types like string or number:

[
    ["A1", "A2", "A3"],
    ["B1", "B2", "B3"]
]

But it is also possible, that an entry in this array is an object (= nested value) like this example shows:

[
    [["Orange", "Green"], "A2", "A3"],
    [["Blue"],            "B2", "B3"]
]

In this example the first column now contains also a nested array. Each entry in this array is shown in the table automatically as badge (1):

By default the string representation of the nested values will be shown in badges. But you can also specify the path to a label inside the nested element to be displayed.

For example, let’s assume there is an input JSON JSON array with nested order objects per row like this:

[
  [1, {"order": {"orderId": "123", "orderDate": "01/23"}}],
  [2, {"order": {"orderId": "124", "orderDate": "02/23"}}]
]

And no lets assume you would like to use the orderDate as label for the badges, then you have to define this in your List Schema like this example shows:

{
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string",
            "piStyle": {"labelPath": "order.orderDate"}
        },
        ...
    }
}

The labelPath points to the attribute inside the nested object which those value must be used as the badge label.

In case the user click on such a badge, the nested object will be shown.

List Config

The List Config is the main configuration file for a list. Here you can define things like the title and description of the list or where the schema and input data should be loaded from.

In order to create a new list and show it as a new entry in your apps tiles listing, you have to add the list config as a new property to this path in the property store:

global/app/tld.domain.myapplist/<listname>

Whereas <listname> is a lower-case and unique name for the list in a format supported by the property path.

The content type of the property must be application/json; type=list.

The structure of this JSON document must be like this:

{
  "title": "The title of the list",
  "description": "The description of the list",
  "input": "$uri:command:property.value.list?pattern=global/app/../*",
  "schema": "$uri:property:global/app/path/to/my-list-schema",
}

title - The title to show for this list on app tiles for example.
Can also be an i18n key, see https://logabit.atlassian.net/wiki/spaces/PA/pages/2549088261 .
description - The optional description to show for this list on app tiles for example.
Can also be an i18n key, see https://logabit.atlassian.net/wiki/spaces/PA/pages/2549088261.
input - A PIPEFORCE URI pointing to the location where to load the input model from (must be a JSON array whereas each item represents a single row in the table).
schema - A PIPEFORCE URI pointing to the location where to load the List Schema from.

Edit a row item

TODO

Server side search