JavaScript

{dialog.object}.saveListEdits Method

Syntax

{dialog.object}.saveListEdits(listId [,options]);

Arguments

listId

A key for saved data entered into the repository.

optionsjson object

A JSON object specifying optional parameters. Available options include:

rowsnumberstringnumber array

The rows to submit. Can explicitly define as number or array of numbers to submit specific rows. Use the string 'current' to specify only the current row should be submitted. Use the string 'allRows' to submit all rows.

batchSizenumber

Overrides the batch size property for the List control. Specifies the number of records to submit when data is synchronized using batches.

allChildRecordsboolean

Default = false. By default, if a List has a child List, only the dirty child records are submitted when data is submitted. If this flag is set to true, then all child records (dirty and not dirty) are submitted to the server.

allParentListsboolean

Can be true or false. If true, parent records will be submitted for a List control that has a parent List.

resetMediaFileUploadErrorsboolean

Can be true or false. If true, file upload media errors will be reset. For PhoneGap applications with media files.

checkForMediaFilesboolean

If true, new or updated media files will be synchronized. For PhoneGap applications with media files.

fixMediaFileReferencesboolean

Flag fix media file references. For PhoneGap applications with media files.

pullSyncboolean

Flag that the list should do a pull sync every time a push sync is done.

ajaxobject

Settings for adding custom handling when the sync fails because the device is offline or the server is unresponsive (does not respond before the request times out.) Settings include:

timeoutnumber

Duration of the timeout before the request is considered to have failed.

onAjaxFailfunction

Javascript function to call if the Ajax callback fails (for example, if the server took longer to respond than the length of the timeout.

onDeviceOfflinefunction

Javascript function to call if the device is offline.

Description

Synchronizes edits that have been made to the List (and any of its child Lists).

Discussion

Synchronizes edits that have been made to the List (and any of its child Lists). By default, edits from all dirty rows in the List are submitted to the server. You can optionally specify that just the edits for the currently selected row, or a specified list of rows, should be submitted to the server. You do this by passing in {rows: 'current'} (for just the current or), or {rows: [rowNumber1, rowNumber2, rowNumber3,...] } (for an explicit set of row numbers) in the optional options parameter.

If the List is based on a SQL data source, the data are automatically saved to the table(s) on which the List is based. Alpha Anywhere automatically generates the necessary SQL CRUD statements from the submitted data.

If the List is not based on a SQL data source (for example the Data Source property of the List is set to 'Custom', 'Static', 'Javascript', etc.), then you must write your own synchronization handler to persist the submitted data.

When you submit multiple dirty rows of data you can choose to submit all rows at once, or you can submit data in batches. The batch size can be specified in the List properties, or you can override the setting in List properties by specifying an option in the JSON options passed in as the second parameter to the method. For example:

{dialog.object}.saveListEdits('LISTCUSTOMERS',{rows: 'allRows', batchSize: 10});

When you submit data in batches, the first batch is submitted, then once that batch is synchronized a subsequent callback is triggered to submit the next batch, and so on, until all of the dirty rows have been submitted. The user can cancel before all batches have been submitted. If the user does cancel, the current batch that is being processed will continue to process, but once this batch completes, no further batches will be sent to the server.

Behind the scenes, this method does this:

  1. Calls the List's .harvestList() method to get all of the dirty data to submit to the server

  2. Makes an Ajax callback and submits the List data

  3. Performs server-side validation of the submitted data.

  4. If server-side errors are found, compute the necessary Javascript to return information about the errors to the List so that the Detail View controls can be decorated with the appropriate error messages.

  5. If any write conflicts were found on the server (because another user had edited any of the records that were edited in the List), compute the necessary Javascript to return information about the conflicts to the user so that she may resolve them.

  6. Computes an Ajax response to refresh the rows in the List that were updated and remove the 'dirty' flags from List rows that were previously marked as 'dirty'.

When the List edits are pushed to the server, you can optionally specify that any edits that were made on the server (presumably, by other users) should be pushed back to the List.

When you configure the List control you can set the synchronization policy to control whether 'server-to-client' synching should take place.

Since 'server-to-client' synching is a more expensive operation than 'client-to-server' synching, you might want to turn this option off and instead provide a menu choice to the client to explicitly do a 'server-to-client' synch. To do an explicit 'server-to-client' synch, you can all this method:

{dialog.object}.refreshListData(listId, {mode: 'incremental'});
When you specify the 'incremental' mode any rows in the List that are dirty will not be refreshed.

 Synchronizing Data Using pullSync

The synchronization policy for the List can be set to always do a pull sync after pushing data to the server. While this guarantees that any new changes to the data on the server will be downloaded after the client synchronizes local changes, it may not be desireable to always do a pull sync after doing a push. The pullSync property can be used to optionally download changes from the server after local changes have been synchronized. If pullSync is true, a pull sync will be performed regardless of the synchronization policy set in the List control. This lets you pull the latest changes from the server when necessary.

{dialog.object}.saveListEdits('LIST',{rows: 'allRows', pullSync: true});

 Example: Setting Request Timeouts and Custom Error Handlers

{dialog.object}.saveListEdits('listName',
{
    rows: 'all' or 'current',
    ajax: {
        timeOut: 15000,
        onAjaxFail: function() { alert('Server could not be reached.'); } ,
        onDeviceOffline: function() { alert('Device is offline.'); }
        }
    });

See Also