Write, Bureaucrats, Administrators
4,332
edits
mNo edit summary |
mNo edit summary |
||
(22 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
{{Stamp| | {{Stamp|2021-03-31|4.10.0|1.9.6}} | ||
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 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. | ||
----- | ----- | ||
Line 8: | Line 8: | ||
:; 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 | ||
Line 28: | Line 32: | ||
:; 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. | :; 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 == | == Events & Phases == | ||
Line 36: | Line 41: | ||
|- | |- | ||
! Event type !! Phase !! [[#Mode of script execution|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|Creating an entry]]''' | | rowspan="3" | '''[[#Creating an entry|Creating an entry]]''' | ||
Line 47: | Line 55: | ||
| '''Opening an Entry Edit card''' || 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 | ||
|- | |- | ||
Line 71: | Line 89: | ||
| '''After the operation''' || asynchronous | | '''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 === | === Creating an entry === | ||
Line 81: | Line 103: | ||
:; 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. | :; 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. | ||
==== 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 ''un''stored 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 === | === Updating an entry === | ||
Line 91: | Line 124: | ||
:; 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. | :; 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. | ||
'''<i><b>The following 2 sections are under development.</b></i>''' | |||
=== 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.<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. | |||
:; 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. | |||
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.<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. | |||
:; 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. | |||
=== Deleting an entry === | === Deleting an entry === | ||
Line 153: | Line 217: | ||
=== Writing a Trigger Script === | === Writing a Trigger Script === | ||
Trigger scripts are | Trigger scripts are in the JavaScript language. See '''''[[#JavaScript links|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. | ; 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. | ||
Line 173: | Line 237: | ||
<br/> | <br/> | ||
== | == See Also == | ||
; [[Memento JavaScript Library]]: Memento JavaScript functions & objects<br/> | |||
; [[Trigger Examples]]: Examples of trigger scripts for common needs | |||
; [[How:Write scripts in JavaScript for Memento]]: Guidelines for writing JavaScript scripts for Memento | |||
<br/> | |||
: | |||
: Write | |||
[[Category:Spec]] | [[Category:Spec]] |