Working with Lists

Documentation home 

 

See also: List Layout, How to use Dynamic Lists, How to use Static Lists, Working with Databases

 

 

This document describes the various options available to display and configure lists.

 

Lists on Input Fields 1

Displaying Static Content as a List 2

Displaying Dynamic Content as a List 3

Advanced Dynamic Content 5

List Layout 5

 

 

Lists on Input Fields

Any form field or table column in a form can be associated with a list by configuring the list properties of the field/column. The list is then displayed to the user by adding the field/column to a page. Three types of list are supported:

 

 

 

 

// create simple list with three entries

var list1 = ["Line 1", "Line 2", "Line 3"];

fields.Field1.createCustomList(list1);

 

// create list with both displayed and return values

var list2 = fields.Field1.createCustomList();

list2.add("Display Value 1", "Returned value 1");

list2.add("Display Value 2", "Returned value 2");

list2.add("Display Value 3", "Returned value 3");

 

Each list can be displayed as a dropdown, radio button or checkbox depending on the form field’s display type.

 

Each list entry can optionally contain both a displayed value and a returned value. This allows you to display a descriptive name while retaining a key value e.g. if displaying employee details, the department_id field might contain a numeric id but be displayed as the descriptive department name. With a Dynamic List the displayed and returned columns are configured when you map the list to a field.

 

When a field associated with a list is display only, the displayed value is shown.

 

The text 'Please Select' or its equivalent in other languages represents a null value and by default appears at the top of each list. This text can be changed or suppressed for individual lists by configuring the Header text options in the list tab of the field’s properties. The default header text is taken from system text 21 – if you would like to change this text for all lists, edit this text.

 

 

Displaying Static Content as a List

To start with, the word static used in this context just means that you know at design time what the content will be e.g. a list of menu items – it has nothing to do with the Static List entity described in the previous section.

 

Static content can be built up using a List Panel Control, then adding List Item Controls and any other controls to this. For example, a menu with three items could be configured as:

 

 

..displays as:

But this could also be configured to display as a horizontal menu by including the appropriate classes on the List Item controls. This is just a simple example: a List Item Control is a general purpose container control and can be used to contain any combination of additional controls.

 

To style the List Panel Control, select it then click Control Style to display its styling dialog. This allows configuration of the list type (unordered or ordered list), the list style type (configures the bullet or number style) and a few other basic list styling properties. CSS classes can also be added to achieve any styling not immediately available in the styling dialog. Similarly the List Item Control can be styled by the addition of CSS classes or via its styling dialog.

 

Displaying Dynamic Content as a List

A simple list of texts or hyperlinks based on a list model can be achieved using a List Control in combination with a List Text Control or a List Hyperlink Control. The List Control requires a list model to supply the list items and there are three options (these are the same as described for input fields above):

 

 

// create simple list with three entries

var list1 = ["Line 1", "Line 2", "Line 3"];

controls.myList1.createCustomList(list1);

 

When one of these lists is used as the list model for a List Control, only the displayed value of each list item is displayed; the return value is ignored.

 

When you first drag a List Control onto a page, three controls including a List Text Control are added – this List Text Control displays the list item text for the current row of the list.

 

 

When the page is displayed, the List Item Control is rendered repeatedly for each item in the list. So if we now configure a Static List in the List Control’s properties:

 

 

The list is now displayed like this:

 

 

To display this as hyperlinks instead of texts, remove the List Text Control and replace it with a List Hyperlink Control:

 

 

The list is now displayed like this:

 

 

Here is the same list, now styled as a Bootstrap Nav menu:

 

 

To process the user clicking on the hyperlink, add a script to the List Hyperlink Control’s on click event. You can then check which item has been clicked:

 

var sel = controls.LisHyp1.text.text;

switch (sel)

{

case "US Dollar":

          log("User clicked US Dollar");

          break;      

      case "Euro":

          log("User clicked Euro");

          break;

      case "GB Pound":

          log("User clicked GB Pound");

          break;

}

 

To style the List Control, select it then click Control Style to display its styling dialog. This allows configuration of the list type (unordered or ordered list), the list style type (configures the bullet or number style) and a few other basic list styling properties. CSS classes can also be added to achieve any styling not immediately available in the styling dialog. Similarly the List Item Control can be styled by the addition of CSS classes or via its styling dialog. A List Text Control just represents the list item text and cannot itself be styled; style the list text by styling its parent List Text Item. A List Hyperlink Control can be styled in the same way as a Hyperlink Control.

 

It’s also possible to change the style of individual list items by looping through the list and setting properties on any of the child controls. For example:

 

var items = controls.LstvIn9L.list.items;

while (items.next())

{

      var txt = items.listValue

      switch (txt)

      {

            case "US Dollar":

                controls.ListItem1.backgroundColor = "red";

                break;      

            case "Euro":

                controls.ListItem1.backgroundColor = "green";

                break;

            case "GB Pound":

                controls.ListItem1.backgroundColor = "yellow";

                break;

      }

}

 

The list is now displayed like this:

 

 

This approach can be extended to make any dynamic change to the display of a list e.g. to hide or show individual entries.

 

 

Advanced Dynamic Content

The previous section Displaying Dynamic Content describes displaying a simple list as a list of text or hyperlinks. This works well but is limited in terms of the number of display options variable. For more advanced requirements you can use a Repeater List Control. This uses a table as a model (whereas the List Control uses a list model) and this means that any number of variables are available within each row (instead of just one). A Repeater List Control is essentially the same as a Repeater Control with the following differences:

 

 

A  Repeater List Control can contain any other controls as children and therefore offers unlimited flexibility in terms of layout

 

This control could be used to display a card layout where the content is dynamic, or any other dynamic content that needs to be rendered as a list using <ul> and <li> tags.

 

List Layout

The List Layout is available as a layout for any container control and lays out child controls within an unordered list/ordered list plus list items. This layout is used by the Repeater List Control.