List Control Client-side Events
Description
Client-side events for the List can be utilized to perform additional tasks when an event, such as clicking a list row or creating a new record, occurs.
Discussion
The List control has numerous client-side events you can use to add your own custom behaviors. The events can be accessed using the List events button at the bottom of the List Builder or via the List Builder's Javascript - Render Time, Javascript - Run Time, or Detail View Events properties. Clicking the button or editing the properties opens the List Control System Events dialog, shown below.
The List Control System Events dialog divides events into two groups: List events and Detail View events. Detail View events only apply to a List with a Detail View. You can switch between the two types of events using the radio buttons above the event listing. To edit an event, select the event from the list and enter your JavaScript in the Javascript Code area to the right.
List Events
List events are triggered when interacting with the List.
Render Time Events
Render time events fire while the List is being rendered. These events can be used to change the HTML rendered for the List.
- Event
- Description
- onBeforeItemDraw
Fires before each row in the list is drawn.
- onBeforeListDraw
Fires before the list is drawn.
- onItemDraw
Fires when each row of data is drawn.
- onListDraw
Fires after the list has been drawn.
Run Time Events
Run time events fire during application execution, such as when the List control is first loaded or when the user clicks a row in the List.
- Event
- Description
- onInitialize
Fires after the list has been initialized.
- onBeforePopulate
Fires before the List is populated.
- onPopulate
Fires after the List has been populated.
- onBeforeAddRows
Fires when the .addRows() method is called before the rows are actually added.
- onBeforeRemoveRows
Fires when the .removeRows() method is called before the rows are actually removed.
- onBeforeUpdateRow
Fires when the .updateRow() method is called before the rows are actually updated.
- onAddRows
Fires after the .addRows() method is called.
- onRemoveRows
Fires after the .removeRows() method is called.
- onUpdateRow
Fires after the .updateRow() method is called.
- onSelect
Fires when a value in the List is set.
- onBeforeSelect
Fires before the onSelect event.
- afterSelect
Fires after the onSelect event.
- onDblClick
Fires when the user double clicks a row in the List.
- onClick
Fires when a row in the List is clicked or when the List has focus and the user hits the Enter key.
- onTap
Fires when the user taps a List row.
- onDblTap
Fires when the user double tapas a row in the List.
- onDownHold
Fires when the user holds down on a row in the List.
- onRightClick
Fires when the user right clicks a row in the List control.
- onFieldClick
Fires when the user clicks on a field in a row in the List.
- onFieldDblClick
Fires when the user double clicks on a field in a row in the List.
- onFieldRightClick
Fires when the user right clicks on a field in a row in the List.
- onFocus
Fires when the List gets focus.
- onBlur
Fires when the List loses focus.
- afterAjaxCallback
Fires after any Ajax callback (sort, refresh row, append row, etc.) has completed.
- beforeClientSideFilter
Fires before a client-side filter is applied to the List. If the function returns false, the filter is not applied.
- afterClientSideFilter
Fires after a client-side filter has been applied to the List.
- beforeClientSideSort
Fires before a client-side sort is applied to the List data (by tapping on a column heading in a tabular List layout). If the event returns false, the List is not ordered.
- afterClientSideSort
Fires after a client-side sort is applied to the List data.
- beforeServerSideSort
Fires before the user tries to do a server-side sort action by clicking on a column heading.
- afterServerSideSort
Fires after the user does a server-side sort action by clicking on a column heading. Direction is 'a' or 'd'.
- onSwipe
Fires when the user swipes (left, right, up or down) on a row in the List.
- onScroll
Fires when the List is scrolled.
- onPullRelease
Fires when the user 'pulls' the List beyond an end point (i.e. top, bottom, left or right edge) of the List and then releases while the List is in a 'pulled' state (allowing the List to animate back to its natural position).
- onPull
Fires repeatedly while the user is 'pulling' the List beyond an end point (i.e. top, bottom, left or right edge) of the List.
- onPullEnd
Fires after the user has started 'pulling' a List beyond an end point, when the user restores the List to its 'non-pulled' state.
- onNavigate
Fires when after List has been navigated (i.e. scrolled).
- afterSearchComplete
Fires after the user submits the List's Search Part to execute a search of the records in the List.
- beforeSearch
Fires before the user submits the List's Search Part to execute a search of the records in the List.
- onSearchResultTooLarge
Fires if the user executes a server-side search that returns too many records.
- onSearchResultTooLargeForLocalStorage
Fires if a server-side search returns more data than the List control is configured to download.
- onBeforePersistToLocalStorage
Fires before the List is persisted to Local Storage.
- onPersistToLocalStorage
Fires after the List is persisted to Local Storage.
- onRestoreFromLocalStorage
Fires after the List data has been restored from Local Storage.
- onListReady
Fires after the List is ready and has been populated.
- localStorageEncryption
Fires before data are written to Local Storage.
- localStorageDecryption
Fires after data are read from Local Storage.
- afterRenderComplete
Fires after the List has been completely rendered.
- beforeFetchMore
Fires before an Ajax callback to fetch more records.
- afterFetchMore
Fires after an Ajax callback to fetch more records has completed.
- beforePageNavigate
Fires before an Ajax callback to navigate to a different page of records.
- afterPageNavigate
Fires after an Ajax callback to navigate to a new page of records has completed.
- beforeRefreshRow
Fires before an Ajax callback to refresh the current row in the List.
- afterRefreshRow
Fires after an Ajax callback to refresh the current row in the List has completed.
- afterServerSideSummaryCompute
Fires after the server-side summary values have been computed.
- afterClientSideSummaryCompute
Fires after the client-side summary values have been computed.
- onBeforeListClear
Fires before the lst data is cleared.
- onFocusOut
Fires when the List or any element in the List looses focus.
- onListColumnSelectorChanged
Fires after the user has made a selection in the List Columns Show/hide control. You can use this event to persist the List state.
- onResize
Fires when the List is resized.
- onRowCheck
Fires when a row is checked or unchecked in a List configured to display a checkbox selector column.
Detail View Events
Detail View events are triggered when interacting with the Detail View for the List. Detail View events are only available if the List has a detail view.
- Event
- Description
- afterCancelBatch
If the List is being synchronized in batches, fires after the user has clicked the 'Cancel' button to stop sending batches of records to the server to synchronize.
- afterDeleteOrphanMediaFiles
Fires after orphaned media files have been deleted.
- afterDeleteRow
Fires after the user has deleted a row in a List.
- afterDetailViewPopulate
Fires after the user has selected a row in a List and the List's Detail View has been populated.
- afterListRowSelectCancelled
Detail View for the orderDetail List is in another Panel, this event can give focus to the Panel so that the user can save the dirty Detail View record.
- afterMediaFilesDownloaded
Fires after media files have been downloaded.
- afterMediaFilesUploaded
Fires after all media files (photos, video, audio recordings) have been uploaded to the server, or Amazon S3 when data are synchronized.
- afterNewRecord
Fires after the new record has been displayed in the DetailView form.
- afterRefreshListIncremental
Fires after an incremental List refresh completes.
- afterResetRow
Fires after the user has undone edits to a row of data in the List.
- afterSynchronizeList
Fires after the data in the List has been synchronized.
- afterSynchronizeListBatch
If the List is being synchronized in batches, fires when a batch is completed. If the function returns false, the next batch (if any) will not be sent. The data in the e object that is passed in will allow you to create your own progress counter. The countObject parameter in the e object has statistics on the current batch (e.g. number of records with errors, etc.) To see all of the properties in e.countObject you can add this to your code: alert(JSON.stringify(e.countObject)).
- afterSynchronizeListBatchEnd
If the List is being synchronized in batches, fires after the last batch has completed. A possible use case for this event is to allow you to close a window you might have opened to show the synchronization progress. The countObject parameter in the e object has statistics on the current batch (e.g. number of records with errors, etc.) To see all of the properties in e.countObject you can add this to your code: alert(JSON.stringify(e.countObject)).
- afterUndoEdits
Fires after the user has undone edits to the List Detail View.
- afterUpdateList
Fires after the user updates the List with edits that have been made to the List Detail View.
- beforeCRUDExecute
Fires before a SQL statement that is part of a List sync operation is executed.
- beforeDeleteOrphanMediaFiles
Fires before any orphaned media files are deleted from the local file system on the device.
- beforeDetailViewPopulate
Fires after the user has selected a row in a List, but before the List's Detail View is populated.
- beforeMediaFilesDownloaded
Fires before media files are downloaded.
- beforeMediaFilesUploaded
Fires before any media files (photos, video, audio recordings) are uploaded to the server, or Amazon S3 when data are synchronized.
- beforeSynchronizeListBatchStart
If the List is being synchronized in batches, fires before the first batch is submitted. The purpose of this event is to allow you to open a window or set focus to a panel where the synchronization progress will be shown.
- canCancelBatch
If the List is being synchronized in batches, fires if the user clicks the 'Cancel' button to stop sending batches of records to the server to synchronize. If the function returns false, then the synchronization is not cancelled.
- canDeleteRow
Fires when the user tries to delete a row of data in the List. If function returns false, action is cancelled.
- canNewRecord
Fires when the user tries to go to a new Detail View record. If the function returns false, action is cancelled.
- canResetRow
Fires when the user tries to undo edits to a row of data in the List. If function returns false, action is cancelled.
- canSynchronizeList
Fires when the user tries to synchronize the data in the List (by making an Ajax callback). If the function returns false, the action is cancelled. The data object is passed in as a member of the e object. If you set properties in e.data, you can override the values from the List that will be submitted to the server. If you set the e.data[rowNumber]._isDirty property of a particular row to false, then the data in that row will not be synchronized. The e object that is passed in includes batchSize, totalDirtyRows, and startingRow. If all of the data is not being submitted in batches, then the batch size is 0. To test if this is the first batch in a job test for batchSize > 0 and startingRow = 1.
- canUndoEdits
Fires when the user tries to undo edits to the List Detail View form. If function returns false, action is cancelled.
- canUpdateList
Fires when the user tries to update the List with edits that have been made to the List Detail View. If function returns false, action is cancelled. The data object is passed in as a member of the e.object. If you set properties in e.data, you can override the values that the user entered.
- hasClientSideValidationErrors
The 'hasClientSideValidationErrors' event fires when the user tries to save Detail View edits back to the List and one or more controls in the Detail View has a client-side validation error.
- listReadyToPersist
Fires when the list is ready to persist to storage.
- modeChanged
Fires when the Detail View mode changes. The possible states of the 'mode' flag are: 'edit', 'enter' and 'search'.
- onMediaFilesUploadErrors
Fires if there were any errors when uploading media files.
- onNoMediaFilesToFetch
Fires when there are no media files to download.
Custom Events
You can add your own custom events using Template Items. Template Items are added to the List layout and support a variety of events, including click, double click, right click, mouse down, and mouse up. See Template Items to learn more.
