List Object Methods


Methods and properties available for interacting with a List Control object.


To get a list object, use the {dialog.object}.getControl method:

var listObj = {dialog.object}.getControl('LIST1');

Base Class Methods

The List Control object inherits methods and properties from the A5.ListBox Class. These methods are listed below. A large number of properties are available, as well. For a complete listing of properties, see the A5.ListBox Class documentation.


appendRows Method

Append new data to the end of the list.

destroy Method

Destroy the list. This method should be called before the list is removed from the DOM.

getColumnarHTML Method

Generate columnar HTML base off the current layout of the list.

getData Method

Get the data for a given row in the list.

getIndex Method

Get the indexes of row(s) in the list.

indexFromElement Method

Get the index of the list row that contains the passed in element.

indexFromEvent Method

Get the index of the list row an event occurred on.

indexFromPoint Method

Get the index of the list row matching the passed in coordinates.

indexVisible Method

Get the first and last indexes currently visible in the list.

insertRows Method

Insert new data into the list.

navigate Method

Navigate the list selection.

populate Method

Populate the list with new data.

refresh Method

Refresh the list.

removeRows Method

Remove rows from the list.

resize Method

Resize the list.

scrollToItem Method

Scroll to a target row in the list.

setColumnOrderImage Method

Set the sort icon on a given column.

setDisabled Method

Disable or enable the list.

setDisplay Method

Show or hide parts of the list. The list will automatically be resized if needed.

setFilter Method

Filter the list data.

setLayout Method

Change the currently used layout.

setLock Method

Lock the list to prevent user interaction.

setOrder Method

Order the rows in the list.

setValue Method

Set the value in the list.

updateRow Method

Update a row in the list.

valueInList Method

Check whether a value is rendered in the list.

Additional Methods & Properties

If a List has a Detail View or a Search Part, additional properties and methods may be available. These methods are dynamically added to the List Control at runtime.

listObj._deselectAll Method

Unselects all rows in the List control.

listObj._selectAll Method

Selects all rows in a List configured to allow multiple row selection.

listObj.filterListClientSide Method

Performs a client-side search on the data in the List and displays all rows that have the searchFor value in any column in the List.

listObj.getAllErrors Method

Returns all errors that occurred when synchronizing a List.

listObj.indexFromValue Method

Returns the zero-based row number for a given row 'value'. If the value is not found, -1 is returned.

listObj.listIsDirty Method

Returns whether or not the List has unsynchronzed edits (eg, is dirty.)

listObj.rowExpander Method

Toggle display of a List item footer.

listObj.scrollToClosestValue Method

Scrolls the closet record into view in the List.

listObj.setListSize Method

Sets the height and width of the List control.

listObj.setOrder Method

Sort the List client-side.

listObj.setValue Method

Set the value of the List.

listObj.showHideColumn Method

Show or hide a column in a List.



Used to temporary suspend persisting List data to Local Storage or the File System. Only applies to Lists with Persist data to Local Storage (or Filesystem) enabled. See listObj.addTableRow Method for additional information.


_clearServerSideErrors Method

Used internally. Clears error messages from the Detail View controls.

_debugListData Method

Shows the contents of the data object for the current row in the List. You must have specified a placeholder for the debug information.

_deleteOrphanMediaFiles Method

Deletes any orphan files that have been saved to the file system.

_fetchMediaFiles Method

Scans the List for the names of any files on remote servers, and then fetches the files, stores them in the mobile device file system and then replaces the data in the List to change references to remote files to local files.

_getControlsInDiv Method

Returns an array of all of the controls in the Detail View. Only controls that actually exit are returned. For example, say you specified that the Detail View is all of the controls in a container called 'CONTAINER_1' and one of the controls in this container is called 'SHIPPING_ADDRESS', but the List does not have a field called 'SHIPPING_ADDRESS'. The array of controls returned by this function will not include the 'SHIPPING_ADDRESS' control.

_getListFieldFromControl Method

Takes the name of a Detail View control and returns the field name in the List that the control is mapped to.

_getRoute Method

Returns an array of objects defining the currently selected rows for the List and all parent and child List controls.

_hasClientSideError Method

Returns true if any control in the List Detail View has a client-side validation error.

_logicalRow2PhysicalRow Method

Takes the logical row number (the value of the *key property in the data object - also the same as the row number in the data when it is loaded - before any client side sorting/filtering) and converts to a physical row number in the current sorted/filtered client side view of the data.

_setRoute Method

For use with Lists that contain hierarchical data. Sets the selected row on each List in the routeArray.

_showServerSideErrors Method

Used internally. Paints error messages on the Detail View controls using information stored in the List data .serverSideErrors object.

addTableRow Method

Adds a row of data to a List with a Detail View.

addTableRowsBulk Method

Adds multiple rows to a List control.

clearSearchList Method

Removes any filter previously applied by submitting the Search Part.

deleteRow Method

Marks the current row in the List as deleted. The row is not physically removed from the List until the data are synchronized. If the current row is a new record, then the row is immediately removed from the List.

deselectAll Method

Deselects all rows in the List control.

detailViewIsDirty Method

Returns true/false if the controls that show the Detail View are dirty or not.

disableDetailView Method

Enable or disable all of the controls in the Detail View.

fieldIsDirty Method

Returns true if the specified field is dirty. If the rowNumber is not passed in the currently selected row is used. For new records, the field is considered dirty if it is not blank.

harvestListRow Method

Gets a JSON object of the data in the row. If row is an existing row, the object includes an _oldData object with the original values in the row. If the optional row number is not passed in, the current row is harvested.

listRowIsDirty Method

Returns true if the current row in the List is dirty. You can optionally specify a zero based row number.

listRowIsNew Method

Returns true if the current row in the List is a new row. You can optionally specify a zero based row number.

newDetailViewRecord Method

Sets all of the controls in the List Detail view to their 'new record' value and deselects the current row in the List.

persistToStorage Method

Manually persists data in a List control to Local Storage or the device's File System.

populateUXControls Method

Populates UX controls with data from the List. This method is internal - it is called automatically when the onSelect event fires if the List has a Detail View.

queryByFormClearControls Method

Removes the search criteria from the Detail View form when the List is in 'search' mode.

resetForm Method

Resets the Detail View form.

resetRow Method

Resets a List row that has been edited to its original values. If the row has been marked as deleted, then 'un-deletes' the row.

searchList Method

Submits the Search Part to search the List. You can specify if the search should be performed client-side, server-side or 'auto'.

searchModeOff Method

If the List Search Part is set to 'QueryByForm' then turns search mode off.

searchModeOn Method

If the List Search Part is set to 'QueryByForm' then turns search mode on.

setRowClean Method

Sets the row state to clear. If row num is not specified, current row.

setServerSideError Method

Used internally to put information about server side errors into the List's data object.

updateListFromUXControls Method

Updates the data in the List with edits made in the List's Detail View controls.

updateTableRow Method

Updates data in a row in a List that has a Detail View.