What is a DdsList?

Often, mobile applications express their data and options in the form of lists. While simple lists of items can be created with a subfile, many apps present feature-rich lists with descriptive text, thumbnail images, checkboxes, switches, and other interactive widgets. The DdsList Control can be used to create these more complex lists while still using a straightforward RPG Subfile on the IBM i.

Applicability: The Navigation ListType is exclusive to Mobile RPG; all other features of the DdsList are available in both Mobile RPG and Wings.

Each DdsList draws its data from a subfile (defined by the SubfileName property) on the IBM i. Each record on the RPG subfile represents an item that will appear on the DdsList.

Each record of the RPG subfile contains at least two mandatory fields:

  1. A text field: Which holds the text that will be displayed in the list item (defined by the TextField property)
  2. A selection field: Which determines whether the item is selected or not (defined by the SelectedField property)

The selection field can have a value of either "1" or "0" with "1" indicating that the field is selected. This value can be set for each record by the programmer. The User can also change the item selection (usually just by tapping on it) and the changes will be reflected in the RPG subfile as the selection field value changes to "0" or "1".

The Four List Styles

The DdsList lets the programmer set the the overall style of the list set at design time (via the ListType property). DdsLists can take any of the following forms:

  • Checkbox list - Consisting of one or more items accompanied by checkboxes.
  • Radio button list - Consisting of one or more items accompanied by radio buttons, only one of which can be selected at a time.
  • Dropdown list - Consisting of one or more items presented in a low-profile list that must be dropped down to be selected.
  • Navigation list - Consisting of one or more items presented with a wider variety of mobile-friendly options.

In the Navigation ListType, up to five visible features can be added to each list entry: main Text, Detail text, an Image, a checkbox (or radio button), and a right-pointing chevron that indicates whether a field is Navigable. The default locations of these parts are detailed on the image of a navigable list below:

From left to right, a checkbox list, a radio button list, a dropdown list, and a navigation list.

The Mechanics of a DdsList

A DdsList, like most Monarch controls, must be placed inside of a DdsRecord. A DdsList has properties that define the RPG subfile, its record formats, its fields, and the subfile controller on which the RPG subfile depends.

On Output

When the DdsList is going to be shown, the RPG subfile must be populated with its data, by means of code similar to this:

SetOff										99 //To clear subfile record
WRITE   SubCTLR
SetOff										99
//Loop reading subfile reload
WRITE	Subfile
SetOff										99
WRITE	SubCTLR				
EXTFMT

On Input

As part of the definition of DdsList the a field in the subfile is used to tell the program when the user has selected a record. As noted in the introduction, this field is defined by the SelectedField property, and it can take a value of either "1" (selected) or "0" (not selected). The value can be set by the programmatically or swtiched by the user (the user taps an empty checkbox or radio button, and it's filled, or vice versa). If altered by the user, the change will then be communicated back to the IBM i when the page is submitted.

Using Checkbox Lists

Lists featuring checkboxes allow the deliberate and simultaneous selection of several options. This can come in handy whenever the user is adjusting multiple options, or making selections before submitting the information to the RPG Program. They generally only have Text elements.

Note that ReadC only looks for the most recent changes to the underlying subfile. In the case of Checkboxes, the program will fail to pick up previous selections on subsequent loops. So if item 2 is changed after item 1, ReadC will only detect item 2.

Using Radio Button Lists

Lists featuring radio buttons allow for the exclusive selection of a single option. Selecting another list item will immediately de-select the first option.

Using Dropdown Lists

Dropdowns are perhaps the simplest type of lists: they only hold text, and tapping on them generally causes something (navigation, turning something on or off) to happen immediately.

Using Navigation Lists

Navigation lists represent the most complex and modern-looking lists that the DdsList control can create. In the Navigation ListType, up to five visible features can be added to each list entry: main Text, Detail text, an Image, a checkbox (or radio button), and a right-pointing chevron that indicates whether a field is Navigable. The default locations of these parts are detailed on the image of a navigable list below:

DdsList Property Tasks

The following list details the properties most essential to creating, populating, and styling a DdsList. They can all be changed in the Property Window.

Property

Notes

Appearance

ChevronIconID ID of the Icon that will be used as a chevron.
DetailAlignment Sets the Alignment of the Detail within the list.

Behavior

ListType An enumeration the sets the type of the list: Checkbox, Dropdown, Listbox, Radio, or Navigation
SelectChevronKey Sets the AidKey pressed when a chevron is selected by a user.
SelectItemKey Sets the AidKey pressed when a list item is selected by a user.

Data

CategoryField & CategoryFieldLength These properties define a character field whose runtime value is used to get the text content of the Category.
ClearIndicator Sets the clear indicator for the list's underlying subfile.
DetailField & DetailFieldLength These properties define a character field whose runtime value is used to get the text content of the Detail area.
NavigableField This property defines a character field whose runtime value is used to set the value for the address to navigate to when a list item or chevron is tapped. The special value *TRUE is used to indicate that all items should be navigable.
ProtectValueField Protect Value from user input Field Name or Indicator Number.
SelectedField Displays whether the record is selected (charfield).
SubfileControlName The name of the subfile control record format used for the list data.
SubfileName The name of the subfile record format used for the list data.
TextField & TextFieldLength These properties define a character field whose runtime value is used to get the text content of the Text area.
ValueField & ValueFieldLength These properties define hidden fields that may contain data the program will need.

Image

IconID ID of the Icon that will be used as a list-item image.
ImageDirectory Sets a character field whose runtime value is used as the path to the directory holding the image file.
ImageName Sets a character field whose runtime value is used to get the name of the image file.
ImageLocation Sets the location of the image within the list.

The NavigableField property is a special case: It defines a field, setting it to a value, for instance 'DRILL' indicates the request to define a field called 'DRILL', the program can then set the value of the field 'DRILL' to '1' before adding a record to the subfile, indicating that the user will be able to tap on that record, setting 'DRILL' to '0' before adding the subfile record would prevent the user from tapping on it. If all the list items are going to be navigable, do not specify the NavigableField property at all, or set it to the special value '*True'.

If all the list items are going to be navigable, do not specify this property at all, or set it to the special value '*True'.

The List Types

The ListType property determines the impact of several other properties, as the Navigation list type in particular has several features not available in the other formats:

ListType

Navigation

Checkbox

Dropdown

Radiobutton

CssClass YesYes YesYes
CssClassList YesYesYesYes
CssClassDetail YesNoNoNo
CssClassImage YesYesNoYes
CssClassChevron YesNoNoNo
SubfileControlName YesYes Yes Yes
SubfileName YesYes YesYes
SelectedField Yes YesYes Yes
SelectChevronKey YesNo NoNo
SelectItemKey Yes Yes YesYes
Categorized YesYes YesYes
CategoryField & CategoryFieldLength YesYes YesYes
TextField & TextFieldLength YesYes YesYes
DetailField & DetailFieldLength YesNoNoNo
DetailAlignmnet YesNoNoNo
ImageLocation Yes YesNoYes
ImageDirectoryField & ImageDirectoryFieldLength YesYes NoYes
ImageNameField & ImageNameFiedLength YesYes NoYes
ValueField Yes YesYesYes
NavigableField & NavigableFieldLength YesNo NoNo
SortCategory Yes YesYesYes
SortItems Yes YesYesYes