Events

An event occurs on the server whenever your app's UI or client-side scripts access or modify data. Server-side scripts don't trigger events, even when loading or saving records. These are data events, not widget events.

Events trigger permissions checks and can execute server-side scripts.

Requests or modifications to multiple records trigger one event for each record affected. For example, the onAfterLoad event triggers for each record returned to the client.

Event types

Name Description
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.

Events and exceptions

When an event occurs, App Maker checks relevant model and relation permissions and executes the event's script, if you've written one. If the permission check fails or the script throws an exception, App Maker cancels the event and returns an error to the client. Canceling an onAfterLoad event prevents the server from returning a record. Cancelling the other events prevents modifications to the database.

Event Scripts

Add event scripts to the Events tab of the model editor. Event scripts have access to a record variable, which represents the record that triggered the event.

Take care when invoking expensive operations in event scripts, such as executing queries or saving records. Many client actions operate on multiple records at once, so your script is likely to run more than once. Try caching to improve your code's performance.

Here are some examples of how to use event scripts for different event types:

onAfterLoad example

You can use onAfterLoad events to track who accesses a record. This example tracks the last person who viewed a 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. This example initializes 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. This example sends 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. This example throws an exception if two record field values are equal:

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. This example sends an email message when the app updates an existing record.

console.log("This is a new name: " + record.name);
sendEmail('anndroyd@mixateria.org', 'onAfterSave', record.name);

onBeforeDelete example

You can use onBeforeDelete events to 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. This example records an event in the console long when the app deletes a record.

console.log("the deleted record name is " + record.name);
var rec = app.models.ArchivedEmp.newRecord();
rec.name = record.name;
app.saveRecords([rec]);
console.log("SAVED");