Triggers: Difference between revisions

A Trigger is a script that defines the processing of an entry based on an Event that has taken place. Trigger scripts are written in [https://developer.mozilla.org/en-US/docs/web/JavaScript JavaScript]. When a trigger script is executed, it may change an existing entry, create a new entry, execute an http request, create a file, perform data validation, etc.

:; Event and Phase

:: One of a predefined set of moments (Event type & Phase) during entry processing during which the user can intervene via a trigger script. See the table of events below.<br/> The Event type and the Phase determine the trigger script to be run.

: implies the application suspends user interaction and then executes the script. It is not recommended to perform time-consuming operations in this case.

: results in the script running in the background; user interaction is not suspended. Usually, asynchronous scripts are used in the last phases of the action.

Each library can have a number of triggers &mdash; up to one for each Event. To see the list of triggers, open the library, open the menu, and then select ''Triggers''.

To create a trigger, open the library's list of triggers and click <big>'''+'''</big>. You must then identify the Event and write a trigger script that performs the necessary actions.

These are the defined ''Event types'', ''Phases'', and their corresponding moves of execution.

; Library permissions

; Read permissions

; Write permissions

: grants to the script the right to execute http requests

=== Global Library Functions ===

This script should be used for the Event '''Creating an entry''' or '''Updating an entry''' in the Phase '''Before saving the entry'''.

The script must be set for Event '''Creating an entry''' Phase '''Open the Entry Edit card for Add'''.

If you need to identify the beginning of a new day in the DateTime field, the script requires to connect the JavaScript library '''moment.js''' [http://momentjs.com/ moment.js].

The script must be set for Event '''Creating an entry''' and Phase '''Opening an Entry Edit card for Add'''.

With scripts you can read or write files located in the device's internal memory or on the SD card. All file operations are performed by the ''File'' object, which is obtained through a global function called ''file()''.

Open a file for read or write operations

This object is returned by the global function ''file()'' and provides access to the requested file. If the file with the specified name does not exist yet, it will be created. After reading or writing, the file should be closed using the method ''close()''.

====Save an entry into a file in XML format ====

Processing for HTTP requests allows integration between Memento and the system. All file operations use the Http object, which works through global function http().

# Script execution should be asynchronous, because processing of the request on the network can take a long time. Therefore, HTTP requests of the last Event phase.

# The library should have permission - Network.

:Execute get request

:Argument: url - HTTP address, starting with http or https

:Result: HttpResult - Object containing the result of the execution of the HTTP request.

=== Object HttpResult ===

;code : HTTP code of the response, if the request is successful (usually is 200).

;body : The response in text form

We will create a Trigger on Event '''Create Entry to Add''' and phaase '''After Saving Entry'''.

=== Global System Functions ===

:Shows the user a brief notifiction

:Argument: text &mdash; Text of the notification

: Stop the system operation that caused the event. Many triggers can be a result of entry manipulation (create, update, delete, etc). The cancel() function can be used during the phases that precede the system operation. For example, this function can be used during data validation before the entry is saved.

:Result: System object

: Argument: Text - text to be written to the log

: Result: Random string identifier

=== Object System ===

;os : Name of the operating system executing the script

=== Object Intent ===

: Argument:uri - URI referencing data to which the action will be applied. It can be contact ID, path to the file, phone number, etc.

: Argument:mime &mdash; MIME type of the data on which the operation will be performed

: Arguments: key and value

Suppose a library contains time and name of an appointment.