Triggers: Difference between revisions

From Memento Database Wiki
Jump to navigation Jump to search
mNo edit summary
 
(357 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Stamp|2016-10-02|4.0.0|1.0.5}}
{{Stamp|2023-08-12|5.0|2.0}}
{{BannerMenu}}
{{PageTitle|Triggers}}


'''''[[This page is incomplete, incorrect, in the midst of translation, and under development.]]'''''
A '''''Trigger''''' is a script that defines the processing of an entry whenever a particular kind of event takes place. Trigger scripts are written in '''[https://developer.mozilla.org/en-US/docs/web/JavaScript JavaScript]'''. When a trigger script is executed, it may perform actions like changing an existing entry, creating a new entry, executing an HTTP request, creating a file, performing data validation, etc.
 
-----
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.


=== Terminology ===
== Definitions ==
So, we define the following terms:
We define the following terms:
:; Event type
:; Event type
:: One of the following:
:: One of the following:
::* Opening a library
::* Creating an entry
::* Creating an entry
::* Updating an entry
::* Updating an entry
::* Updating a field
::* Deleting an entry
::* Deleting an entry
::* Linking an entry
::* Unlinking an entry
::* Opening an Entry Edit card
::* Opening an Entry Edit card
::* Adding an entry to Favorites
::* Adding an entry to Favorites
::* Removing an entry from Favorites
::* Removing an entry from Favorites


