...
Table of Contents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
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.
...
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.
Quick Start
In case you are in a hurry or you want to create your first list without going into details, follow these steps in this quick start:
Step 1: Create a List Schema
The first step is to create the List Schema. This is a JSON file which specifies the columns of the list in the JSON Schema format.
...
Info |
---|
A List Schema is 100% a JSON Schema. Here you define the structure of a row of your input model to the list. Each field on first level of the schema will represent a column configuration of your list. You can change the demo data in it later and adjust it to fit your needs. |
Step 2: Create a List Config
The next step is to create the List Config. This is also a JSON file which configures for example where to load the data for the list from, what the name of the list is and more.
...
title
: The title of the list to be displayed in the app.description
: The optional description of the list.schema
: A client side PIPEFORCE URI which points to the location where the List Schema can be loaded from. As you can see, in this example this is the path to the List Schema we have created in step 1.input
: A client side PIPEFORCE URI which points to the location where the data for the list can be loaded from. In this example it points to a single commandproperty.value.list
. But it can also point for example to a persisted pipeline which loads, prepares and returns the input model for the list.
Step 3: Create Input Model (data)
At this point, you have everything you need to display your list. However, you still need to provide the data for it, and this is what we will do in this step.
...
For more details how to customize the list to fit even better your needs, read the details below.
List Input Model
The input model to the list is always a root JSON Array. The entries of this root JSON Array are the rows of the list whereas these rows can be one of:
...
Info |
---|
|
JSON Array row items
The list input model can be of this format where each row is itself is a JSON Array containing the cell data as items:
...
Info |
---|
The JSON array format is the most effective format and should be preferred whenever possible. |
JSON Object row items
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:
...
Info |
---|
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 less complex, smaller in size and therefore better performing. |
List Schema (JSON Schema)
Status | ||||
---|---|---|---|---|
|
...
Info |
---|
The List Schema describes the row item of the source JSON Array. 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)
Status | ||||
---|---|---|---|---|
|
...
Code Block | ||
---|---|---|
| ||
{ "type": "object", "properties": { "firstName": { "type": "string", "piStyle": { "hidden": true } }, ... } } |
Render cell content as link (href)
Status | ||||
---|---|---|---|---|
|
...
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.
Limit cell text
Status | ||||
---|---|---|---|---|
|
...
This will limit the field to a max length of 3 chars plus dots:
...
Format cell text as badge
Status | ||||
---|---|---|---|---|
|
...
This will format any cell text of the column Description into a badge. For example:
...
Nested Values
Status | ||||
---|---|---|---|---|
|
...
Code Block | ||
---|---|---|
| ||
{ "type": "object", "properties": { "id": { "type": "number", "title": "Customer ID" }, "name": { "type": "string", "title": "Customer Name" }, "order": { "type": "object", "title": "Order", "properties": { "orderId": { "type": "number" }, "orderDate": { "type": "string" } } } } } |
Label Path
You can specify a single item out of the nested object which should be displayed as label using the piStyle
attribute labelPath
. For example:
...
Code Block |
---|
"labelPath": "level1.level2.level" |
Nested Label Badge
In order to format a nested label using a badge, you can again use the badgeColor
attribute:
...
This will render the label in the Details column like this example:
...
Make label clickable / Show details
You can make the label clickable. If the user click such a label, then a view is rendered which shows the nested value as JSON. To do so add the attributes contentType: "application/json"
and "openInViewerOnClick": true
to the List Schema:
...
If the user clicks on the label, a view opens with a JSON tree inside:
...
Use fixed label text
Status | ||||
---|---|---|---|---|
|
...
This will render the same, fixed text Click here...
on each cell:
...
Array of nested values
Status | ||||
---|---|---|---|---|
|
...
Info |
---|
Note that the orders |
List Config
Status | ||||
---|---|---|---|---|
|
...
Code Block | ||
---|---|---|
| ||
{ "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
defines the title of the list to be displayed in the web ui and in other locations.
This can be a static text or an i18n uri like $uri:i18n:myTitle
for example. See: Internationalization (i18n)
description
The description
is optional and describes the intention of the list.
This can be a static text or an i18n uri like $uri:i18n:myDescription
for example. See: Internationalization (i18n)
icon
Each list can have an individual icon. This value must be a code name from the Google Material Icons as listed here: https://fonts.google.com/icons
This value is optional. If not given, the default icon is shown:
...
color
The color of the list icon. If not specified, the secondary color is used, which depends on the style settings. By default this is a blue color like this:
...
Another example:
"color": "red-8"
...
hidden
This optional attribute defines whether the list should be shown as tile inside the app ("hidden": false
) or not ("hidden": true
).
...
If this attribute is missing, "hidden": false
is used as a default.
schema
A PIPEFORCE URI pointing to the location where to load the List Schema from.
...
Code Block |
---|
{ "type": "object", "properties": { "firstName": { "type": "string", "title": "First Name", "description": "The first name of the person." }, "lastName": { "type": "string", "title": "Last Name", "description": "The last name of the person." }, "age": { "type": "number", "title": "Age", "description": "The age of the person." }, "gender": { "type": "string", "title": "Gender", "description": "The gender of the person.", "enum": [ "male", "female", "neutral" ] }, "birthDate": { "type": "string", "format": "date", "title": "Date of birth", "description": "The date of birth of the person." } } } |
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).
...
Code Block |
---|
[ ["Sam", "Smith", 38, "male", "04/04/1989"], ["Marisha", "Mayer", 42, "female", "03/08/1979"], ["Lee", "Long", 55, "male", "01/02/1968"] ] |
Make a list row editable
Status | ||||
---|---|---|---|---|
|
Status | ||||
---|---|---|---|---|
|
...
Let’s see here how this can be configured…
Step 1: Change List Config
Let’s assume you have a List Config like this at path global/app/io.pipeforce.myapp/list/person
:
...
formConfig
: This is the path of the property which defines the Form Config for the row form. This is a standard Form Config as described in the Forms Framework. So you can use all the features of the forms framework here. Note that the Form Schema and List Schema here are sharing the same structure so both pointing to the same schema property as defined in the List Config.formInputCol
: This is the id of the column which contains the (hidden) client side PIPEFORCE URI to load the input data for the form so it can be edited.formOutputCol
: This is the id of the column which contains the (hidden) client side PIPEFORCE URI to store the form data to afterSUBMIT
was clicked in the row form.
Step 2: Change List Schema
The next step is to change the List Schema and add three more columns:
...
hidden
: Set totrue
in order to not show the value of this column in the list.value
: Since the backend isn’t returning any value for this field, a fixed value for this column from client side is set here. The keyword${row.uuid}
is a special variable which will be rendered at client side for any row and in this case it will be replaced by the value of theuuid
column of the current row. This way you can set the uuid of the current row in order to read and write it in the form. You can refer to any column field here by its id in order to construct a valid client side PIPEFORCE URI required to read and write row data. For example in order to refer to thefirstName
field, you would use${row.firstName}
instead.
Step 3: Create the row edit form
As last step you have to create the form which should be displayed in case a row has been clicked.
...
Done. If you open your list and click a row, the form will load the current row data by using the PIPEFORCE URI of column readPath
and shows this data in a form defined by the form config. On SUBMIT it will use the PIPEFORCE URI of column writePath
to store changed data back to the backend.
Internationalization (i18n)
Text elements of the list can also be internationalized (= translated to different languages). See here for more details, how this works: Internationalization (i18n).
...