Memento JavaScript Library: Difference between revisions

Jump to navigation Jump to search

Memento JavaScript Library (view source)

Revision as of 06:44, 26 February 2021

3,418 bytes added ,  26 February 2021
m
no edit summary
mNo edit summary
mNo edit summary
(36 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Stamp|2017-03-04|4.3.0|1.1.0}}
{{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.


== Libraries and Entries ==
== Libraries and Entries ==
=== ''Library'' Global Functions ===
 
=== ''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 function will return the entry being updated.
: 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 21: Line 22:


:; Result: [[#Object DefaultEntry|'''''DefaultEntry''''' object]]
:; Result: [[#Object DefaultEntry|'''''DefaultEntry''''' object]]
==== exit() ====
: Stops script execution


==== lib() ====
==== lib() ====
Line 33: Line 37:


:; Result: [[#Object Library|'''''Library''''' object]] — the library identified by the argument ''name'', if found. Otherwise ''null''.
:; Result: [[#Object Library|'''''Library''''' object]] — the library identified by the argument ''name'', if found. Otherwise ''null''.
==== exit() ====
: Stops script execution


<br/>
<br/>


=== Object ''Library'' ===
=== Object ''Library'' ===
This object provides access to library entries. You can work with the current library &mdash; the ''lib()'' &mdash; or any other library in the database &mdash; ''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 &mdash; the ''lib()'' &mdash; or any other library in the database &mdash; ''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: [https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object '''''Object'''''] containing the field values
:; Result: [[#Object entry|'''''Entry''''' object]] &mdash; the new entry in the library


==== ''Library'' Methods ====
===== entries() =====
===== entries() =====
: Get all the entries of the library
: Get all the entries of the library
Line 53: Line 61:
:; Result: Array object containing matching entries. Entries are sorted by the time of their creation, from newest to oldest.
:; Result: Array object containing matching entries. Entries are sorted by the time of their creation, from newest to oldest.


===== findByKey(name) =====
===== findById(id) =====
: Search all entries by the Entry Name. The library must be set for unique Entry Names.
: Search all entries by entry ID.
: '''Argument'''
: '''Argument'''
::; name: the Entry Name field value
::; id: the ID string uniquely identifying the entry.
:; Result: [[#Object Entry|'''''Entry''''' object]], if found. Otherwise, ''null''.
:; Result: [[#Object Entry|'''''Entry''''' object]], if found. Otherwise, ''null''.


===== create(values) =====
===== findByKey(name) =====
: Create a new entry in the library
: Search all entries by the entry name. The library must be set for unique entry names.
: '''Argument'''
: '''Argument'''
::; values: [https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object '''''Object'''''] containing the field values
::; name: the Entry name field value(s)
:; Result: [[#Object entry|'''''Entry''''' object]] &mdash; the new entry in the library
:; Result: an [[#Object Entry|'''''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() =====
===== show() =====
: Display the library
: Display the library


==== ''Library'' Properties ====
==== ''Library'' properties ====
:; name: The name of the library
:; title: The name of the library
:; title: The name of the library


Line 76: Line 91:
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'' Methods ====
==== ''Entry'' methods ====
===== 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 Entry Name, the entry name for the set() method is formed by separating the value of those fields by a comma (,) &mdash; 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.


===== field(name) =====
===== field(name) =====
Line 94: Line 100:


::{{FieldTypeReturnValues}}
::{{FieldTypeReturnValues}}
===== show() =====
: Display the entry


===== link(name, entry) =====
===== link(name, entry) =====
Line 103: Line 106:
::; 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
===== 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 (,) &mdash; 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 &mdash; each of which may be a comma-separated list of field names &mdash; 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) =====
===== unlink(name, entry) =====
Line 110: Line 137:
::; 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'' Properties ====
==== ''Entry'' properties ====
:; name: entry name
:; author: the id of the user who created the entry
:; title: entry name
:; creationTime: date & time the entry was created
:; deleted: true, if the entry is deleted (it is in the Recycle Bin)
:; description: entry description
:; description: entry description
:; favorites: true, if the entry is in Favorites
:; favorites: true, if the entry is in Favorites
:; deleted: true, if the entry is deleted (it is in the Recycle Bin)
:; id: entry identifier
:; author: the id of the user who created the entry
:; creationTime: date & time the entry was created
:; lastModifiedTime: date & time the entry was last modified
:; lastModifiedTime: date & time the entry was last modified
:; name: entry name
:; title: entry name
<br/>
<br/>


Line 124: Line 152:
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'' Methods ====
==== ''DefaultEntry'' methods ====
 
===== set(name, value) =====
===== set(name, value) =====
: Set the value of the field
: Set the value of the field
Line 134: Line 163:


=== Library & Entry objects examples ===
=== Library & Entry objects examples ===
See '''[[Trigger Examples#Libraries Examples]]'''.
See '''[[Trigger Examples#Libraries examples]]'''.
<br/>
<br/>
-----
-----
Line 144: Line 173:
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.


=== ''File'' Global Functions ===
=== ''File'' global functions ===
 
==== file(name) ====
==== 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.
Open a file for read or write operations. If the file with the specified name does not exist yet, it will be created.
Line 158: Line 188:
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'' Methods ====
==== ''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 167: Line 206:
:; 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
:; readChar(): Reads the next character from the file stream
::; Returns: The character


:; 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 175: Line 211:
:; writeLine(text): Write strings and a newline to the file stream
:; writeLine(text): Write strings and a newline to the file stream


:; close(): Close the file. It can subsequently be reopened.
==== ''File'' properties ====
 
==== ''File'' Properties ====
:; exists: true &mdash; if and only if the file exists; false otherwise
:; exists: true &mdash; 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.  
:; getLineNumber: Get the current line number
::; Returns: The line number, or position, in the file
<br/>
<br/>


=== Files Examples ===
=== Files examples ===
See '''[[Trigger Examples#Files Examples]]'''.
See '''[[Trigger Examples#Files examples]]'''.
<br/>
<br/>
-----
-----
Line 202: Line 234:
Interface for processing HTTP requests
Interface for processing HTTP requests


==== ''Http'' Methods ====
==== ''Http'' methods ====
 
===== get(url) =====
===== get(url) =====
: Execute HTTP get request
: Execute HTTP GET request
: '''Argument'''
: '''Argument'''
::; url: HTTP address, starting with http or https
::; url: HTTP address, starting with http:// or https://
: '''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
<br/>
<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'''
::; 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/>
===== 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


==== ''HttpResult'' Properties ====
==== 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).
:; body: The response in text form
<br/>
<br/>


=== Http Examples ===
==== ''Method'' ====
See '''[[Trigger Examples#Http Examples]]'''.
 
===== header(tag) =====
'''Argument'''
::; tag: ???
 
=== Http examples ===
See '''[[Trigger Examples#Http examples]]'''.
<br/>
<br/>
-----
-----
<br/>
<br/>


== Interaction with the System ==
== Performing email functions ==
=== ''System'' Global Functions ===
 
==== message(text) ====
=== ''Email'' global functions ===
: Shows the user a brief notification
 
: '''Argument'''
==== email() ====
::; text: Text of the notification
: 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.
==== system() ====
: Obtain information about the system
:; Result: [[#Object System|'''''System''''' object]]
==== log(text) ====
: Write a line to the log file
: '''Argument'''
::; text: text to be written to the log


==== guid() ====
==== guid() ====
Line 256: Line 354:
: 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
==== system() ====
: Obtain information about the system
:; Result: [[#Object System|'''''System''''' object]]
<br/>
<br/>


Line 261: Line 374:
This object contains information about the system.
This object contains information about the system.


==== ''System'' Global Functions ====
==== ''System'' global functions ====
:; exit(): End script execution
:; exit(): End script execution


==== ''System'' Properties ====
==== ''System'' properties ====
:; os: Name of the operating system executing the script
:; os: Name of the operating system executing the script
<br/>
<br/>
Line 271: Line 384:
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'' Methods ====
==== ''Intent'' methods ====
 
===== data(uri) =====
===== data(uri) =====
: Define URI to reference the data
: Define URI to reference the data
: '''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.
===== mimeType(mime) =====
: Define MIME type of the data
: '''Argument'''
::; mime: MIME type of the data on which the operation will be performed


===== extra(key, value) =====
===== extra(key, value) =====
Line 293: Line 402:
::; 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 298: Line 412:
<br/>
<br/>


=== System Examples ===
=== System examples ===
See '''[[Trigger Examples#System Examples]]'''.
See '''[[Trigger Examples#System examples]]'''.
<br/>
<br/>
-----
-----
Line 312: Line 426:
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 Methods ====
==== JSContact methods ====


:; show(): Opens the Contacts app for this contact
:; call(): If the device is a phone, calls the primary phone number of this contact


:; 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


:; sendEmail(subject, message): Sends an email message to the primary email address of this contact, with subject '''''subject''''' and message '''''message''''' (text string)
:; show(): Opens the Contacts app for this contact
 
==== JSContact properties ====


==== JSContact Properties ====
:; email: The primary email address of this contact


:; fullName: The full name of this contact
:; fullName: The full name of this contact


:; phone: The primary phone number of this contact
:; hasNext: Returns TRUE if there is a next JSContact object, otherwise FALSE


:; email: The primary email address of this contact
:; next: Returns the next JSContact object, if there is one.


:;hasNext: Returns TRUE if there is a next JSContact object, otherwise FALSE
:; phone: The primary phone number of this contact


:;next: Returns the next JSContact object, if there is one.
<br/>


<br/>
=== Object ''JSGeolocation'' ===
=== Object ''JSGeolocation'' ===


Line 343: Line 458:
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 Properties ====
==== 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
:; address: Address for this Location
:; hasNext: Returns TRUE if there is a next JSGeolocation object, otherwise FALSE


:; next: Returns the next JSGeolocation object, if there is one.  
:; next: Returns the next JSGeolocation object, if there is one.  
Line 357: Line 472:
<br/>
<br/>


=== Built-in Objects Examples ===
=== Built-in Objects examples ===
See '''[[Trigger Examples#Built-in Objects Examples]]'''.
See '''[[Trigger Examples#Built-in Objects examples]]'''.
<br/>
<br/>
-----
-----
Retrieved from "https://wiki.mementodatabase.com/index.php?title=Special:MobileDiff/2336...2976"

Navigation menu