Memento JavaScript Library: Difference between revisions
mNo edit summary |
|||
(63 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
{{Stamp| | {{Stamp|2021-02-26|4.9.3|1.9.6}} | ||
Memento includes the capability for users to use JavaScript to accomplish complex tasks beyond the capabilities of the normal Memento user interface. Examples include JavaScript fields, Triggers, Actions, and Data Sources. The Memento JavaScript Library may be used to access Memento facilities. | Memento includes the capability for users to use JavaScript to accomplish complex tasks beyond the capabilities of the normal Memento user interface. Examples include JavaScript fields, Triggers, Actions, and Data Sources. The Memento JavaScript Library may be used to access Memento facilities (by all except JavaScript fields). | ||
To keep JavaScript fields both easy and safe for users, they may use only a portion of the library, and the nature of its use is simplified. Any limitations or differences related to JavaScript fields will be identified. | To keep JavaScript fields both easy and safe for users, they may use only a portion of the library, and the nature of its use is simplified. Any limitations or differences related to JavaScript fields will be identified. | ||
Line 7: | Line 7: | ||
== Libraries and Entries == | == Libraries and Entries == | ||
=== ''Library'' | === ''Library'' global functions === | ||
==== entry() ==== | ==== entry() ==== | ||
: Get the Entry object of the Event. For example, if the script is triggered by an Update Entry event, this | : Get the Entry object of the Event. For example, if the script is triggered by an Update Entry event, this method will return the entry being updated. | ||
: This Entry object is a clone of the actual Entry object. If the entry is saved, this object will become the actual one, but if cancel() is called, this entry clone, along with any changes the script may have performed, will be discarded. | : This Entry object is a clone of the actual Entry object. If the entry is saved, this object will become the actual one, but if cancel() is called, this entry clone, along with any changes the script may have performed, will be discarded. | ||
: This function is available to all Events and Phases, with the exception of '''Creating an entry''' > '''Opening an Entry Edit card'''; for this action, use the function ''entryDefault()''. | : This global function is available to all Events and Phases, with the exception of '''Creating an entry''' > '''Opening an Entry Edit card'''; for this action, use the global function ''entryDefault()''. | ||
:; Result: [[#Object Entry|'''''Entry''''' object]] — the current entry | :; Result: [[#Object Entry|'''''Entry''''' object]] — the current entry | ||
Line 22: | Line 22: | ||
:; Result: [[#Object DefaultEntry|'''''DefaultEntry''''' object]] | :; Result: [[#Object DefaultEntry|'''''DefaultEntry''''' object]] | ||
==== buildDefaultEntry() ==== | |||
: The buildDefaultEntry() method is designed to facilitate the customization of default field values during the '''Creating an entry''' or '''Updating an entry''' trigger events, specifically in the '''Opening an Entry Edit card''' phase. When used in the "Creating an entry" trigger event, the buildDefaultEntry() method applies default values for new, copied, or prefilled entries. | |||
:; Result: [[#Object DefaultEntry|'''''DefaultEntry''''' object]] | |||
: '''Properties''' | |||
: The buildDefaultEntry() method allows you to determine the method used by the user to create an entry. Use the following properties for this purpose: | |||
::; buildDefaultEntry().created: Indicates a new and empty entry. | |||
::; buildDefaultEntry().duplicated: Indicates a duplicate of an existing entry. | |||
::; buildDefaultEntry().prefilled: Indicates the creation of an entry based on a template. | |||
: '''Usage''' | |||
: The typical usage pattern involves invoking the set() method on the result of buildDefaultEntry() to specify the field name and its corresponding default value. | |||
:: <source lang="JavaScript"> | |||
buildDefaultEntry().set("Field name", "Field value"); | |||
</source> | |||
: If you want to set default values only when duplicating an entry, you can use the following example: | |||
:: <source lang="JavaScript"> | |||
if (buildDefaultEntry().duplicated) { | |||
buildDefaultEntry().set("Description", "Duplicated Entry") | |||
} | |||
</source> | |||
==== exit() ==== | ==== exit() ==== | ||
Line 41: | Line 66: | ||
=== Object ''Library'' === | === Object ''Library'' === | ||
This object provides access to library entries. You can work with the current library — the ''lib()'' — or any other library in the database — ''libByName()''. This function provides the ability to update existing entries and create new ones. | This object provides access to library entries. You can work with the current library — the ''lib()'' — or any other library in the database — ''libByName()''. This global function provides the ability to update existing entries and create new ones. | ||
==== ''Library'' | ==== ''Library'' methods ==== | ||
===== create(values) ===== | ===== create(values) ===== | ||
: Create a new entry in the library | : Create a new entry in the library | ||
: '''Argument''' | : '''Argument''' | ||
::; values: [https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object '''''Object'''''] containing the field values | ::; values: [https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object '''''Object'''''] containing the field values as its properties | ||
:; Result: [[#Object entry|'''''Entry''''' object]] — the new entry in the library | :; Result: [[#Object entry|'''''Entry''''' object]] — the new entry to create in the library | ||
===== entries() ===== | ===== entries() ===== | ||
: Get all the entries of the library | : Get all the entries of the library | ||
:; Result: Array object containing entries, sorted by the time of their creation, from newest to oldest | :; Result: Array object containing entries (Entry objects), sorted by the time of their creation, from newest to oldest | ||
===== fields() ===== | |||
: Get some of the fieldnames of the library | |||
:; Result: Array object containing the strings, in definition order. Only the names of the fields defined in the MAIN page and not appearing within a Subheader will be returned, as of Memento release 4.13. | |||
===== find(query) ===== | ===== find(query) ===== | ||
Line 68: | Line 97: | ||
===== findByKey(name) ===== | ===== findByKey(name) ===== | ||
: Search all entries by the | : Search all entries by the entry name. The library must be set for unique entry names. | ||
: '''Argument''' | : '''Argument''' | ||
::; name: the Entry | ::; name: the Entry name field value(s) | ||
:; Result: [[#Object Entry|'''''Entry''''' object]], if found. Otherwise, ''null''. | :; Result: an [[#Object Entry|'''''Entry''''' object]], if found. Otherwise, ''null''. | ||
===== linksTo(entry) ===== | ===== linksTo(entry) ===== | ||
Line 82: | Line 111: | ||
: Display the library | : Display the library | ||
==== ''Library'' | ==== ''Library'' properties ==== | ||
:; name: The name of the library | |||
:; title: The name of the library | :; title: The name of the library | ||
Line 90: | Line 120: | ||
This object holds an entry of the current library, allowing the setting of field values | This object holds an entry of the current library, allowing the setting of field values | ||
==== ''Entry'' | ==== ''Entry'' methods ==== | ||
===== field(name) ===== | ===== field(name) ===== | ||
Line 105: | Line 135: | ||
::; name: Name of the Link to Entry field to which to add the link | ::; name: Name of the Link to Entry field to which to add the link | ||
::; entry: Entry in the field's related library to which to link | ::; entry: Entry in the field's related library to which to link | ||
===== images(name) ===== | |||
: The images(name) method is designed to facilitate easy retrieval and manipulation of images associated with a specified field in the entry. | |||
: '''Arguments''' | |||
::; name: Name of the Image field | |||
: '''Return Value''' | |||
: An array of objects, each representing an image associated with the specified field. | |||
::; caption: Get or set the caption for the image. | |||
::; uri: Retrieve the URI (link) of the image. | |||
===== recalc() ===== | ===== recalc() ===== | ||
: Recalculate values of entry fields. | : Recalculate values of entry fields. | ||
===== trash() ===== | |||
: Moves an entry into the trash. | |||
===== untrash() ===== | |||
: Moves an entry out of the trash. | |||
===== set(name, value) ===== | ===== set(name, value) ===== | ||
: Set the value of the named field. Calling this method results in immediate writing of the value to the library. | : Set the value of the named field. Calling this method results in immediate writing of the value to the library. | ||
:'''Note:''' In the case where the field to be set is a Link To Entry field, the second argument should be the entry name of the entry to link to. If there are, in that library, multiple fields set as | :'''Note:''' In the case where the field to be set is a Link To Entry field, the second argument should be the entry name of the entry to link to. If there are, in that library, multiple fields set as the entry name, the entry name for the set() method is formed by separating the value of those fields by a comma (,) — not a comma and a space, but only a comma. | ||
: '''Arguments''' | : '''Arguments''' | ||
Line 130: | Line 176: | ||
::; entry: Entry in the field's related library identifying the link to be removed | ::; entry: Entry in the field's related library identifying the link to be removed | ||
==== ''Entry'' | ==== ''Entry'' properties ==== | ||
:; author: the id of the user who created the entry | :; author: the id of the user who created the entry | ||
:; creationTime: date & time the entry was created | :; creationTime: date & time the entry was created | ||
Line 145: | Line 191: | ||
Template with default values for a new entry. This feature is available specifically and only for the Event '''Creating an entry''' & Phase '''Opening an Entry Edit card'''. | Template with default values for a new entry. This feature is available specifically and only for the Event '''Creating an entry''' & Phase '''Opening an Entry Edit card'''. | ||
==== ''DefaultEntry'' | ==== ''DefaultEntry'' methods ==== | ||
===== set(name, value) ===== | ===== set(name, value) ===== | ||
Line 156: | Line 202: | ||
=== Library & Entry objects examples === | === Library & Entry objects examples === | ||
See '''[[Trigger Examples#Libraries | See '''[[Trigger Examples#Libraries examples]]'''. | ||
<br/> | <br/> | ||
----- | ----- | ||
Line 164: | Line 210: | ||
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 via a global function called ''file()''. | 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 via a global function called ''file()''. | ||
To work with the files, the library should have read/write file access. | To work with the files, the library should have read/write file access. Also, in the Android app, select a folder that your script will have access to. You can configure this folder in the script permission dialog. | ||
=== ''File'' | === ''File'' global functions === | ||
==== file(name) ==== | ==== file(name) ==== | ||
Line 172: | Line 218: | ||
: '''Argument''' | : '''Argument''' | ||
::; name: The name | ::; name: The name of the file in the chosen folder is accessible to scripts. In the Desktop app, you must specify the full file path. | ||
:; Result | :; Result | ||
Line 181: | Line 227: | ||
This object is returned by the global function ''file()'' and provides access to the requested file. After reading or writing, the file should be closed using the method ''close()''. | This object is returned by the global function ''file()'' and provides access to the requested file. After reading or writing, the file should be closed using the method ''close()''. | ||
==== ''File'' | ==== ''File'' methods ==== | ||
:; close(): Close the file. It can subsequently be reopened. | |||
:; getLineNumber(): Get the current line number | |||
::; Returns: The line number, or position, in the file | |||
:; readAll(): Reads all lines of the file, and then closes the file | :; readAll(): Reads all lines of the file, and then closes the file | ||
::; Returns: Array containing the lines of the file | ::; Returns: Array containing the lines of the file | ||
:; readChar(): Reads the next character from the file stream | |||
::; Returns: The character | |||
:; readLine(): Reads the next line from the file stream | :; readLine(): Reads the next line from the file stream | ||
Line 190: | Line 245: | ||
:; readLines(): Reads the remaining lines from the file stream | :; readLines(): Reads the remaining lines from the file stream | ||
::; Returns: Array containing the remaining lines of the file | ::; Returns: Array containing the remaining lines of the file | ||
:; write(text): Write string(s). Take a variable number of arguments, converts each argument to a string, and writes that string to the file stream. | :; write(text): Write string(s). Take a variable number of arguments, converts each argument to a string, and writes that string to the file stream. | ||
Line 198: | Line 250: | ||
:; writeLine(text): Write strings and a newline to the file stream | :; writeLine(text): Write strings and a newline to the file stream | ||
:; | :; appendMode(): Switch the file to append mode, allowing data to be added to the end of the file without overwriting existing content. | ||
==== ''File'' | ==== ''File'' properties ==== | ||
:; exists: true — if and only if the file exists; false otherwise | :; 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. | :; length: The length, in bytes, of the file, or 0L if the file does not exist. | ||
<br/> | <br/> | ||
=== Files | === Files examples === | ||
See '''[[Trigger Examples#Files | See '''[[Trigger Examples#Files examples]]'''. | ||
<br/> | <br/> | ||
----- | ----- | ||
Line 225: | Line 275: | ||
Interface for processing HTTP requests | Interface for processing HTTP requests | ||
==== ''Http'' | ==== ''Http'' methods ==== | ||
===== http() ===== | |||
: Get the Http object | |||
<br/> | |||
===== get(url) ===== | ===== get(url) ===== | ||
: Execute HTTP | : Execute HTTP GET request | ||
: '''Argument''' | : '''Argument''' | ||
::; url: HTTP address, starting with http or https | ::; url: HTTP address, starting with http:// or https:// | ||
: '''Result''' | |||
::; HttpResult: Object containing the result of the execution of the HTTP request | |||
<br/> | |||
===== post(url, body) ===== | |||
: Execute HTTP POST request | |||
: '''Arguments''' | |||
::; url: HTTP address, starting with http:// or https:// | |||
::; body: The text of the HTTP POST request | |||
: '''Result''' | : '''Result''' | ||
::; HttpResult: Object containing the result of the execution of the HTTP request | ::; HttpResult: Object containing the result of the execution of the HTTP request | ||
: '''Example''' | |||
:: <source lang="JavaScript"> | |||
var result = http().post("http://httpbin.org/post", "the body of the request message"); | |||
</source> | |||
<br/> | <br/> | ||
===== headers(info) ===== | |||
: Set up header | |||
'''Argument''' | |||
::; info: Header text | |||
: '''Result''' | |||
::; HttpResult: Object containing the result of the execution of the HTTP request | |||
: '''Example''' | |||
<source lang="JavaScript"> | |||
var http = http(); | |||
http.headers({"User-Agent": "My Super App"}); // Set up the header | |||
var result = http.get("http://httpbin.org/get"); // Do a GET | |||
var headerValue = result.header("etag"); // Get response header | |||
</source> | |||
=== Object ''HttpResult'' === | === Object ''HttpResult'' === | ||
Result of the execution of the HTTP request | Result of the execution of the HTTP request | ||
==== | ==== Properties ==== | ||
:; body: The response in text form | |||
:; code: HTTP code of the response, if the request is successful (usually 200). | :; code: HTTP code of the response, if the request is successful (usually 200). | ||
<br/> | <br/> | ||
=== Http | ==== ''Method'' ==== | ||
See '''[[Trigger Examples#Http | |||
===== header(tag) ===== | |||
'''Argument''' | |||
::; tag: ??? | |||
=== Http examples === | |||
See '''[[Trigger Examples#Http examples]]'''. | |||
<br/> | <br/> | ||
----- | ----- | ||
<br/> | <br/> | ||
== | == Performing email functions == | ||
=== ''Email'' global functions === | |||
==== email() ==== | |||
: Returns the system Email object. Methods of the Email object may be used to send email messages, among other things. See the [[#Object Email|'''''Email''''' object]]. | |||
=== Object ''Email'' === | |||
This object provides methods related to email. | |||
==== ''Email'' global functions ==== | |||
:; send(): Send an email message based on a provided Smtp configuration object and other arguments. | |||
:: '''Arguments''' | |||
:::; cfg: The EmailConfig object to use for this email message | |||
:::; to: The email address to which to send the email message | |||
:::; subject: Text for the "Subject:" line | |||
:::; message: Body text of the email message | |||
=== Object ''EmailConfig'' === | |||
==== ''EmailConfig'' properties ==== | |||
:; host: The SMTP server from which to base email requests | |||
:; port: The UDP port to use for email communications | |||
:; user: The user within the host in whose name to make email requests | |||
:; pass: The password for the user | |||
:; from: The email address for the email "From:" line | |||
=== | === Email example === | ||
Send an email message in the background | |||
<source lang="JavaScript"> | |||
// Send email example | |||
// You must use the Object to specify SMTP configuration: | |||
// SMTP server host, port, username, password, email address | |||
= | var cfg = {"host" : "smtp.example.com" , "port":25, | ||
"user":"username" , "pass":"password" , "from":"username@example.com"}; | |||
email().send(cfg , "to@email.com" , "Subject" , "Text"); | |||
</source> | |||
== Interaction with the system == | |||
=== ''System'' global functions === | |||
==== cancel() ==== | ==== cancel() ==== | ||
: Stop the system operation that caused the event. Many triggers can be a result of an 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. | : Stop the system operation that caused the event. Many triggers can be a result of an 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. | ||
==== guid() ==== | ==== guid() ==== | ||
Line 276: | Line 393: | ||
==== intent(action) ==== | ==== intent(action) ==== | ||
: Create an information exchange object — Intent. This function can send a request for action to another application. | : Create an information exchange object — Intent. This function can send a request for action to another application. | ||
: This function is available only on Android. | : '''This function is available only on Android.''' | ||
: '''Argument''' | : '''Argument''' | ||
::; action: Line that defines standard action (eg, view, pick) | ::; action: Line that defines standard action (eg, view, pick) | ||
Line 282: | Line 399: | ||
: After the object is received, the data will be added to it, and then sent via ''send()''. | : After the object is received, the data will be added to it, and then sent via ''send()''. | ||
: Android has many built-in actions. A list of these actions can be found [https://developer.android.com/reference/android/content/Intent.html '''here''']. | : Android has many built-in actions. A list of these actions can be found [https://developer.android.com/reference/android/content/Intent.html '''here''']. | ||
==== log(text) ==== | |||
: Write a line to the log file | |||
: '''Argument''' | |||
::; text: text to be written to the log | |||
==== message(text) ==== | |||
: Shows the user a brief notification | |||
: '''Argument''' | |||
::; text: Text of the notification | |||
==== dialog() ==== | |||
: Create a builder for constructing and displaying a dialog | |||
:; Result: [[#Object Dialog|'''''Dialog''''' object]] | |||
==== system() ==== | |||
: Obtain information about the system | |||
:; Result: [[#Object System|'''''System''''' object]] | |||
<br/> | <br/> | ||
Line 287: | Line 423: | ||
This object contains information about the system. | This object contains information about the system. | ||
==== ''System'' | ==== ''System'' global functions ==== | ||
:; exit(): End script execution | :; exit(): End script execution | ||
==== ''System'' | ==== ''System'' properties ==== | ||
:; os: Name of the operating system executing the script | :; os: Name of the operating system executing the script | ||
<br/> | |||
=== Object ''Dialog'' === | |||
The Dialog object provides a set of methods to configure and customize the appearance and behavior of the dialog. | |||
'''Usage''' | |||
To use the Dialog object, instantiate it using dialog() method and then chain the available methods to configure the dialog as needed. Finally, call the show() method to display the constructed dialog to the user. | |||
<source lang="javascript"> | |||
const myDialog = dialog() | |||
myDialog.title("Hello") | |||
.text("Welcome to our application.") | |||
.positiveButton("OK", () => { /* Handle positive button click */ }) | |||
.show(); | |||
</source> | |||
'''Methods''' | |||
:; title(string): Sets the title of the dialog. Accepts a string parameter that represents the title to be displayed. | |||
:; text(string): Sets the main text content of the dialog. Accepts a string parameter that represents the primary message or content of the dialog. | |||
:; view(ui object): Sets a custom view for the dialog. Accepts a [[Memento_JavaScript_UI|UI object]] that represents the custom view to be displayed within the dialog. | |||
:; positiveButton(text, function()): Configures the positive button of the dialog. Accepts two parameters: the text to be displayed on the button and the function to be executed when the button is clicked. | |||
:; negativeButton(text, function()): Configures the negative button of the dialog. Accepts two parameters: the text to be displayed on the button and the function to be executed when the button is clicked. | |||
:; neutralButton(text, function()): Configures the neutral button of the dialog. Accepts two parameters: the text to be displayed on the button and the function to be executed when the button is clicked. | |||
:; autoDismiss(bool): Sets whether the dialog should automatically dismiss when a button is clicked. Accepts a boolean parameter. If autoDismiss is set to false, the dialog will only close when a button function returns true. | |||
:; show(): Displays the configured dialog to the user. | |||
<br/> | <br/> | ||
Line 297: | Line 457: | ||
Information exchange object. This object is created by using the global function ''intent()''. | Information exchange object. This object is created by using the global function ''intent()''. | ||
==== ''Intent'' | ==== ''Intent'' methods ==== | ||
===== data(uri) ===== | ===== data(uri) ===== | ||
Line 303: | Line 463: | ||
: '''Argument''' | : '''Argument''' | ||
::; uri: URI referencing data to which the action will be applied. It can be contact ID, path to the file, phone number, etc. | ::; uri: URI referencing data to which the action will be applied. It can be contact ID, path to the file, phone number, etc. | ||
===== extra(key, value) ===== | ===== extra(key, value) ===== | ||
Line 320: | Line 475: | ||
::; key: key for additional data item | ::; key: key for additional data item | ||
::; value: value of additional data item | ::; value: value of additional data item | ||
===== mimeType(mime) ===== | |||
: Define MIME type of the data | |||
: '''Argument''' | |||
::; mime: MIME type of the data on which the operation will be performed | |||
===== send() ===== | ===== send() ===== | ||
Line 325: | Line 485: | ||
<br/> | <br/> | ||
=== System | === System examples === | ||
See '''[[Trigger Examples#System | See '''[[Trigger Examples#System examples]]'''. | ||
<br/> | <br/> | ||
----- | ----- | ||
Line 339: | Line 499: | ||
If the Contact field contains multiple contacts, use ''hasNext'' and ''next'' to retrieve them. | If the Contact field contains multiple contacts, use ''hasNext'' and ''next'' to retrieve them. | ||
==== JSContact | ==== JSContact methods ==== | ||
:; | :; call(): If the device is a phone, calls the primary phone number of this contact | ||
:; | :; sendEmail(subject, message): Sends an email message to the primary email address of this contact, with subject '''''subject''''' and message '''''message''''' (text string) | ||
:; sendSMS(message): If the device is a phone, sends the provided '''''message''''' (text string) as an SMS message to the primary phone number of this contact | :; sendSMS(message): If the device is a phone, sends the provided '''''message''''' (text string) as an SMS message to the primary phone number of this contact | ||
:; | :; show(): Opens the Contacts app for this contact | ||
==== JSContact | ==== JSContact properties ==== | ||
:; email: The primary email address of this contact | |||
:; fullName: The full name of this contact | :; fullName: The full name of this contact | ||
:; | :; hasNext: Returns TRUE if there is a next JSContact object, otherwise FALSE | ||
:; | :; next: Returns the next JSContact object, if there is one. | ||
:; | :; phone: The primary phone number of this contact | ||
<br/> | |||
=== Object ''JSGeolocation'' === | === Object ''JSGeolocation'' === | ||
Line 370: | Line 531: | ||
If the Location field contains multiple locations, use ''hasNext'' and ''next'' to retrieve them. | If the Location field contains multiple locations, use ''hasNext'' and ''next'' to retrieve them. | ||
==== JSGeolocation | ==== JSGeolocation properties ==== | ||
:; address: Address for this Location | |||
:; hasNext: Returns TRUE if there is a next JSGeolocation object, otherwise FALSE | |||
:; lat: Latitude, as a Real | :; lat: Latitude, as a Real | ||
:; lng: Longitude, as a Real | :; lng: Longitude, as a Real | ||
:; next: Returns the next JSGeolocation object, if there is one. | :; next: Returns the next JSGeolocation object, if there is one. | ||
Line 384: | Line 545: | ||
<br/> | <br/> | ||
=== Built-in Objects | === Built-in Objects examples === | ||
See '''[[Trigger Examples# | See '''[[Tips:Trigger Examples#Examples of built-in object use|Examples of built-in object use]]'''. | ||
<br/> | <br/> | ||
----- | ----- | ||
Line 391: | Line 552: | ||
== See also == | == See also == | ||
; [[ | ; [[Actions]]: Memento Actions | ||
; [[ | ; [[Data Sources]]: Memento Data Sources | ||
; [[Triggers]]: Memento Triggers | ; [[Triggers]]: Memento Triggers | ||
; [[Trigger Examples]]: Examples of Memento Triggers | ; [[Trigger Examples]]: Examples of Memento Triggers | ||
Line 402: | Line 563: | ||
----- | ----- | ||
<br/> | <br/> | ||
[[Category:Spec]] | |||
[[Category:en]] [[Category:Spec]] [[Category:Sc]] |
Latest revision as of 14:24, 6 March 2024
Memento includes the capability for users to use JavaScript to accomplish complex tasks beyond the capabilities of the normal Memento user interface. Examples include JavaScript fields, Triggers, Actions, and Data Sources. The Memento JavaScript Library may be used to access Memento facilities (by all except JavaScript fields).
To keep JavaScript fields both easy and safe for users, they may use only a portion of the library, and the nature of its use is simplified. Any limitations or differences related to JavaScript fields will be identified.
Libraries and Entries
Library global functions
entry()
- Get the Entry object of the Event. For example, if the script is triggered by an Update Entry event, this method will return the entry being updated.
- This Entry object is a clone of the actual Entry object. If the entry is saved, this object will become the actual one, but if cancel() is called, this entry clone, along with any changes the script may have performed, will be discarded.
- This global function is available to all Events and Phases, with the exception of Creating an entry > Opening an Entry Edit card; for this action, use the global function entryDefault().
- Result
- Entry object — the current entry
entryDefault()
- Get the Entry object containing the default field values for the entry not yet created. This feature is available specifically and only for the Event Creating an entry & Phase Opening an Entry Edit card.
- Result
- DefaultEntry object
buildDefaultEntry()
- The buildDefaultEntry() method is designed to facilitate the customization of default field values during the Creating an entry or Updating an entry trigger events, specifically in the Opening an Entry Edit card phase. When used in the "Creating an entry" trigger event, the buildDefaultEntry() method applies default values for new, copied, or prefilled entries.
- Result
- DefaultEntry object
- Properties
- The buildDefaultEntry() method allows you to determine the method used by the user to create an entry. Use the following properties for this purpose:
- buildDefaultEntry().created
- Indicates a new and empty entry.
- buildDefaultEntry().duplicated
- Indicates a duplicate of an existing entry.
- buildDefaultEntry().prefilled
- Indicates the creation of an entry based on a template.
- Usage
- The typical usage pattern involves invoking the set() method on the result of buildDefaultEntry() to specify the field name and its corresponding default value.
buildDefaultEntry().set("Field name", "Field value");
- If you want to set default values only when duplicating an entry, you can use the following example:
if (buildDefaultEntry().duplicated) { buildDefaultEntry().set("Description", "Duplicated Entry") }
exit()
- Stops script execution
lib()
- Get the library of the triggering event
- Result
- Library object — the current library
libByName(name)
- Find the library by name. Permission to use the library is required, based on security settings.
- Argument
- The name of the library to find
- Result
- Library object — the library identified by the argument name, if found. Otherwise null.
Object Library
This object provides access to library entries. You can work with the current library — the lib() — or any other library in the database — libByName(). This global function provides the ability to update existing entries and create new ones.
Library methods
create(values)
- Create a new entry in the library
- Argument
- values
- Object containing the field values as its properties
- Result
- Entry object — the new entry to create in the library
entries()
- Get all the entries of the library
- Result
- Array object containing entries (Entry objects), sorted by the time of their creation, from newest to oldest
fields()
- Get some of the fieldnames of the library
- Result
- Array object containing the strings, in definition order. Only the names of the fields defined in the MAIN page and not appearing within a Subheader will be returned, as of Memento release 4.13.
find(query)
- Search field values within entries in the library matching the given query. This search is similar to searching via Memento's user interface.
- Argument
- query
- the search string
- Result
- Array object containing matching entries. Entries are sorted by the time of their creation, from newest to oldest.
findById(id)
- Search all entries by entry ID.
- Argument
- id
- the ID string uniquely identifying the entry.
- Result
- Entry object, if found. Otherwise, null.
findByKey(name)
- Search all entries by the entry name. The library must be set for unique entry names.
- Argument
- name
- the Entry name field value(s)
- Result
- an Entry object, if found. Otherwise, null.
linksTo(entry)
Get entries in the library that contain a link to the specified entry.
- Arguments
- entry
- An entry to search for links to it.
- Result
- Array object containing entries.
show()
- Display the library
Library properties
- name
- The name of the library
- title
- The name of the library
Object Entry
This object holds an entry of the current library, allowing the setting of field values
Entry methods
field(name)
- Get the value of the named field
- Argument
- name
- name of the field
- Result
- The value of the field. The type of the result depends on the type of the field.
Field type | JavaScript object | Examples |
---|---|---|
Text , Hyperlink, Password, Phone, Email, Barcode, Radio buttons, Single-choice list, Calculation (string result) | String | "abc" |
Integer, Real number, Integer values, Rating, Currency, Calculation (number result) | Number | 42, 42.1 |
Date , DateTime, Time | Date | |
Checkbox (Boolean) | Boolean | true, false |
Checkboxes, Multiple-choice list | Array of strings | ["Shirts", "Pants", "Socks"] |
Image | Array of strings | ["file:///storage/emulated/0/DCIM/image01.png", "file:///storage/emulated/0/DCIM/image02.png"] |
Link to entry | Array of entries Each array element has a method field() for access to values of fields of entries of the linked library. Example: field("localField")[i].field("remoteField") |
[e1, e2, e3, ...] |
link(name, entry)
- Add a link — to a Link to Entry field in the current library — to an entry in the related library.
- Arguments
- name
- Name of the Link to Entry field to which to add the link
- entry
- Entry in the field's related library to which to link
images(name)
- The images(name) method is designed to facilitate easy retrieval and manipulation of images associated with a specified field in the entry.
- Arguments
- name
- Name of the Image field
- Return Value
- An array of objects, each representing an image associated with the specified field.
- caption
- Get or set the caption for the image.
- uri
- Retrieve the URI (link) of the image.
recalc()
- Recalculate values of entry fields.
trash()
- Moves an entry into the trash.
untrash()
- Moves an entry out of the trash.
set(name, value)
- Set the value of the named field. Calling this method results in immediate writing of the value to the library.
- Note: In the case where the field to be set is a Link To Entry field, the second argument should be the entry name of the entry to link to. If there are, in that library, multiple fields set as the entry name, the entry name for the set() method is formed by separating the value of those fields by a comma (,) — not a comma and a space, but only a comma.
- Arguments
- name
- name of the field
- value
- the value of the field
- For Multiple-choice List and Checkboxes fields, an array of strings supplies the values.
- For Link to Entry fields, an array of of strings — each of which may be a comma-separated list of field names — supplies the entry names of entries to which to link.
- For Link to File fields, an array of path names identifies the files to which to link.
show()
- Display the entry
unlink(name, entry)
- Remove a link — from a Link to Entry field in the current library — to an entry in the related library.
- Arguments
- name
- Name of the Link to Entry field from which to remove the link
- entry
- Entry in the field's related library identifying the link to be removed
Entry properties
- author
- the id of the user who created the entry
- creationTime
- date & time the entry was created
- deleted
- true, if the entry is deleted (it is in the Recycle Bin)
- description
- entry description
- favorites
- true, if the entry is in Favorites
- id
- entry identifier
- lastModifiedTime
- date & time the entry was last modified
- name
- entry name
- title
- entry name
Object DefaultEntry
Template with default values for a new entry. This feature is available specifically and only for the Event Creating an entry & Phase Opening an Entry Edit card.
DefaultEntry methods
set(name, value)
- Set the value of the field
- Arguments
- name
- the name of the field
- value
- the value of the field
Library & Entry objects examples
See Trigger Examples#Libraries examples.
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 are performed by the File object, which is obtained via a global function called file().
To work with the files, the library should have read/write file access. Also, in the Android app, select a folder that your script will have access to. You can configure this folder in the script permission dialog.
File global functions
file(name)
Open a file for read or write operations. If the file with the specified name does not exist yet, it will be created.
- Argument
- name
- The name of the file in the chosen folder is accessible to scripts. In the Desktop app, you must specify the full file path.
- Result
- File object
Object File
This object is returned by the global function file() and provides access to the requested file. After reading or writing, the file should be closed using the method close().
File methods
- close()
- Close the file. It can subsequently be reopened.
- getLineNumber()
- Get the current line number
- Returns
- The line number, or position, in the file
- readAll()
- Reads all lines of the file, and then closes the file
- Returns
- Array containing the lines of the file
- readChar()
- Reads the next character from the file stream
- Returns
- The character
- readLine()
- Reads the next line from the file stream
- Returns
- The line
- readLines()
- Reads the remaining lines from the file stream
- Returns
- Array containing the remaining lines of the file
- write(text)
- Write string(s). Take a variable number of arguments, converts each argument to a string, and writes that string to the file stream.
- writeLine(text)
- Write strings and a newline to the file stream
- appendMode()
- Switch the file to append mode, allowing data to be added to the end of the file without overwriting existing content.
File 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.
Files examples
See Trigger Examples#Files examples.
Processing an HTTP request
Scripts can send HTTP requests to Web services through their APIs. Processing for HTTP requests allows integration between Memento and the system. All file operations use the Http object, which works through global function http().
HTTP requests must fulfill two requirements:
- Script execution must be asynchronous, so HTTP requests go in the last Phase of an Event.
- The library should have the permission Network.
Object Http
Interface for processing HTTP requests
Http methods
http()
- Get the Http object
get(url)
- Execute HTTP GET request
- Argument
- url
- HTTP address, starting with http:// or https://
- Result
- HttpResult
- Object containing the result of the execution of the HTTP request
post(url, body)
- Execute HTTP POST request
- Arguments
- url
- HTTP address, starting with http:// or https://
- body
- The text of the HTTP POST request
- Result
- HttpResult
- Object containing the result of the execution of the HTTP request
- Example
var result = http().post("http://httpbin.org/post", "the body of the request message");
headers(info)
- Set up header
Argument
- info
- Header text
- Result
- HttpResult
- Object containing the result of the execution of the HTTP request
- Example
var http = http();
http.headers({"User-Agent": "My Super App"}); // Set up the header
var result = http.get("http://httpbin.org/get"); // Do a GET
var headerValue = result.header("etag"); // Get response header
Object HttpResult
Result of the execution of the HTTP request
Properties
- body
- The response in text form
- code
- HTTP code of the response, if the request is successful (usually 200).
Method
header(tag)
Argument
- tag
- ???
Http examples
See Trigger Examples#Http examples.
Performing email functions
Email global functions
email()
- Returns the system Email object. Methods of the Email object may be used to send email messages, among other things. See the Email object.
Object Email
This object provides methods related to email.
Email global functions
- send()
- Send an email message based on a provided Smtp configuration object and other arguments.
- Arguments
- cfg
- The EmailConfig object to use for this email message
- to
- The email address to which to send the email message
- subject
- Text for the "Subject:" line
- message
- Body text of the email message
Object EmailConfig
EmailConfig properties
- host
- The SMTP server from which to base email requests
- port
- The UDP port to use for email communications
- user
- The user within the host in whose name to make email requests
- pass
- The password for the user
- from
- The email address for the email "From:" line
Email example
Send an email message in the background
// Send email example
// You must use the Object to specify SMTP configuration:
// SMTP server host, port, username, password, email address
var cfg = {"host" : "smtp.example.com" , "port":25,
"user":"username" , "pass":"password" , "from":"username@example.com"};
email().send(cfg , "to@email.com" , "Subject" , "Text");
Interaction with the system
System global functions
cancel()
- Stop the system operation that caused the event. Many triggers can be a result of an 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.
guid()
- Generates random text identifier
- Result
- Random string identifier
intent(action)
- Create an information exchange object — Intent. This function can send a request for action to another application.
- This function is available only on Android.
- Argument
- action
- Line that defines standard action (eg, view, pick)
- Result
- Intent object — Information exchange object
- After the object is received, the data will be added to it, and then sent via send().
- Android has many built-in actions. A list of these actions can be found here.
log(text)
- Write a line to the log file
- Argument
- text
- text to be written to the log
message(text)
- Shows the user a brief notification
- Argument
- text
- Text of the notification
dialog()
- Create a builder for constructing and displaying a dialog
- Result
- Dialog object
system()
- Obtain information about the system
- Result
- System object
Object System
This object contains information about the system.
System global functions
- exit()
- End script execution
System properties
- os
- Name of the operating system executing the script
Object Dialog
The Dialog object provides a set of methods to configure and customize the appearance and behavior of the dialog.
Usage
To use the Dialog object, instantiate it using dialog() method and then chain the available methods to configure the dialog as needed. Finally, call the show() method to display the constructed dialog to the user.
const myDialog = dialog()
myDialog.title("Hello")
.text("Welcome to our application.")
.positiveButton("OK", () => { /* Handle positive button click */ })
.show();
Methods
- title(string)
- Sets the title of the dialog. Accepts a string parameter that represents the title to be displayed.
- text(string)
- Sets the main text content of the dialog. Accepts a string parameter that represents the primary message or content of the dialog.
- view(ui object)
- Sets a custom view for the dialog. Accepts a UI object that represents the custom view to be displayed within the dialog.
- positiveButton(text, function())
- Configures the positive button of the dialog. Accepts two parameters: the text to be displayed on the button and the function to be executed when the button is clicked.
- negativeButton(text, function())
- Configures the negative button of the dialog. Accepts two parameters: the text to be displayed on the button and the function to be executed when the button is clicked.
- neutralButton(text, function())
- Configures the neutral button of the dialog. Accepts two parameters: the text to be displayed on the button and the function to be executed when the button is clicked.
- autoDismiss(bool)
- Sets whether the dialog should automatically dismiss when a button is clicked. Accepts a boolean parameter. If autoDismiss is set to false, the dialog will only close when a button function returns true.
- show()
- Displays the configured dialog to the user.
Object Intent
Information exchange object. This object is created by using the global function intent().
Intent methods
data(uri)
- Define URI to reference the data
- Argument
- uri
- URI referencing data to which the action will be applied. It can be contact ID, path to the file, phone number, etc.
extra(key, value)
- Define additional data as key-value pairs, as necessary for execution of the required action. Similar to how URI data can be required for certain actions, other actions may require extra data in this format.
- Arguments
- key
- key for additional data item
- value
- value of additional data item
extraLong(key, value)
- Define additional data as key-value pairs, where data type needs to be Long
- Arguments
- key
- key for additional data item
- value
- value of additional data item
mimeType(mime)
- Define MIME type of the data
- Argument
- mime
- MIME type of the data on which the operation will be performed
send()
- Send a message
System examples
See Trigger Examples#System examples.
Built-in objects for certain Memento field types
Object JSContact
This object contains the information stored within a Contact field and provides properties and methods for use in accessing and manipulating this information.
When an Entry object's field() method is called, if the Memento field type is Contact, a JSContact object is returned.
If the Contact field contains multiple contacts, use hasNext and next to retrieve them.
JSContact methods
- call()
- If the device is a phone, calls the primary phone number of this contact
- sendEmail(subject, message)
- Sends an email message to the primary email address of this contact, with subject subject and message message (text string)
- sendSMS(message)
- If the device is a phone, sends the provided message (text string) as an SMS message to the primary phone number of this contact
- show()
- Opens the Contacts app for this contact
JSContact properties
- The primary email address of this contact
- fullName
- The full name of this contact
- hasNext
- Returns TRUE if there is a next JSContact object, otherwise FALSE
- next
- Returns the next JSContact object, if there is one.
- phone
- The primary phone number of this contact
Object JSGeolocation
This object contains the information stored within a Location field and provides properties and methods for use in accessing and manipulating this information.
When an Entry object's field() method is called, if the Memento field type is Location, a JSGeolocation object is returned.
If the Location field contains multiple locations, use hasNext and next to retrieve them.
JSGeolocation properties
- address
- Address for this Location
- hasNext
- Returns TRUE if there is a next JSGeolocation object, otherwise FALSE
- lat
- Latitude, as a Real
- lng
- Longitude, as a Real
- next
- Returns the next JSGeolocation object, if there is one.
Built-in Objects examples
See Examples of built-in object use.
See also
- Actions
- Memento Actions
- Data Sources
- Memento Data Sources
- Triggers
- Memento Triggers
- Trigger Examples
- Examples of Memento Triggers
- Tips:Using JavaScript in Memento
- Tips for using JavaScript in Memento
JavaScript links
W3Schools | |
---|---|
JavaScript Tutorial | A pleasant, fairly complete, and useful tutorial on JavaScript Best on a computer or tablet in landscape. On a phone or tablet in portrait, scroll to the bottom for navigation. |
Mozilla Developer Network | |
JavaScript Guide | Shows you how to use JavaScript, gives an overview of the language, and presents its capabilities & features |
JavaScript Reference | The entire JavaScript language described in detail |
Introduction to JavaScript | Introduces JavaScript and discusses some of its fundamental concepts |
JavaScript Tutorial | A re-introduction. JavaScript is often derided as being a toy, but beneath its simplicity, powerful language features await. |
JavaScript 1.7 | The JavaScript release upon which Memento is currently based |
About JavaScript | Jumping off point in learning about JavaScript |