SINCE VERSION 5.0 Feature TAG: F-T37Y

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 referred to as the list input model. It is returned by a pipeline that consolidates data from various locations and provides this data as a JSON Array. The portal finally renders this array to a HTML table:

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

Open

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/schema/<type>.

• List Config
  Defines from which source 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.

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.

Login as a developer and go to LOW CODE -> Properties.

Select an existing app or create a new one first using the App wizard.
For example with app name io.pipeforce.myapp.

Then, click the List Schema wizard and set as name person. Click CREATE:

Open

After this step, a List Schema will be created at path global/app/io.pipeforce.myapp/schema/person, pre-filled with some demo fields similar to this:

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.

Go to LOW CODE -> Properties.

Select your app, for example io.pipeforce.myapp.

Click on the List Config wizard. Set as name also person and click CREATE:

This will create the List Config as JSON property at path global/app/io.pipeforce.myapp/list/person which will look similar to this example:

As you can see in this configuration, there are four main attributes:

• 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 command property.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.

If you take a closer look again into the List Config, you will notice the attribute input which points to the location where the input for the list can be loaded from. In this example, the command property.value.list is used which will load all property values from the property store at a given path given by the pattern attribute. In this example, this pattern is set to global/app/io.pipeforce.myapp/data/person/*. This means, the list expects in this property path JSON properties to be returned.

Go to LOW CODE -> Playground.

Copy & paste and execute this pipeline:

As a result [] will be returned:

The reason for this result is, because currently there is no data yet at location global/app/io.pipeforce.myapp/data/person/*. To create demo data there, copy & paste this pipeline into the playground and execute it:

This will create three simple demo JSON documents:

• global/app/io.pipeforce.myapp/data/person/1

• global/app/io.pipeforce.myapp/data/person/2

• global/app/io.pipeforce.myapp/data/person/3

Execute again this pipeline in the Playground:

As a result, you will see a JSON Array this time with exactly the JSON properties as entries, we have created before:

This is also exactly the input model for our list.

Now we have everything for our list, including data.

Go to APPS -> Installed Apps.

Click your app, for example io.pipeforce.myapp.

Click person to show the list which looks similar to this:

Done. Your list is ready to be used.

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:

• JSON Array row items:

• JSON Object row items:

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:

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:

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:

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

List Schema (JSON Schema)

Feature TAG: F-M6JK ​

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/$TYPE 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/tld.domain.myapp/schema/person.

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

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:

Hide a column (hidden)

Feature TAG: F-VEY9

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

Render cell content as link (href)

FEATURE TAG: F-XYLJ

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

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

FEATURE TAG: F-XALK

In some situations it is necessary to limit the cell text to a max. length. For this you can use the piStyle attribute maxLength in the List Schema. Example:

This will limit the field to a max length of 3 chars plus dots:

Format cell text as badge

FEATURE TAG: F-BYTJ

You can format the text of a cell inside the List Schema and put it into a bage style using the badgeColor attribute of the piStyle element:

This will format any cell text of the column Description into a badge. For example:

Nested Values

Feature TAG: F-SBBH

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

But it is also possible, this array is a mixture of primitive values and objects (= nested value) like this example shows:

Nested values are, by default, displayed in JSON format in the list:

And here is the List Schema which is used for this example:

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:

The labelPath defines the field inside the nested value which should be displayed in the list. All other fields of the nested value in the Details column wont be shown:

It is also possible to point to deeper nested paths for the label. For example:

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

FEATURE TAG: F-FCLJ

Instead of a dynamic value from the nested item, also a fixed text can be shown as label by using the attribute fixedText:

This will render the same, fixed text Click here... on each cell:

Array of nested values

FEATURE TAG: F-O7BW

It is also possible to have a list of nested values to be displayed in a single cell.

See the Orders column in this example. There are multiple orders per cell:

This example uses an input JSON like this:

.. and a List Schema like this, with the piStyle settings from above:

List Config

Feature TAG: F-KQO6

The List Config is the main configuration file for a list. Here you can define the title and description of the list and from 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:

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 list config property must be application/json; type=list.

You can also create it in the web ui in section LOW CODE -> Properties using the List Config wizard.

The most basic structure of this JSON document must be like this:

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: Material Symbols and Icons - Google Fonts

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:

The color value can be a hexadecimal value, like this:
"color": "#FFA500"

Or it can be a constant selected from the Colors palette.

For example you could use the color palette constant “green” like this:
"color": "green"

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).

The list can be still loaded by its URL if required.

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.

For example, the attribute could look like this:

Which could return a JSON schema like this:

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).

For example, the input parameter could look like this in order to load a JSON property from the property store:

Which could return a list data (= model) as JSON array similar to this:

Make a list row editable

Since Version 9.0 Feature Tag: F-KL7AP

It is possible to combine the List Framework with the Forms Framework so a row in a list becomes editable: After such a row was clicked, a modal form opens with all row data in it. The row data can be changed and after submit, the data will be updated in the list. For example:

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:

This List Config needs to be enriched with information about the form to edit a row. To do so, add the attributes formConfig, formInputCol and formOutputCol to the List Config as as shown in this example:

• 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 after SUBMIT 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:

• A column which contains the unique id of a row to load and save it.

• A column which contains the path how to load the row data from backend. Relates to formInputCol.

• A column which contains the path how to save the row data to backend. Relates to formOutputCol.

Let’s assume you already have List Schema like this example:

Now lets add three more top level fields uuid, readPath, writePath to this schema as this example shows at its bottom:

The field uuid contains an id in order to point to a row data set. In this example, this uuid is returned from the backend. But it can be any field capable to identify a single row entry data set. This column is set to "hidden": true in order to not show it in the list.

The added fields readPath and writePath correspond with the value set in the List Config using the attributes formInputCol and formOutputCol. The value of these fields can be any client side PIPEFORCE URI pointing to a location where the row data can be loaded from and written to. This can differ for any row if required.

Additionally the piStyle attribute is used inside readPath and writePath:

• hidden: Set to true 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 the uuid 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 the firstName 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.

Go to LOW CODE -> Properties.

Select your app and create a new Form Config.

Let’s assume you have a Form Config like this:

Additionally, we need to change this so that the fields uuid, readPath and writePath are not shown in this form. To do so, add the layout section to this Form Config as shown in this example:

The layout part explicitly defines the fields which must be displayed in the form. All other fields like uuid, readPath and writePath are ignored and not displayed.

Note: Any input and output settings in this Form Config can be ignored since they will be overwritten by the row edit form using values from readPath and writePath instead.

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).