Events

A data event is triggered when the app's UI or client-side scripts (but not server scripts) access or modify data through a datasource. Events also trigger the app to check access permissions. You can enter a client script to run when a data event occurs, such as to email an administrator when a user updates or deletes a record. Data events are separate from widget events.

When you use a data event to trigger a client script, consider the following:

  • The client script can execute server-side scripts that access or modify data. However, server-side scripts don't trigger data events or permission checks because they work with data through models instead of datasources. For server scripts, you must write your own success action and security in the script.

  • Requests or modifications to multiple records trigger an event for each record. For example, the onAfterLoad event is triggered for each record returned to the client.

  • Take care when you invoke expensive operations in event scripts, such as running queries or saving records. Client actions often operate on multiple records at once, so your script is likely to run more than once. To improve your code's performance, try to cache information.

Add an event script

  1. In App Maker, in the left navigation, click the model that you want to add an event to.
  2. Go to the Events tab.
  3. Click the event type that you want to add.

    Data event types
    onAfterLoad An event that occurs before the server returns a record.
    onBeforeCreate An event that occurs after the client creates a record, but before it's saved to the database.
    onAfterCreate An event that occurs after the client creates a record and the server saves it to the database, but before the change is loaded by the client.
    onBeforeSave An event that occurs after the client applies changes to a record, but before it's saved to the database.
    onAfterSave An event that occurs after the client makes a change and the servers saves it to the database, but before the change is loaded by the client.
    onBeforeDelete An event that occurs after the client requests deletion of a record, but before it's deleted from the database.
    onAfterDelete An event that occurs after the client requests the server to delete a record from the database but before the deletion is loaded by the client.

  4. Enter your script in the code editor. You can use the record variable, which represents the record that triggered the event. The following sections provide examples of event scripts.

Event exceptions

When an event occurs, App Maker checks relevant model and relation permissions and executes the event's script. If the permission check fails or the script throws an exception, App Maker cancels the event and returns an error to the client. When an onAfterLoad event is cancelled, the server doesn't return the record. When other events are cancelled, the database is not modified.

Event script examples

onAfterLoad example

You can use onAfterLoad events to track who accesses a record. For example, save the current user's email address in a LastVisitor value of the record:

var userEmail = Session.getActiveUser().getEmail();
record.LastVisitor = userEmail;
app.saveRecords([record]);

onBeforeCreate example

You can use onBeforeCreate events to initialize records with values computed on the server. For example, initialize a new record with its creation date:

 record.TimeCreated = new Date();

onAfterCreate example

You can use onAfterCreate events to perform actions after a new record is saved to the database. For example, send an email message with details of the new record:

var body = 'record: { key:' + record._key + ',name:' + record.name + '}';
console.log('record key is ' + record._key);
sendEmail('anndroyd@mixateria.org', 'OnAfterCreate', body);

onBeforeSave example

You can use onBeforeSave events to validate state in your record or to track when it was last modified. For example, return an error when two record field values match:

if (record.ValueOne === record.ValueTwo) {
  throw new Error("valueOne and valueTwo can't be equal");
}

onAfterSave example

You can use onAfterSave events to perform actions after an existing record is changed. For example, send an email message when the app updates a record:

if (record.CcEmailAddress) {
  sendEmail(record.CcEmailAddress, 'Ticket ' + record.Name + ' was updated', 'Please review the change');
}

onBeforeDelete example

You can use onBeforeDelete events to perform actions before a record is deleted. For example, store a backup of the record in another record of a different model:

var backupRecord = app.models.BackupRecords.newRecord();
backupRecord.Name = record.Name;
app.saveRecords([backupRecord]);

onAfterDelete example

You can use onAfterDelete events to perform actions after a record is deleted. For example, record the deletion event in an audit log when the app deletes a record:

var auditRecord = app.models.AuditLog.newRecord();
auditRecord.Message = 'Ticket ' + record.Name + ' was deleted by ' + Session.getEffectiveUser().getEmail();
app.saveRecords([auditRecord]);