Event Handling Basics
Events are fired based on application events, actions performed by the user, and custom conditions handled by loaded plug-ins.
When an event is fired, DataSplice will execute a chain of actions as specified by the configuration to process the event. By default the chain consists of a single action that performs the basic function for the event. The Administration Client can be used to add additional actions when needed to specify custom business logic. These can be set up in two ways:
- Before and After the default action, with the additional actions handling validation and post conditions associated with the event.
- Instead of the default action, such that the other actions in the chain completely provide the functionality needed for the event.
For each event the steps taken by the Default Action are described below, since they are specific to the actual event in question. Additional actions before and after the default will be processed with that context in mind, and if the default action is removed from the chain or skipped because of the condition those steps will not be performed.
This may or may not make sense depending on the configuration. For instance, the default action for the update, insert, and delete events is very rarely called - typically the view will be configured to pass the modifications off to a separate business rule processing layer. However not calling the default action for the query events rarely makes sense because this will always result in an empty set of data.
Event Qualifiers
Certain events have an additional qualifier that further specifies when the specified actions should be fired. For instance, the qualifier for the Keypress event is the sequence that should fire the event, and the qualifier of the VerifyField event is the name of the field being modified.
If the event has no qualifier it can only have a single binding, and qualified events can have multiple bindings as long as the qualifier is different.
The qualifier for these events can be specified in a couple of ways:
- The explicit value to match
- A comma separated list to match multiple values
- A pattern (/regex/) to match values based on a regular expression
In cases where multiple bindings match a particular qualifier the applications will execute the most specific match.
Server-Side Events
The following events are processed by the server in order to integrate with the target data sources that are mapped to various views.
| Event Name |
Qualifier | Details |
|---|---|---|
| ServerQuery | none | Handles data queries on the server to request client queries from the associated backend data source. This is fired both when the user explicitly requests data, and when other actions (dynamic lists, query expressions) attempt to access data. Default Action: Sends query to server data source to be processed. |
| UpdateRecord | none | Commits records modified by the user to the backend data source. Note that this event is not fired when a user modifies a record on the client application, but rather when the modification is committed to the server by the user. Default Action: Requests server data source to update record. For instance, the ADO.NET data source will execute an UPDATE SQL statement to modify the data. |
| InsertRecord | none | Commits records that have been created on the client to the backend data source. Similar to the UpdateRecord event, this is fired when changes are committed to the server and not when records are created on the client. Default Action: Requests server data source to insert the new record. For instance, the ADO.NET data source will execute an INSERT SQL statement to create a new record in the associated table. |
| DeleteRecord | none | Commits records that have been marked for deletion to the backend data source. Similar to the UpdateRecord event, this is fired when changes are committed to the server and not when records are marked for deletion on the client. Default Action: Requests the server data source to delete the specified record. For instance, the ADO.NET data source will execute a DELETE SQL statement to delete the selected record. |
Client-Side Events
| Event Name |
Qualifier | Details |
|---|---|---|
| ClientQuery |
none |
Handles offline queries on the client to fetch locally stored data that matches a query. Default Action: Executes the query against the locally stored offline data. |
| CreateRecord |
none | Fired when the user creates a new record within a view, either by clicking the Create Record button, or by accessing an action that creates a new local record. Default Action: Creates the new record and applies any field defaults. |
| MarkForDelete |
none | Handles marking records to be deleted on the client. Default Action: Marks the record to be deleted, or in the case of inserted records it removes them from the data store. |
| VerifyRecord |
none | Fired when the user attempts to leave the currently selected record, either by selecting another record or moving to a different section of the client application. This allows the Remote Client to validate the data provided by the user and ensure that correct data has been entered. Default Action: Does nothing, though if this event fails the user is prevented from leaving the record. |
| VerifyField |
Field Name |
Processes new values for fields, either when explicitly edited by the user or when modified by other events and actions. This is typically used to validate the supplied value, and cascade changes to depended fields where needed. Default Action: Applies the new value to the record. |
| PerformAction |
Action Name |
Executes navigation actions to display related data and perform other configured actions within a view. Navigation Actions are covered in the Display Settings section of this document. Default Action: Performs the task specified by the associated action. |
| DefaultCommand |
Current Display Mode (filter/grid/record) |
Handles the default action for the view when the user presses the Enter key. This is used to reduce the amount of screen taps/mouse clicks needed to navigate through the configured views. For instance, this is often used to automatically display results for the current query after filling out values in the query editor. Default Action: Displays the menu in the navigation bar. |
| Keypress |
Keypress Sequence |
Handles keyboard input typed by the user. The qualifier can be a single key ( F1, Esc, Enter ) or a control sequence formatted like alt+<char>, ctrl+<char>, win+<char>. Default Action: Passes the character on to the selected control. |
| LogOut |
none |
Commits any pending modifications to the server and releases the current session. This is typically used to take actions before logging out. Default Action: Performs the log out operation with the server. |
| OfflineSync |
none |
Synchronizes data on the handheld by committing pending changes and updating the data available to the user. Overriding this can be used to prompt the user for information prior to a sync, or perform other data cleanup operations during the process. Default Action: Perfoms the offline synchronization operation. |
Plug-in Events
Plug-in modules are capable of registering an firing events. The available events can change depending on plug-ins that are installed.
| Event Name |
Disposition |
Qualifier | Details |
|---|---|---|---|
| BarcodeScan |
Client |
Scanned Data |
Called when the user successfully scans a bar code label. The scanned input is passed as the event qualifier, which allows bindings to use patterns to match the details of what the user scanned. As mentioned in the client configuration section, the desktop version of the scanner plug-in can be enabled to fire this event when a particular keypress sequence is typed, which allows the event processing the be tested on machines that don't have a scanner. This will display a prompt for the data that should be simulated in the scan event, and then fires the processing in the client. Default Action: Replaces the text in the current edit control with the scanned input. |
Miscellaneous Events
| Event Name |
Qualifier | Details |
|---|---|---|
| Custom |
Unique Event Identifier |
This event is never directly fired by the system, but can be used by administrators to create sets of functionality that are referenced by different elements in the configuration. These can be called from other events or navigation actions, and essentially create subroutines of functionality within a view. Default Action: Does nothing |
Last modified 2009-10-13 01:12 PM
