Building truly reusable components means finding the right compromise between hard-coded logic, parametric adjustment and customisation. In this post, I want to share my way of building customisable components.

Background

To understand how this works, we have to start with a specific feature of the Appian expression language. It is a functional language with expression rules as first class citizens. This means, that you can pass references to expression rules just like any other value to a rule input of the type Any or a local variable and then execute them. Find the documentation here.

Let’s do a quick example. My first rule is this:

ReferencedRule(name(text))

"Hello " & ri!name & "!"

Then I can write code like below:

a!localVariables(
  local!rule: rule!SSH_ReferencedRule,
  
  local!rule(name: "Stefan")
)

Take a close look at line 2. By omitting the brackets, I assign a reference to the local variable instead of calling it. I can then execute the reference stored in the local by treating it like a normal rule.

Customisable Components

With this technique at hand, you can build a framework component like a grid, and then let the designer pass an expression to display each item. Let’s have a look at an example. This needs three separate expressions.

EXP_SegmentList

As I want to put a grid onto the screen, I somehow need to turn a list of items into a two-dimensional matrix. I use the following expression out of my toolbox to turn a list of items into a list of lists of items with a defined length. It transforms a one-dimensional list (1, 2, 3, 4, 5) into a two-dimensional ((1, 2, 3), (4, 5)). I added some additional features to allow a 90° rotation ((1, 4), (2, 5), (3)) and padding to have a uniform number of items in each column or row.

It uses the following rule inputs:

• items: Any Type
• segmentSize: Integer
• rotate: Boolean
• enablePadding: Boolean

if(
  or(
    a!isNullOrEmpty(ri!items),
    a!isNullOrEmpty(ri!segmentSize)
  ),
  ri!items,
  a!localVariables(
    local!numSegments: ceiling(count(ri!items) / ri!segmentSize),
    if(
      ri!rotate,
      /* WITH ROTATION: segmentSize means the number of segments */
      if(
        ri!enablePadding,
        /* WITH PADDING: Adds type casted NULL values to the last segment to fill up to the size of the segment */
        a!forEach(
          items: enumerate(ri!segmentSize),
          expression: index(
            ri!items,
            1 /* First item in list is at index 1 and enumerate creates numbers starting at 0 */
            + fv!item /* Start number for current segment */
            /* Fix segment size */
            + enumerate(local!numSegments)
            * ri!segmentSize,
            cast(runtimetypeof(ri!items[1]), null)
          )
        ),
        /* WITHOUT PADDING: Only add left over items into the last segment. The last segment might contain less items */
        a!forEach(
          items: enumerate(ri!segmentSize),
          expression: reject(
            a!isNullOrEmpty(_),
            index(
              ri!items,
              1 /* First item in list is at index 1 and enumerate creates numbers starting at 0 */
              + fv!item /* Start number for current segment */
              /* Adjust the size of the segment to either the required size or for the last segment the left over items */
              + enumerate(local!numSegments)
              * ri!segmentSize,
              null
            )
          )
        )
      ),
      /* WITHOUT ROTATION: segmentSize means the number of items per segment */
      if(
        ri!enablePadding,
        /* WITH PADDING: Adds type casted NULL values to the last segment to fill up to the size of the segment */
        a!forEach(
          items: enumerate(local!numSegments),
          expression: index(
            ri!items,
            1 /* First item in list is at index 1 and enumerate creates numbers starting at 0 */
            + (fv!item * ri!segmentSize) /* Start number for current segment */
            /* Fixe segment size */
            + enumerate(ri!segmentSize),
            cast(runtimetypeof(ri!items[1]), null)
          )
        ),
        /* WITHOUT PADDING: Only add left over items into the last segment. The last segment might contain less items */
        a!forEach(
          items: enumerate(local!numSegments),
          expression: index(
            ri!items,
            1 /* First item in list is at index 1 and enumerate creates numbers starting at 0 */
            + (fv!item * ri!segmentSize) /* Start number for current segment */
            /* Adjust the size of the segment to either the required size or for the last segment the left over items */
            + enumerate(min(ri!segmentSize, count(ri!items) - (fv!item * ri!segmentSize))),
            null
          )
        )
      )
    )
  )
)

EXP_RenderGridItem

This expression is responsible for rendering an individual item from the list. In my example, these items only have a single field “name”. There is no restriction to the complexity or source of the items you want to use. Just make sure that your expression works with your data structure.

The rule inputs are:

• item: Any Type (This can also be your CDT or Record type, or a map)

a!cardLayout(
  showWhen: a!isNotNullOrEmpty(ri!item),
  contents: {
    a!richTextDisplayField(
      labelPosition: "COLLAPSED",
      value: ri!item.name
    )
  },
  height: "AUTO",
  style: "NONE",
  marginBelow: "STANDARD",
  showBorder: false,
  showShadow: true
)

EXP_Grid

This is my framework component, which uses a foreach() to create a columns layout for the horizontal dimension. In each column, the inner foreach() calls the contentExpression to display the actual contents in a vertical orientation.

It needs the following rule inputs:

• items: Any Type
• contentExpression: Any Type
• numColumns: Integer

a!columnsLayout(
  columns: a!forEach(
    items: rule!PCO_SegmentList(
      items: ri!items,
      segmentSize: ri!numColumns,
      rotate: true,
      enablePadding: true
    ),
    expression: a!columnLayout(
      contents: a!forEach(
        items: fv!item,
        expression: ri!contentExpression(
          item: fv!item
        )
      )
    )
  )
)

If you like, you can add a default rendering style and make the contentExpression optional. Below, a simple example:

        expression: if(
          a!isNullOrEmpty(ri!contentExpression),
          a!richTextDisplayField(
            label: "Default",
            value: tostring(fv!item)
          ),
          ri!contentExpression(
            item: fv!item
          )
        )

Putting the Pieces Together

Let’s do a quick recap. You now have an expression that can render a two-dimensional matrix of items onto the screen. And you have another expression which knows how to display an individual item. Putting it together should look like this:

rule!EXP_Grid(
  items: {
    {name: "One"},
    {name: "Two"},
    {name: "Three"},
    {name: "Four"},
    {name: "Five"},
  },
  contentExpression: rule!EXP_ContentExpression,
  numColumns: 2
)

Summary

I hope I could give you some insights into advanced coding techniques using the Appian expression language and inspiration for building your own customisable components.

I am very curious about the ideas you will implement with this method. Let me know in a comment.