CCs - Dynamic Lists control w/ per row actions

Custom Controls are a great way to combine any number of Airkit’s built-in Web Controls into a customized control of your own.

In this guide we’ll be building a Custom Control that displays a list of items to the users using a Repeater with a nested Custom Control that has a view and an edit status, with the options to edit the item’s information or remove the item altogether. Let’s get started.


Pre-requisites

  1. LIST#EDIT(list) - Function to build a list of Booleans (one per each item in the input list) to control the Custom Control’s editable status of all rows
  2. LIST#REMOVE(list, item_index) - Function to remove the item at index from our list
  3. PERSON - App Obj or Custom Type that describes the items to be displayed in the list

List UDFs

LIST#EDIT(<Datatype: list>)

Create a new UDF, with a list input of Datatype: List of JSON, and an output of Datatype: List of Boolean. Set the UDF’s Body to:

FROM index IN list SELECT FALSE

LIST#REMOVE(<Datatype: List of Any>, <Datatype: Number>)

Create a new UDF, with a list input of Datatype: List of JSON, a item_index input of Datatype: Number, and an output of Datatype: List of JSON. Set the UDF’s Body to:

FROM item IN list WHERE NOT(index = item_index) SELECT item

Custom Data Types

In Data Builder create a new Custom Data Type and add three fields to it:

  • first_name - Datatype: Text
  • last_name - Datatype: Text
  • user_id - Datatype: Text


Custom Control Design

For this exercise, we’ll be using the following JSON as the base item to be displayed (we’ll just tweak it a little bit to populate the Summary CC).

  {
    "first_name": "James",
    "last_name":"Bond",
    "user_id": 007
  }

The Row Custom Control will include:

  • View status
  • Edit status

Each status will be displaying a different Container to the user, making use of the Container’s isVisible property.
Both statuses should include the option to remove the item from the main list.

The Summary Custom Control will include:

  • A header
  • A Repeater (List) of Row CCs that is populated with a List of JSON objects

Building the Row CC

Main Structure

  1. Add a new Custom Control to your application, name it ‘row’ (you can change this later)

  2. Add a read-only Template Variable of Datatype: Boolean to the control, name it edit

  3. Add an editable (read-only unchecked) Template Variable of Datatype: PERSON to the control, name it person

  4. Add three events to the control, name one edit, the second one save, and the last one remove, add a variable to each event of Datatype: PERSON and name it person

  5. Inside the default Container of the row control, add two new containers, view and edit

  6. in the Advanced tab for each container, set the isVisible property to: edit = FALSE on the view container, and edit = TRUE on the edit container.
    Note: NOT(edit) and edit should also work, the former values are provided for ease of understanding.

Now that the basic structure of the row control is set up, let’s dig in to the different statuses

View status

  1. Inside the view container, add three labels (one for each of the fields in the PERSON object), make sure the Container’s Children are distributed Horizontally to display all of them as a row.

  2. Bind each one to person.field_name where field_name will be one of: first_name, last_name, user_id

  3. Add two buttons, one for the Edit action, and another one for the Remove action.

  4. Set the buttons’ Clicked Actions to Invoke Event, bind the Edit button to the edit event, and the Remove button to the remove event.

Edit status

  1. Inside the edit container, add a form with three Inputs (one for each of the fields in the PERSON object), and a Save button. Make sure the Container’s Children are distributed Horizontally to display all of them as an inline form.

  2. Bind each Input control to one of the person fields: person.first_name, person.last_name, and person.user_id


Building the Summary CC

Main Structure

  1. Add a new Custom Control to your application, name it ‘summary’ (you can change this later)

  2. Add an editable (read-only unchecked) Template Variable of Datatype: List of PERSON to the control, name it person_list

  3. Add a read-only Template Variable of Datatype: Boolean to the control, name it edit

  4. Add three events to the control, name one edit, the second one save, and the last one remove, add the following to each event: a variable of Datatype: PERSON and name it person, and a variable of Datatype: Number and name it index

  5. Inside the default Container of the summary control, add two new containers, header and list

  6. The header container will look pretty much like the row’s view container, except it’ll have hard-coded values for the column names: First, Last, ID, and Actions (instead of the action buttons)

Now that the basic structure of the summary control is set up, let’s dig in to the summary list

List Control

  1. Add a Repeater to the list container, bind the Data to the input.person_list cc input

  2. Add a Simple Cell to the List

  3. Add a row Custom Control to the the Simple Cell

Row CC setup

  1. Set the row’s cc person input to the List’s item

  2. Set the row’s cc edit input to edit[index] (change the edit status for that row alone)

  3. Add an Invoke Event action to each of the row’s cc events, and bind each to the corresponding summary cc events (edit, save, remove)

Done! Now we can go to our Web Flows and implement the Custom Control in one of our Web Pages.


Custom Control Implementation

Pre-requisites

The following are not mandatory to run the Custom Control (all values can be hard-coded), but they are part of any Airkit application and as such, it’s always good practice to set it up in the suggested way.

  • Add a Web Flow Variable person_list of Datatype: PERSON. This variable will hold the list of JSON objects used to populate our Custom Control. For testing purposes, you can add a Web Flow Updated action to Set a Variable person_list to the list below, but in practice you’ll want to populate this with
    • The results of a Data Flow
    • The results of an API call
    • The information entered in a Portal, etc.
      [
        {
          "first_name": "James",
          "last_name": "Bond",
          "user_id": "007"
        },
        {
          "first_name": "Maxwell",
          "last_name": "Smart",
          "user_id": "86"
        }
      ]
      
  • Add a Web Page variable edit of Datatype: List of Boolean. This variable will hold the list of edit status for the different objects in our person_list. Add a Web Page Viewed action and Set a Variable edit to
    LIST#EDIT(
      person_list
    )
    
    This will make all rows to the view status on page load.

Add and Configure the Custom Control

  1. In your Web Page you’ll want to add a new Web Control, scroll down to the Custom category and select the summary control.

  2. Configure the Custom Control

    1. Bind the Web Flow’s person_list variable to the CC’s person_list input
    2. Bind the Web Page’s edit variable to the CC’s edit input
    3. Add a Set a Variable action to the edit event of the control and set it up like so
    4. Add a Set a Variable action to the save event of the control and set it up like so
    5. Add a Set a Variable action to the remove event of the control to update the person_list and set the value to
      LIST#REMOVE( person_list, event.index )

The Custom Control implementation is now complete. Feel free to run your app in Preview or Publish it.


This is what the Custom Control looks like (with a little styling here and there)

Custom Controls - Dynamic List management

:information_source: Click >>here<< to play around with a live version of this Custom Control.

5 Likes

This is super helpful @juanchax. This is really useful in learning how to leverage the new custom types feature, user defined functions, and custom controls all in one exercise. Thank you for the write up!

2 Likes