listObj.addTableRow Method

IN THIS PAGE

Adding Multiple Rows to a Table for Lists Persisted to the File System
- Temporarily Suspending List Persistence in a Loop
- Adding Multiple List Rows using addTableRowsBulk()

Syntax

listObj.addTableRow(data [,options]);

Arguments

dataJSON Object

An object with the values in the List that you want to set.

optionsJSON Object

An object with optional settings. The options object can contain these properties:

setFocusToTargetRowboolean: true/false - If true, then focus will be given to the target row. The default for this property is false.
insertRowboolean: true/false -- Default false. Set to true if you want to insert at a specified position in the List rather than at the end. (Requires build 4444 or above)
insertPositionnumberstring: If options.insertRow is true, specify where in the List the new row should be inserted. options.insertPosition can either be a number or a string. If it is a number, it represents a zero based row number in the List where the new record will be inserted. If it is a string it represents the List value where the new row will be inserted.

Description

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

Discussion

Adds a new row of data to a List that has a Detail View. By default, the new row is added at the end of the List, but you can add the new row (i.e. insert the row) at any position by setting options.

//create a data object with values for the columns in the List you want to edit
var data = {};
data.FIRSTNAME = 'Cecelia';
data.LASTNAME = 'Longwood';

//define optional settings
var ops = {};
ops.setFocusToTargetRow = true;

//get a pointer to the List control and then call the .addTableRow() method
var listObj = {dialog.object}.getControl('CUSTOMERLIST')

if (listObj ) {
    listObj.addTableRow(data,ops);

    //insert the new row at position 3 (zero based)
    var ops = {};
    ops.setFocusToTargetRow = true;
    ops.insertRow = true;
    ops.insertPosition = 3;
    listObj.addTableRow(data,ops);
}

Contrast the .addTableRow() method with the List object's .appendRows() method.

The .addTableRow() method is the programmatic equivalent of the user entering some values into the List Detail view controls and then clicking on the Save button to save their changes back to the List. When the user does this, the List becomes dirty and the edits that have been made to the list can be synchronized with the server.

The .appendRows() method is a low level method that adds the data to the List, but this method does not add the necessary information to the List to cause the List row that was added to become dirty. The new row cannot be synchronized with the server.

To programmatically update a table row see the .updateTableRow() method.

Adding Multiple Rows to a Table for Lists Persisted to the File System

You can use the addTableRow() method in a loop to add many new rows to a List quite quickly. Under certain circumstances, however, this can cause a problem.

The circumstances under which this could cause a problem are:

The List is set to persist to storage (so that the application can function offline)
The List storage is set to 'FileSystem'
The App is running in Cordova.

The reason that there is a potential problem under the above scenario is that writing to the File System in Cordova is an asynchronous operation. Each time the List is updated, the edits to the List are saved in files written to the File System. But since these write operations are asynchronous, it is possible (actually likely), that the write operation for the next record added to the List will be initiated before the write operation for the current record added to the List has completed, and so on. These overlapping write operations to the File System could corrupt the files used to store the List edits.

There are two ways to address this issue. One way is to use the addTableRowsBulk() method. Another approach is to temporarily suspend persisting the List while calling the addTableRow() method in a loop.

Temporarily Suspending List Persistence in a Loop

If you want to write your own loop to add the rows, you can temporarily suspend persisting the List while the addTableRow() method is being called in a loop. Once the loop has completed, turn the suspension off and persist the List to storage.

To suspend persisting to the List, you set the List's .suspendPersist property to true.

To turn persisting back on, you set the List's .suspendPersist to false

To manually persist the List after you have turned suspend persist off use the List's persistToStorage() method. You must pass in an empty object when calling this method.

For example:

//persist multiple rows in a loop
var listObj = {dialog.object}.getControl('list1');

if (listObj) {
    //suspend list persisting
    listObj.suspendPersist = true;

    //execute the .addTableRow() method in a loop

    //turn list persisting back on
    listObj.suspendPersist = false;

    //persist the list (passing in an empty object to the .persistToStorage() method.
    listObj.persistToStorage({});
}

Using the .addTableRowsBulk() method (described below) is faster than calling the .addTableRow() method in a loop.

Adding Multiple List Rows using addTableRowsBulk()

The addTableRowsBulk() method can be used to add multiple rows to a List quickly. Using the .addTableRowsBulk() method is faster than calling the .addTableRow() method in a loop. To use this method, create a JSON array of rows to add to the List control. Then, call the addTableRowsBulk() method of the List object. For example:

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

if (listObj) {
    var dataArray = [];

    // code to build up an array of rows to add to the list
    // or uncomment example code below:
    // dataArray = [
    //    { FIRSTNAME: 'Cecelia', LASTNAME: 'DeLuca'},
    //    { FIRSTNAME: 'Cathy', LASTNAME: 'Marsh'}
    //]

    listObj.addTableRowsBulk(dataArray);
}

Limitations

List Control with Detail View Part