List Framework
SINCE VERSION 5.0 DRAFT
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 |
---|---|---|---|
|
|
|
|
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
TODO