Write, Bureaucrats, Administrators
4,332
edits
Triggers: Difference between revisions
Jump to navigation
Jump to search
m
no edit summary
mNo edit summary |
mNo edit summary |
||
| (14 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 11: | Line 11: | ||
::* Creating an entry | ::* Creating an entry | ||
::* Updating an entry | ::* Updating an entry | ||
::* Updating a field | |||
::* Deleting an entry | ::* Deleting an entry | ||
::* Linking an entry | ::* Linking an entry | ||
| Line 31: | 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 90: | Line 92: | ||
=== Opening a library === | === Opening a library === | ||
This event occurs when a library is opened before any activity is performed on the 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. | |||
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 102: | 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 114: | Line 126: | ||
'''<i><b>The following 2 sections are under development.</b></i>''' | '''<i><b>The following 2 sections are under development.</b></i>''' | ||
=== Updating a field === | |||
TBD | |||
=== Linking an entry === | === Linking an entry === | ||
| Line 122: | Line 137: | ||
:; 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. | :; 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 === | === Unlinking an entry === | ||
| Line 192: | 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 215: | Line 240: | ||
; [[Memento JavaScript Library]]: Memento JavaScript functions & objects<br/> | ; [[Memento JavaScript Library]]: Memento JavaScript functions & objects<br/> | ||
; [[Trigger Examples]]: Examples of trigger scripts for common needs | ; [[Trigger Examples]]: Examples of trigger scripts for common needs | ||
; [[How:Write scripts in JavaScript for Memento]]: Guidelines for writing JavaScript scripts for Memento | |||
[[Category:Spec]] | [[Category:en]] [[Category:Spec]] | ||