Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents
minLevel1
maxLevel3
outlinefalse
typelist
printablefalse

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

...

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
  • All row items of a single List Input Model must have the same data structure.

  • Primitive and nested objects are allowed as values.

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
colourPurple
titleFeature TAG: F-M6JK

...

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
colourPurple
titleFeature TAG: F-VEY9

...

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

Render cell content as link (href)

Status
colourPurple
titleFEATURE TAG: F-XYLJ

...

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
colourPurple
titleFEATURE TAG: F-XALK

...

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

...

Format cell text as badge

Status
colourPurple
titleFEATURE TAG: F-BYTJ

...

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

...

Nested Values

Status
colourPurple
titleFeature TAG: F-SBBH

...

Code Block
languagejson
{
  "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
colourPurple
titleFEATURE TAG: F-FCLJ

...

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

...

Array of nested values

Status
colourPurple
titleFEATURE TAG: F-O7BW

...

Info

Note that the orders type is now array since it can contain multiple order entries.

List Config

Status
colourPurple
titleFeature TAG: F-KQO6

...

Code Block
languagejson
{
  "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
colourBlue
titleSince Version 9.0
Status
colourPurple
titleFeature Tag: F-KL7AP

...

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 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:

...

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

...

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

...