:; Event or Phase
:; Phase of an Event
:: 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 and the Phase are essentially synonymous.<br/>Depending upon context, either term may be more appropriate than the other.
:: One of a predefined set of moments during entry processing for each Event type during which the user can intervene via a trigger script. See [[#Events & Phases|the table of events and phases below]].<br/> The Event type and the Phase determine the trigger script(s) to be run.


:; Trigger or Trigger Script
:; Trigger or Trigger Script
:: A script that may be defined to run when an event occurs for an entry<br/>The trigger (Event type & Phase) and the corresponding trigger script are one-to-one.<br/>When referring specifically to the script, it is called the ''trigger script''. When referring to the Event type & Phase and its listing in the trigger list, it is referred to merely as a ''trigger''.
:: A script that may be defined to run when an event occurs for an entry<br/>The trigger (Event type & Phase) and the corresponding trigger script are one-to-one.<br/>When referring specifically to the script, it is called the ''trigger script''. When referring to the Event type & Phase and its listing in the trigger list, it is referred to merely as a ''trigger''.


== Mode of script execution ==
=== Mode of script execution ===
The phase in which the trigger is activated defines its mode of execution &mdash; synchronous or asynchronous.
The phase in which the trigger is activated defines its mode of execution &mdash; synchronous or asynchronous.


; Synchronous script execution mode
:; Synchronous script execution mode: Memento suspends user interaction and then executes the script. In the case of '''Before...''' phases, there is an impending operation that will take place unless the script forestalls it by calling ''cancel()''.<br/>Time-consuming operations are not recommended in this mode.
: implies the application suspends user interaction and then executes the script. It is not recommended to perform time-consuming operations in this case.


; Asynchronous script execution mode
:; Asynchronous script execution mode: The script runs in the background; user interaction is '''not''' suspended. Usually, asynchronous scripts are used in the last phases of the action, after any save or other operation is initiated.
: 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.
-----
 
=== Scripting for creating and for updating entries ===
== Creating a trigger ==
If you want the same logic to be used in both your ''Creating'' scripts and your ''Updating'' scripts, it is tempting to just copy the code for one and paste it into the other, and that can be  done in '''''in most cases'''''. If you write your ''Updating'' script first, the copy will work. If you write your ''Creating'' script first, then you '''''may''''' still be able to copy, but if you needed for the ''Creating'' Script to be executed ''Before saving'', you'll need to change ''defaultEntry()'' to use ''entry()'' instead.
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.


== Events ==
== Events & Phases ==
These are the defined ''Event types'', ''Phases'', and their corresponding moves of execution.
These are the defined ''Event types'', ''Phases'', and their corresponding modes of execution.
{| class="wikitable" style="font-size:120%"
{| class="wikitable" style="font-size:120%"
|+ THE DEFINED EVENT TYPES & THEIR PHASES
|+ THE DEFINED EVENT TYPES & THEIR PHASES
|-
|-
! Event type !! Phase !! Execution mode
! Event type !! Phase !! [[#Mode of script execution|Execution mode]]
|-
|| '''[[#Opening a library|Opening a library]]'''
| '''Opening the library''' || synchronous
|-
|-
| rowspan="3" | '''Creating an entry'''
| rowspan="3" | '''[[#Creating an entry|Creating an entry]]'''
| '''Opening an Entry Edit card for add''' || synchronous
| '''Opening an Entry Edit card''' || synchronous
|-
|-
| '''Before saving the entry'''  || synchronous
| '''Before saving the entry'''  || synchronous
Line 50: Line 54:
| '''After saving the entry''' || asynchronous
| '''After saving the entry''' || asynchronous
|-
|-
| rowspan="3" | '''Updating an entry'''
| rowspan="3" | '''[[#Updating an entry|Updating an entry]]'''
| '''Opening an Entry Edit card for update''' || synchronous
| '''Opening an Entry Edit card''' || synchronous
|-
| '''Before saving the entry''' || synchronous
|-
| '''After saving the entry''' || asynchronous
|-
| rowspan="2" | '''[[#Linking an entry|Linking an entry]]'''
| '''Before saving the entry'''  || synchronous
|-
| '''After saving the entry''' || asynchronous
|-
|-
| rowspan="2" | '''[[#Unlinking an entry|Unlinking an entry]]'''
| '''Before saving the entry''' || synchronous
| '''Before saving the entry''' || synchronous
|-
|-
| '''After saving the entry''' || asynchronous
| '''After saving the entry''' || asynchronous
|-
|-
| rowspan="2" | '''Deleting an entry'''
| rowspan="2" | '''[[#Deleting an entry|Deleting an entry]]'''
| '''Before deleting an entry''' || synchronous
| '''Before deleting the entry''' || synchronous
|-
|-
| '''After deleting an entry''' || asynchronous
| '''After deleting the entry''' || asynchronous
|-
|-
| rowspan="2" | '''Opening an Entry View card'''
| rowspan="2" | '''[[#Opening an Entry View card|Opening an Entry View card]]'''
| '''Before window display''' || synchronous
| '''Before window display''' || synchronous
|-
|-
| '''After window display''' || asynchronous
| '''After window display''' || asynchronous
|-
|-
| rowspan="2" | '''Adding entries to Favorites'''
| rowspan="2" | '''[[#Adding an entry to Favorites|Adding an entry to Favorites]]'''
| '''Before the operation''' || synchronous
| '''Before the operation''' || synchronous
|-
|-
| '''After the operation''' || asynchronous
| '''After the operation''' || asynchronous
|-
|-
| rowspan="2" | '''Deleting an entry from Favorites'''
| rowspan="2" | '''[[#Removing an entry from Favorites|Removing an entry from Favorites]]'''
| '''Before the operation''' || synchronous
| '''Before the operation''' || synchronous
|-  
|-  
Line 78: Line 92:
|}
|}


== Security ==
=== Opening a library ===
Since the scripts have access to more actions than a user does, they require additional permissions.
This event occurs when a library is opened before any activity is performed on the library.
 
This event has only one phase, and it is ''synchronous''. Therefore, the script will fully execute before any other activity takes place in the library.
The user must define these permissions manually for each library.


To open the dialog to set permissions for scripts, open the library triggers list and click ''Shield'' on the toolbar. Permissions must be set separately on each device. Permissions are not synchronized between devices.
=== Creating an entry ===
This event starts when a user has requested that a new entry be added to the library, normally by pressing the '''<big>+</big>''' button on the Entries List screen. It ends after the entry is saved to storage &mdash; or else not, depending on the processing of the entry.
==== Phases ====
This event has three phases. In sequence:
:; 1. Opening an Entry Edit card (synchronous): The script will be called once the Entry Edit card is open and before any data is displayed.<br/>Initial field values (defaults) may be set.


=== Permissions for scripts ===
:; 2. Before saving the entry (synchronous): The script will be called after the user has pressed the '''Checkmark''' icon and before the entry has been saved to storage.<br/>The entered data may be validated; if validation fails, the save may be forestalled and control sent back to the Entry Edit card so the user may fix the errors.<br/>Once the data is validated, this phase is an opportunity for many other functions to be performed to get data to add to the entry to be saved.
; Library permissions
: determines which other libraries can be affected by the script. You can grant access to all libraries or select only certain libraries. This authorization is required for the libByName() method.


; Read permissions
:; 3. After saving the entry (asynchronous): The script will be called once the save of the entry has been initiated and will continue in parallel with final processing of the new entry.<br/>If you want to do something whenever a new entry is added, but not before the data is saved, this is the place to do it.
: grants the script read access to a file


; Write permissions
==== Scripting considerations ====
: grants the script write access to a file


; Network
'''=>''''' Say what here? '''''
: grants to the script the right to execute http requests


== Libraries and Entries ==
===== Creating an entry =====
=== Global Methods ===
''Creating'' scripts are different from other trigger scripts in that, since the new entry is being crafted, it is not yet stored within Memento &mdash; the Entry object does not yet exist &mdash; so it needs to be handled differently.


==== entry() ====
Use the method ''defaultEntry()'', rather than ''entry()'', to get the DefaultEntry object (the ''un''stored template, if you will, for the eventual Entry object).
: Get the entry of the Event. For example, if script is triggered by an Update Entry event, this method will return the entry being updated.
: This method is available to all Events and Phases, with the exception of "Creating a file &gt; Opening an Entry Edit card for add"; for this action, use the method entryDefault().


:; Result: [[#Object entry|'''Entry object''']] &mdash; the current entry
Once the default entry is saved, it can be referred to by calling ''entry()'' to get the saved Entry object. So ''Before saving'' scripts use ''defaultEntry()'', and ''After saving'' scripts use ''entry()''.


==== entryDefault() ====  
=== Updating an entry ===
: Get the Entry object containing the default field values for the Entry not yet created. This feature is available for the Event ''Creating an entry &gt; Opening an Entry Edit card''.
This event starts when a user has requested that an existing entry be edited (updated) within the library, normally by pressing the '''Pencil''' button on the Entry View card. It ends after the entry is resaved to storage &mdash; or else not, depending on the processing of the entry.
==== Phases ====
This event has three phases. In sequence:
:; 1. Opening an Entry Edit card (synchronous): The script will be called once the Entry Edit card is open and before any data is displayed.


:; Result: The DefaultEntry object
:; 2. Before saving the entry (synchronous): The script will be called after the user has pressed the '''Checkmark''' icon and before the entry has been saved to storage.<br/>The entered data may be validated; if validation fails, the save may be forestalled and control sent back to the Entry Edit card so the user may fix the errors.<br/>Once the data is validated, this phase is an opportunity for many other functions to be performed to get data to add to the entry to be saved.<br/>The script could be used to update some entry data based on other entry data, to keep it all coordinated.


==== lib() ====
:; 3. After saving the entry (asynchronous): The script will be called once the save of the entry has been initiated and will continue in parallel with final processing of the new entry.<br/>If you want to do something whenever an existing entry is updated, but not before the data is saved, this is the place to do it.
: Get the library of the Event


:; Result: [[#Object library|'''Library object''']] &mdash; the current library
'''<i><b>The following 2 sections are under development.</b></i>'''


==== libByName(name) ====  
=== Updating a field ===
: Get the named library. Permission to use the library is required.
TBD


:; Argument: The name of the library to get
=== Linking an entry ===
This event starts when a user has added a linked entry to a Link to Entry field either by selecting an existing entry from the entries list for the linked library or by pressing '''+''' (Plus) to create a new entry in the linked library. It ends after the entry is resaved to storage &mdash; or else not, depending on the processing of the entry.
==== Phases ====
This event has two phases. In sequence:
:; 1. Before saving the entry (synchronous): The script will be called before the entry has been saved to storage after the user has either selected an entry from the linked library or pressed the '''Checkmark''' icon after having added a new entry to the linked library from within the Link to Entry field.<br/>The entered data may be validated; if validation fails, the save may be forestalled and control sent back to the Entry Edit card so the user may fix the errors.<br/>Once the data is validated, this phase is an opportunity for many other functions to be performed to get data to add to the entry to be saved.<br/>The script could be used to update some entry data based on other entry data, to keep it all coordinated.


:; Result: [[#Object Library|'''Library object''']] &mdash; the library identified by the argument ''name''
:; 2. After saving the entry (asynchronous): The script will be called once the save of the entry has been initiated and will continue in parallel with final processing of the new entry.<br/>If you want to do something whenever an existing entry is updated, but not before the data is saved, this is the place to do it.


=== Object ''Library'' ===
The script of this event type has access to additional functions:
This object provides access to library entries. You can work with the current library &mdash; the lib() &mdash; or any other library database &mdash; libByName(). This method provides the ability to update existing entries and create new ones.
===== masterLib() ===== 
:Returns the library from which the current record was referenced.
===== masterEntry() =====
:Returns the entry from which the current record was referenced.
===== attr(name) =====
:Get the value of the attribute for the current reference.
===== setAttr(name , value) =====
:Set the value of the attribute for the current reference.


==== Methods ====
=== Unlinking an entry ===
===== entries() =====
This event starts when a user has requested that an existing entry be edited (updated) within the library, normally by pressing the '''Pencil''' button on the Entry View card. It ends after the entry is resaved to storage &mdash; or else not, depending on the processing of the entry.
: Get all the entries of the library
==== Phases ====
:; Result: Array object containing entries, sorted by the time of their creation, from newest to oldest
This event has two phases. In sequence:
:; 1. Before saving the entry (synchronous): The script will be called after the user has pressed the '''Checkmark''' icon and before the entry has been saved to storage.<br/>The entered data may be validated; if validation fails, the save may be forestalled and control sent back to the Entry Edit card so the user may fix the errors.<br/>Once the data is validated, this phase is an opportunity for many other functions to be performed to get data to add to the entry to be saved.<br/>The script could be used to update some entry data based on other entry data, to keep it all coordinated.


===== find(query) =====
:; 2. After saving the entry (asynchronous): The script will be called once the save of the entry has been initiated and will continue in parallel with final processing of the new entry.<br/>If you want to do something whenever an existing entry is updated, but not before the data is saved, this is the place to do it.
: Search for entries in the library matching the given query. This search is similar to searching via Memento's user interface.
:; Argument: '''query''' &mdash; the search string
:; Result: Array object containing matching entries. Entries are sorted by the time of their creation, from newest to oldest.


===== findByKey(name) =====
=== Deleting an entry ===
: Search for all entries by the Entry Name field value. The library must be set for unique Entry Names.
This event starts when a user has requested that an existing entry be deleted (actually, moved to the library's Recycle Bin) within the library, normally by pressing the '''Trash Can''' button on the Entry View card. It ends after the entry is moved to the Recycle Bin &mdash; or else not, depending on the processing of the entry.
:; Argument: '''name''' &mdash; the Entry Name field value
:; Result: Entry object


===== create(values) =====
==== Phases ====
: Create a new entry in the library
This event has two phases. In sequence:
:; Argument: '''values''' &mdash; [https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object '''Object'''] containing the field values
:; 1. Before deleting the entry (synchronous): This script will be called after the user has requested the deletion of the entry and pressed '''Yes''' on the "Do you really want to?" card, but before taking the action.<br/>Since the user has at this point already confirmed that he or she really wants to delete that entry, what else needs to be done before doing the delete? And what would cause the delete to need to be forestalled? If the delete is to be forestalled, the script could call ''cancel()'' and inform the user as to why via ''message()'', and let the user reconsider what to do.<br/>Mainly, help the user reconfirm that the deletion should take place, and if not, call ''cancel()'' and inform the user (via ''message()'').
:; Result: [[#Object entry|'''Entry object''']] &mdash; the new entry in the library


==== Properties ====
:; 2. After deleting the entry (asynchronous): This script will be called after the delete operation is initiated and will continue as that operation takes place.<br/> Anything you want to do whenever an entry is deleted should be done in this script.
: '''Title''' &mdash; The name of the library
-----


=== Object ''Entry'' ===
=== Opening an Entry View card ===
This object holds an entry of the current library, primarily including field values. Methods provide access to the field values.
This event starts when the user has selected an entry for view and ends after the entry had been displayed.
==== Phases ====
This event has two phases. In sequence:
:; 1. Before window display (synchronous): This script will be called before the entry is displayed. This provides the opportunity to alter or augment the data before it is seen by the user.
:; 2. After window display (asynchronous): This script will be called after the data display had been initiated, providing the opportunity to perform an action each time an entry had been viewed, such as logging or timestamping.


==== Entry Methods ====
=== Adding an entry to Favorites ===
===== set(name, value) =====
This event starts when the user has pressed an empty '''Star''' icon to make the current entry a Favorite and ends once it has been made a Favorite.
: Set the value of the named field. After being called once, there is an entry with values in the library.
==== Phases ====
This event has two phases. In sequence:
:; 1. Before the operation (synchronous): This script is run just before the entry is made a Favorite.<br/>Data validation could be done; perhaps only certain entries are allowed to be Favorites.
:; 2. After the operation (asynchronous): This script is called after the entry has been made a Favorite.<br/>This action could be logged, for instance, or it could trigger an action on some other app.


:; Arguments
=== Removing an entry from Favorites ===
:: '''name''' &mdash; name of the field
This event starts when the user has pressed a filled '''Star''' icon to remove the current entry from Favorites and ends once it has been removed.
:: '''value''' &mdash; the value of the field
==== Phases ====
This event has two phases. In sequence:
:; 1. Before the operation (synchronous): This script is run just before the entry is removed from Favorites.<br/>Confirmation of the user's intent could go here.
:; 2. After the operation (asynchronous): This script is called after the entry has been removed from Favorites.<br/>This action could be logged, for instance, or it could trigger an action on some other app.


===== field(name) =====
-----
: Get the value of the named field
<br/>
:; Argument: '''name''' &mdash; name of the field
:; Result: The value of the field


==== Entry Properties ====
== Security ==
: '''Title''' &mdash; account name
Since the scripts have access to more actions than a user does, they require additional permissions.
: '''Description''' &mdash; description
: '''Favorites''' &mdash; true, if the entry is in Favorites
: '''Deleted''' &mdash; true, if the record is deleted (it is in the basket)


=== Object DefaultEntry ===
The user must define these permissions manually for each library.
Template with default values for a new record


==== Methods ====
To open a card to set permissions for scripts, open the library triggers list and click the '''Shield''' icon on the toolbar. Permissions must be set separately on each device. Permissions are not synchronized between devices.
===== set(name, value) =====
: Set the value of the field


:; Arguments
=== Permissions for scripts ===
:: '''name''' &mdash; the name of the field
:; Library permission
:: '''value''' &mdash; the value of the field
:: determines which other libraries can be affected by the script. You can grant access to all libraries or select only certain libraries. This authorization is required for the ''libByName()'' function.


=== Examples ===
:; Read permission
:: grants the script read access to a file


==== Data Validation ====
:; Write permission
Using scripts, you can check the correctness of input data. For example, for a field integer values ​​are allowed only from 0 to 200.
:: grants the script write access to a file


<source lang="javascript" line>
:; Network
var num = entry().field("Number")
:: grants to the script the right to execute HTTP requests
if (num < 0 || num > 200) {
-----
message("Wrong range");
<br/>
cancel();
}
</source>


# We get the value of the field Number
== Creating a trigger ==
# Tests for values ​​matching the allowable range
Each library can have a number of triggers; multiple triggers may exist for each Event type and Phase. To see the list of triggers, open the library, open the menu, and then select ''Triggers''.
# If the value is out of range then display a message Wrong range
# Cancels the operation


This script should be used for the action '''Create entry''' or '''Change entry'''.
To create a trigger, press the 3-dot icon in the upper-right corner of the screen to open the Action Menu; then press Triggers to open the list of existing triggers; then click <big>'''+'''</big>. You must then identify the Event type & Phase and write a trigger script that performs the necessary actions.


==== Set default values ====
=== Writing a Trigger Script ===
If the standard tools can not be set to the desired value of the field by default, it can be done through a script.
Trigger scripts are in the JavaScript language. See '''''[[#JavaScript links|Links to JavaScript documentation]]''''' below.


===== Previous value of another field =====
; Event & Phase: Make sure to understand the Event & Phase you are scripting. This will dictate a number of things, such as whether data is present already or not, whether ''cancel()'' makes sense or not, whether the user is waiting for script execution or not, and so on.
There is a library containing the records of daily walks or use of a car or bicycle. The library has a StartingMileage field and a Mileage field. When an entry is created, the field StartMileage must get data from the field Mileage in the previous entry.


<source lang="javascript" line>
; Globals get you started: Note the global functions in the sections below; they generally get you started by providing needed information.
var entries = lib().entries();
if (entries.length > 0) {
prevMileage = entries[0].field("Mileage");
entryDefault().set("StartMileage" , prevMileage )
}
</source>


# Get the current library and an array of its entries.
; Inform the user: Keep the user informed. For instance, if a script is running in a synchronous phase, then a call to ''cancel()'' may make sense, but the user won't know what happened and what to do next unless you provide that information, probably via ''message()''.
# Check that the array is not empty of entries; otherwise stop the script, so we do not have a previous entry.
# The array of entries is sorted from newest to oldest. The previous entry is set to the newest entry at the beginning of the array with an index value of 0. Get the Mileage field from the previous entry.
# We set the value of the field Mileage from the previous entry as the default value for the field StartMileage.


The script must be set for action ''Creating and recording phase opening of the card''.
; Debug your script: Of course, you can put calls to ''message("Your message")'' to help to test your script. To further assist, the ''log("Your message")'' global function can be used to send messages to a log without bothering the user about it. By default, the log is directed to the Android developer console; to have it directed instead to a file, go to Memento Settings under Debug and turn on Triggers Logs. You can set the location for the file, but by default, it will be in ''memento/logs''. Both messages from calls to ''log()'' and system log messages, including JavaScript exceptions, go into the log.


===== Beginning the next day =====
; Permissions: Certain functions require special permissions; read '''''[[#Security|above]]''''' about that. One such function is ''libByName()''. Others include the file access and HTTP functions.
If you want the date/time field when creating a record, set the beginning of the next day, it can make the following script. For the script, you must connect the JavaScript-library moment.js [http://momentjs.com/ moment.js]


<source lang="javascript" line>
; No return: As of release 4.0.0 of the mobile edition, the script is executed as a top-level script and not as a called function; therefore, for instance, the ''return'' statement is not appropriate in a trigger script.
var m = moment().add(1,'d')
m.hour(8).minute(0)
entryDefault().set("Date" , m.toDate().getTime())
</source>


# With the moment () function library moment.js obtain the current time and add 1 day.
==== Things to know while writing a trigger script ====
# Set time of 8 hours and 0 minutes.
:; No implicit context: There is no implicit context for the trigger script, as there is, for instance, in a JavaScript field. Instead, there are global functions, such as lib() and entry() that must be used to set up context for the script.
# Write a default value for the field Date.
:; Entry objects are clones: The Entry object associated with the Event (the one that entry() gives you) is a clone of the actual entry object. If changes are made to this object, they will be saved if the script returns normally. However, if the script calls cancel(), this clone will be discarded upon return from the script, along with any changes that have been made.
 
-----
The script must be set for action Creating a record and phase Opening a form.
<br/>
 
== Working with files ==
With scripts you can read or write files located in the device's internal memory or on the SD card. All file operations performed by the File object, which is obtained through a method call file().
 
To work with the files for the library to be set to a resolution - on the reading and / or writing files.
 
=== Global Functions ===
==== file(name) ====
Open a file for read or write operations.
 
:;Argument
:: '''name''' &mdash; The name and the full path to the file.<br/>For example, if the file is located on the SD card, the path should look /sdcard/example.txt, assuming /sdcard as the path on your platform to the SD card.
 
:; Result
:: Object file
 
=== Object File ===
This object is returned by the file() method 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().
 
==== Methods ====
; readAll()
: Reads all lines of the file, and then closes the file
:; Returns
:: Array containing the lines of the file
 
; readLine()
: Reads a line from the file
:; Returns: The line
 
; readLines()
: Reads the remaining lines in the file
:; Returns: Array containing the remaining lines of the file
 
; readChar()
: Reads a character
:; Returns: The character
 
; write(text)
: Write string(s). This function takes a variable number of arguments, converts each argument to a string, and writes that string to the file.
 
; writeLine(text)
: Write strings and a newline to the file
 
; close()
: Close the file. It can be subsequently reopened.
 
==== Properties ====
; exists: true - if and only if the file exists; false otherwise
; length: The length, in bytes, of the file, or 0L if the file does not exist.  
; getLineNumber: Get the current line number
:; Returns: The line number, or position, in the file
 
=== Examples ===
==== Writing & reading from a file ====
 
<source lang="javascript" line>
f = file("/sdcard/myfile.txt")
f.writeLine("one");                     
f.writeLine("two");
f.writeLine("three");
f.close();   
var a = f.readLines();
</source>
 
<ol>
<li>Open myfile.txt file on the sdcard. If the file does not exist, it is created.</li>
<li>Write the string "one" as a line to the file</li>
</ol>
<ol start="5">
<li>Save and close the file</li>
<li>Read all the lines of the file into the array a</li>
</ol>
 
====Save a file to a record ====
Необходимо сохранить запись в формате xml. Запись имеет следующие поля: id , title , date.
<source lang="javascript" line>
var xml = '<record id="' + entry().field("id") + '">' +
'<title>' + entry().field("title") + '</title>' +
'<date>' + entry().field("date") + '</date>' +
'</record>';
f = file("/sdcard/" + entry().field("title") + ".xml");
f.write(xml);
f.close();
</source>
<ol><li>Формируем xml данные из значений полей для записи в файл.</li></ol>
<ol start="5">
<li>Открываем файл, имя файла будет таким же как и имя записи.</li>
<li>Сохраняем в файл xml-данные</li>
<li>Закрываем файл</li>
</ol>
 
==Выполнение http запросов==
С помощью скриптов можно выполнять http-запросы, что позволяет обмениваться информацией с веб-службами предоставляющими API. Также через http запросы вы можете интегрировать Memento со своей системой.
Все операции с файлами производятся через объект Http, который получается через вызов глобального метода http().
 
Http запросы доступны при соблюдении двух условий:
# Выполнение скрипта должно быть асинхронным (фоновым), так как обработка запроса по сети может занимать много времени. Таким образом выполнять http-запросы можно только в последних фазах действий.
# В библиотеки должно быть установлено разрешение - Network.
=== Object Http ===
Интерфейс выполнения http запросов.
==== Method ====
=====get(url)=====
:Выполнить get запрос.
:Параметры: url - http адрес, должен начинаться с http или https
:Результат: HttpResult - объект содержащий результат выполнения http запроса.
 
=== Object HttpResult ===
Результат выполнения http запроса
====Свойства====
;code : http код ответа, если запрос выполнен успешно, то он обычно равен 200.
;body : тело ответа в виде текста.
 
===Примеры===
====Конвертация валюты====
Библиотека содержит два поля PriceUSD и PriceEUR. Пользователь заполняет только поле PriceUSD, требуется чтобы в поле  PriceEUR  записывалась цена в евро по текущему курсу.
Создадим триггер на действие ''Создание записи'', фаза выполнения будет ''После сохранения''.
<source lang="javascript" line>
result = http().get("http://api.fixer.io/latest?base=USD")
usdToEur = JSON.parse(result.body)["rates"]["Eur"]
entry().set("PriceEUR" , entry().field( "PriceUSD") * usdToEur )
</source>
#Для получения курсов валют пользуемся сервисом http://fixer.io/. Сервис по запросу http://api.fixer.io/latest?base=USD возвращает курсы валют в JSON формате.
#Воспользуется стандартным JavaScript объектом JSON чтобы распарсить ответ.
#Умножаем цену из поля PriceUSD на коэффициент конвертации валюты и устанавливаем полученное значение в поле PriceEUR.
 
====Создание задачи в приложении Todoist====
[https://todoist.com Todoist] — это веб-сервис и программа для управления задачами. Веб-сервис предоставляет возможность через [https://developer.todoist.com/ api] создавать задачи.
Приведем скрипт для создания задачи, текст задачи будет браться из записи.
<source lang="javascript" line>
var commands='[{"uuid":"' + guid() + '","temp_id":"' + guid() + '","type":"item_add","args":{"content":"' + entry().field("Task") + '"}}]'
result = http().get("https://todoist.com/API/v7/sync?token=15281e8e4d499dаff817af0b14112eac3176f9dc&commands=" + encodeURIComponent(commands))
if (result.code == 200) message('Task has been successfully created")
</source>
#Составляем команду в json формате для создания задачи в todoist, формат команды описан здесь: https://developer.todoist.com/#add-an-item. В команде должны присутствовать уникальные идентификаторы, для их получения используем глобальную функцию guid().
#Выполняем http запрос. Атрибут token используется для авторизации в todoist, его можно получить в Настройках Todoist вкладка Аккаунт. Так как текст задачи может содержать символы недопустимые в URL-запроса, то экранируем их с помощью стандартной функции encodeURIComponent().
#Выводим пользователю сообщение об успешно созданной задачи.
 
==Взаимодействие с системой==
===Глобальные Функции===
====message(text)====
:Отобразить пользователю небольшое всплывающее сообщение.
:Параметры: text - текст для отображения.
 
====cancel()====
:Отменить операцию вызвавшую данный триггер. Многие действия возникают при каких либо операциях с записями (создание, модификация, удаление и .д.). Если фаза действия предшествует операции, то возможно отменить эту операцию с помощью данной функции. Например, применять эту функцию можно при проверки корректности вводимых данных перед сохранением записи.
 
====system()====
:Получить информацию о системе.
:Результат: Объект System с информацией о системе.
 
====log(text)====
:Вывести строку в лог-файл выполнения скрипта. Функция будет полезна для отладки скриптов.
:Параметры: Text - текст который будет выведен в лог.
 
====guid()====
:Генерация случайного текстового идентификатора.
:Результат: Случайная строка-идентификатор.
 
====intent(action)====
:Создать объект обмена сообщениями - Intent. С помощью данного объекта можно передать данные другому приложению, или заставить другое приложение выполнить какое-либо действие.
:Функция доступна только для Android.
:Параметры: action - Строка, определяющая стандартное действие, которое требуется выполнить (например, view (просмотр) или pick (выбор)).
:Результат: Intent - объект обмена сообщениями.
:После получения объекта требуется добавить в него отправляемые данные и вызывать метод send().
:В Android есть множество встроенных  действий, список и описание которых вы можете найти [https://developer.android.com/reference/android/content/Intent.html здесь].
 
=== Object System ===
Данный объект содержит информацию о системе.
====Свойства====
;os : имя операционной системы на которой запущен скрипт.
 
===Объект Intent===
Объект обмена сообщениями. Объект создается с помощью вызова глобальной функции intent().
====Методы====
=====data(uri)=====
:Установить URI ссылающийся на данные.
:Параметры:uri - URI, ссылающийся на данные, с которыми будет выполняться действие. Это может быть идентификатор контакта, путь к файлу, номер телефона и т.д.
=====mimeType(mime)=====
:Установить MIME тип данных.
:Параметры:mime - MIME тип данных с которыми будет выполняться действие.
=====extra(key, value)=====
:Установить дополнительные данные в виде ключ-значение, которые необходимы для выполнения запрошенного действия. Точно так же, как некоторые действия используют определенные виды URI данных, некоторые действия используют определенные дополнительные данные.
:Параметры:
=====extraLong(key, value)=====
:Установить дополнительные данные в виде ключ-значение, где значение должно быть типом Long.
=====send()=====
:Отправить сообщение.
 
===Примеры===
====Скрипт открывающий окно набора номера====
В библиотеке должно быть поле Phone, содержащие номер телефона.
<source lang="javascript" line>
i = intent("android.intent.action.DIAL")
i.data("tel:"+entry().field("Phone"))
i.send()
</source>
# Создаем объект обмена сообщениями Intent и указываем действие которое откроет окно набора номера - android.intent.action.DIAL.
# В качестве данных требуется указать номер телефона в формате ''tel:номер''. Номер телефона берем из поля записи Phone.
# Отправляем сообщение.
 
====Скрипт открывающий приложение для отправки смс-сообщения====
Номер телефона будет определяться полем записи - Phone, а текст сообщения составляется из полей ContactName и Notes.
<source lang="javascript" line>
msg = "Dear, " + entry().field("ContactName") + "\n" + entry().field("Notes")
i = intent("android.intent.action.SENDTO")
i.data("smsto:"+entry().field("Phone"))
i.extra("sms_body" , msg)
i.send()
</source>
# Составляем сообщение из значений полей ContactName и Notes
# Создаем объект обмена сообщениями Intent и указываем действие которое откроет приложение для отправки сообщений- android.intent.action.SENDTO.
# В качестве данных требуется указать номер телефона в формате ''smsto:номер''. Номер телефона берем из поля записи Phone.
# Текст сообщение передаем в дополнительный параметр sms_body.
# Отправляем сообщение.


====Скрипт открывающий форму создания события в Гугл-Календаре.====
== See Also ==
Время события и название события будут определяться полями записи.
; [[Memento JavaScript Library]]: Memento JavaScript functions & objects<br/>
<source lang="javascript" line>
; [[Trigger Examples]]: Examples of trigger scripts for common needs
i = intent("android.intent.action.INSERT")
; [[How:Write scripts in JavaScript for Memento]]: Guidelines for writing JavaScript scripts for Memento
i.data("content://com.android.calendar/events")
i.extra("title", entry().field("Title"))
i.extra("description" , entry().field("Description"))
i.extraLong("beginTime" , entry().field("Begin").getTime())
i.extraLong("endTime" , entry().field("End").getTime())
i.send()
</source>
# Создаем объект обмена сообщениями Intent и указываем действие которое требуется выполнить, а именно создание объекта - android.intent.action.INSERT.
# Для события android.intent.action.INSERT в data требуется передать базовый Uri создаваемого объекта. Событие в Google-календаре имеет базовый Uri - content://com.android.calendar/events.
# Устанавливаем название события, которое берем из поля Title.
# Устанавливаем описание события, которое берем из поля Description.
# Устанавливаем время начала события, которое берем из поля Begin. Поле Begin должно иметь тип Date/Time. Дополнительный параметр beginTime должен иметь тип Long, поэтому используется метод extraLong.
# Устанавливаем время окончания события, которое берем из поля End. Поле End должно иметь тип Date/Time. Дополнительный параметр endTime должен иметь тип Long, поэтому используется метод extraLong.
# Отправляем сообщение.


== JavaScript links ==
[[Category:en]] [[Category:Spec]] [[Category:Sc]]
{{Template:JavaScriptLinks}}

Latest revision as of 08:26, 23 August 2023

« Page as of 2023-08-12, editions Mobile 5.0, Desktop 2.0 »
Wiki
Home 		About
Wiki | Memento 		Getting started
Wiki | Memento 		Indexes
Mobile | Desktop | Scripting 		Support
Wiki | Memento 
Triggers

A Trigger is a script that defines the processing of an entry whenever a particular kind of event takes place. Trigger scripts are written in JavaScript. When a trigger script is executed, it may perform actions like changing an existing entry, creating a new entry, executing an HTTP request, creating a file, performing data validation, etc.

Definitions

We define the following terms:

Event type
One of the following:
  • Opening a library
  • Creating an entry
  • Updating an entry
  • Updating a field
  • Deleting an entry
  • Linking an entry
  • Unlinking an entry
  • Opening an Entry Edit card
  • Adding an entry to Favorites
  • Removing an entry from Favorites
Phase of an Event
One of a predefined set of moments during entry processing for each Event type during which the user can intervene via a trigger script. See the table of events and phases below.
The Event type and the Phase determine the trigger script(s) to be run.
Trigger or Trigger Script
A script that may be defined to run when an event occurs for an entry
The trigger (Event type & Phase) and the corresponding trigger script are one-to-one.
When referring specifically to the script, it is called the trigger script. When referring to the Event type & Phase and its listing in the trigger list, it is referred to merely as a trigger.

Mode of script execution

The phase in which the trigger is activated defines its mode of execution — synchronous or asynchronous.

Synchronous script execution mode
Memento suspends user interaction and then executes the script. In the case of Before... phases, there is an impending operation that will take place unless the script forestalls it by calling cancel().
Time-consuming operations are not recommended in this mode.
Asynchronous script execution mode
The script runs in the background; user interaction is not suspended. Usually, asynchronous scripts are used in the last phases of the action, after any save or other operation is initiated.

Scripting for creating and for updating entries

If you want the same logic to be used in both your Creating scripts and your Updating scripts, it is tempting to just copy the code for one and paste it into the other, and that can be done in in most cases. If you write your Updating script first, the copy will work. If you write your Creating script first, then you may still be able to copy, but if you needed for the Creating Script to be executed Before saving, you'll need to change defaultEntry() to use entry() instead.

Events & Phases

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

THE DEFINED EVENT TYPES & THEIR PHASES
Event type Phase Execution mode
Opening a library Opening the library synchronous
Creating an entry Opening an Entry Edit card synchronous
Before saving the entry synchronous
After saving the entry asynchronous
Updating an entry Opening an Entry Edit card synchronous
Before saving the entry synchronous
After saving the entry asynchronous
Linking an entry Before saving the entry synchronous
After saving the entry asynchronous
Unlinking an entry Before saving the entry synchronous
After saving the entry asynchronous
Deleting an entry Before deleting the entry synchronous
After deleting the entry asynchronous
Opening an Entry View card Before window display synchronous
After window display asynchronous
Adding an entry to Favorites Before the operation synchronous
After the operation asynchronous
Removing an entry from Favorites Before the operation synchronous
After the operation asynchronous

Opening a library

This event occurs when a library is opened before any activity is performed on the library. This event has only one phase, and it is synchronous. Therefore, the script will fully execute before any other activity takes place in the library.

Creating an entry

This event starts when a user has requested that a new entry be added to the library, normally by pressing the + button on the Entries List screen. It ends after the entry is saved to storage — or else not, depending on the processing of the entry.

Phases

This event has three phases. In sequence:

1. Opening an Entry Edit card (synchronous)
The script will be called once the Entry Edit card is open and before any data is displayed.
Initial field values (defaults) may be set.
2. Before saving the entry (synchronous)
The script will be called after the user has pressed the Checkmark icon and before the entry has been saved to storage.
The entered data may be validated; if validation fails, the save may be forestalled and control sent back to the Entry Edit card so the user may fix the errors.
Once the data is validated, this phase is an opportunity for many other functions to be performed to get data to add to the entry to be saved.
3. After saving the entry (asynchronous)
The script will be called once the save of the entry has been initiated and will continue in parallel with final processing of the new entry.
If you want to do something whenever a new entry is added, but not before the data is saved, this is the place to do it.

Scripting considerations

=> Say what here?

Creating an entry

Creating scripts are different from other trigger scripts in that, since the new entry is being crafted, it is not yet stored within Memento — the Entry object does not yet exist — so it needs to be handled differently.

Use the method defaultEntry(), rather than entry(), to get the DefaultEntry object (the unstored template, if you will, for the eventual Entry object).

Once the default entry is saved, it can be referred to by calling entry() to get the saved Entry object. So Before saving scripts use defaultEntry(), and After saving scripts use entry().

Updating an entry

This event starts when a user has requested that an existing entry be edited (updated) within the library, normally by pressing the Pencil button on the Entry View card. It ends after the entry is resaved to storage — or else not, depending on the processing of the entry.

Phases

This event has three phases. In sequence:

1. Opening an Entry Edit card (synchronous)
The script will be called once the Entry Edit card is open and before any data is displayed.
2. Before saving the entry (synchronous)
The script will be called after the user has pressed the Checkmark icon and before the entry has been saved to storage.
The entered data may be validated; if validation fails, the save may be forestalled and control sent back to the Entry Edit card so the user may fix the errors.
Once the data is validated, this phase is an opportunity for many other functions to be performed to get data to add to the entry to be saved.
The script could be used to update some entry data based on other entry data, to keep it all coordinated.
3. After saving the entry (asynchronous)
The script will be called once the save of the entry has been initiated and will continue in parallel with final processing of the new entry.
If you want to do something whenever an existing entry is updated, but not before the data is saved, this is the place to do it.

The following 2 sections are under development.

Updating a field

TBD

Linking an entry

This event starts when a user has added a linked entry to a Link to Entry field either by selecting an existing entry from the entries list for the linked library or by pressing + (Plus) to create a new entry in the linked library. It ends after the entry is resaved to storage — or else not, depending on the processing of the entry.

Phases

This event has two phases. In sequence:

1. Before saving the entry (synchronous)
The script will be called before the entry has been saved to storage after the user has either selected an entry from the linked library or pressed the Checkmark icon after having added a new entry to the linked library from within the Link to Entry field.
The entered data may be validated; if validation fails, the save may be forestalled and control sent back to the Entry Edit card so the user may fix the errors.
Once the data is validated, this phase is an opportunity for many other functions to be performed to get data to add to the entry to be saved.
The script could be used to update some entry data based on other entry data, to keep it all coordinated.
2. After saving the entry (asynchronous)
The script will be called once the save of the entry has been initiated and will continue in parallel with final processing of the new entry.
If you want to do something whenever an existing entry is updated, but not before the data is saved, this is the place to do it.

The script of this event type has access to additional functions:

masterLib()
Returns the library from which the current record was referenced.
masterEntry()
Returns the entry from which the current record was referenced.
attr(name)
Get the value of the attribute for the current reference.
setAttr(name , value)
Set the value of the attribute for the current reference.

Unlinking an entry

This event starts when a user has requested that an existing entry be edited (updated) within the library, normally by pressing the Pencil button on the Entry View card. It ends after the entry is resaved to storage — or else not, depending on the processing of the entry.

Phases

This event has two phases. In sequence:

1. Before saving the entry (synchronous)
The script will be called after the user has pressed the Checkmark icon and before the entry has been saved to storage.
The entered data may be validated; if validation fails, the save may be forestalled and control sent back to the Entry Edit card so the user may fix the errors.
Once the data is validated, this phase is an opportunity for many other functions to be performed to get data to add to the entry to be saved.
The script could be used to update some entry data based on other entry data, to keep it all coordinated.
2. After saving the entry (asynchronous)
The script will be called once the save of the entry has been initiated and will continue in parallel with final processing of the new entry.
If you want to do something whenever an existing entry is updated, but not before the data is saved, this is the place to do it.

Deleting an entry

This event starts when a user has requested that an existing entry be deleted (actually, moved to the library's Recycle Bin) within the library, normally by pressing the Trash Can button on the Entry View card. It ends after the entry is moved to the Recycle Bin — or else not, depending on the processing of the entry.

Phases

This event has two phases. In sequence:

1. Before deleting the entry (synchronous)
This script will be called after the user has requested the deletion of the entry and pressed Yes on the "Do you really want to?" card, but before taking the action.
Since the user has at this point already confirmed that he or she really wants to delete that entry, what else needs to be done before doing the delete? And what would cause the delete to need to be forestalled? If the delete is to be forestalled, the script could call cancel() and inform the user as to why via message(), and let the user reconsider what to do.
Mainly, help the user reconfirm that the deletion should take place, and if not, call cancel() and inform the user (via message()).
2. After deleting the entry (asynchronous)
This script will be called after the delete operation is initiated and will continue as that operation takes place.
Anything you want to do whenever an entry is deleted should be done in this script.

Opening an Entry View card

This event starts when the user has selected an entry for view and ends after the entry had been displayed.

Phases

This event has two phases. In sequence:

1. Before window display (synchronous)
This script will be called before the entry is displayed. This provides the opportunity to alter or augment the data before it is seen by the user.
2. After window display (asynchronous)
This script will be called after the data display had been initiated, providing the opportunity to perform an action each time an entry had been viewed, such as logging or timestamping.

Adding an entry to Favorites

This event starts when the user has pressed an empty Star icon to make the current entry a Favorite and ends once it has been made a Favorite.

Phases

This event has two phases. In sequence:

1. Before the operation (synchronous)
This script is run just before the entry is made a Favorite.
Data validation could be done; perhaps only certain entries are allowed to be Favorites.
2. After the operation (asynchronous)
This script is called after the entry has been made a Favorite.
This action could be logged, for instance, or it could trigger an action on some other app.

Removing an entry from Favorites

This event starts when the user has pressed a filled Star icon to remove the current entry from Favorites and ends once it has been removed.

Phases

This event has two phases. In sequence:

1. Before the operation (synchronous)
This script is run just before the entry is removed from Favorites.
Confirmation of the user's intent could go here.
2. After the operation (asynchronous)
This script is called after the entry has been removed from Favorites.
This action could be logged, for instance, or it could trigger an action on some other app.


Security

Since the scripts have access to more actions than a user does, they require additional permissions.

The user must define these permissions manually for each library.

To open a card to set permissions for scripts, open the library triggers list and click the Shield icon on the toolbar. Permissions must be set separately on each device. Permissions are not synchronized between devices.

Permissions for scripts

Library permission
determines which other libraries can be affected by the script. You can grant access to all libraries or select only certain libraries. This authorization is required for the libByName() function.
Read permission
grants the script read access to a file
Write permission
grants the script write access to a file
Network
grants to the script the right to execute HTTP requests


Creating a trigger

Each library can have a number of triggers; multiple triggers may exist for each Event type and Phase. To see the list of triggers, open the library, open the menu, and then select Triggers.

To create a trigger, press the 3-dot icon in the upper-right corner of the screen to open the Action Menu; then press Triggers to open the list of existing triggers; then click +. You must then identify the Event type & Phase and write a trigger script that performs the necessary actions.

Writing a Trigger Script

Trigger scripts are in the JavaScript language. See Links to JavaScript documentation below.

Event & Phase
Make sure to understand the Event & Phase you are scripting. This will dictate a number of things, such as whether data is present already or not, whether cancel() makes sense or not, whether the user is waiting for script execution or not, and so on.
Globals get you started
Note the global functions in the sections below; they generally get you started by providing needed information.
Inform the user
Keep the user informed. For instance, if a script is running in a synchronous phase, then a call to cancel() may make sense, but the user won't know what happened and what to do next unless you provide that information, probably via message().
Debug your script
Of course, you can put calls to message("Your message") to help to test your script. To further assist, the log("Your message") global function can be used to send messages to a log without bothering the user about it. By default, the log is directed to the Android developer console; to have it directed instead to a file, go to Memento Settings under Debug and turn on Triggers Logs. You can set the location for the file, but by default, it will be in memento/logs. Both messages from calls to log() and system log messages, including JavaScript exceptions, go into the log.
Permissions
Certain functions require special permissions; read above about that. One such function is libByName(). Others include the file access and HTTP functions.
No return
As of release 4.0.0 of the mobile edition, the script is executed as a top-level script and not as a called function; therefore, for instance, the return statement is not appropriate in a trigger script.

Things to know while writing a trigger script

No implicit context
There is no implicit context for the trigger script, as there is, for instance, in a JavaScript field. Instead, there are global functions, such as lib() and entry() that must be used to set up context for the script.
Entry objects are clones
The Entry object associated with the Event (the one that entry() gives you) is a clone of the actual entry object. If changes are made to this object, they will be saved if the script returns normally. However, if the script calls cancel(), this clone will be discarded upon return from the script, along with any changes that have been made.


See Also

Memento JavaScript Library
Memento JavaScript functions & objects
Trigger Examples
Examples of trigger scripts for common needs
How:Write scripts in JavaScript for Memento
Guidelines for writing JavaScript scripts for Memento
Retrieved from "https://wiki.mementodatabase.com/index.php?title=Triggers&oldid=4655"