Memento JavaScript Library
{Stamp|2017-02-28|4.3.0|1.1.0}
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.
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 function 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 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().
- 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
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 function provides the ability to update existing entries and create new ones.
Library Methods
entries()
- Get all the entries of the library
- Result
- Array object containing entries, sorted by the time of their creation, from newest to oldest
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.
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
- Result
- Entry object, if found. Otherwise, null.
create(values)
- Create a new entry in the library
- Argument
- values — [Object containing the field values
- Result
- Entry object — the new entry in the library
show()
- Display the library
Library Properties
- 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
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 (,) — not a comma and a space, but only a comma.
- Arguments
- name — name of the field
- value — the value of the field
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, ...] |
show()
- Display the entry
Entry Properties
- name — entry name
- title — entry name
- description — entry description
- favorites — true, if the entry is in Favorites
- deleted — true, if the record is deleted (it is in the Recycle Bin)
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
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.
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 and the full path to the file. For example, if the file is located on the SD card, the path should be something like /sdcard/example.txt.
- 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
- readAll()
- Reads all lines of the file, and then closes the file
- Returns
- Array containing the lines of the file
- 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
- 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.
- writeLine(text)
- Write strings and a newline to the file stream
- close()
- Close the file. It can subsequently be reopened.
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.
- getLineNumber
- Get the current line number
- Returns
- The line number, or position, in the file
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
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
Object HttpResult
Result of the execution of the HTTP request
HttpResult Properties
- code — HTTP code of the response, if the request is successful (usually 200).
- body — The response in text form
Http Examples
See Trigger Examples#Http Examples.
Interaction with the System
System Global Functions
message(text)
- Shows the user a brief notification
- Argument
- text — Text of the notification
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.
system()
- Obtain information about the system
- Result
- System object
log(text)
- Write a line to the log file
- Argument
- text — text to be written to the log
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.
Object System
This object contains information about the system.
System Properties
- os — Name of the operating system executing the script
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.
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)
- 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 and value
extraLong(key, value)
- Define additional data as key-value pairs, where data type needs to be Long
- Arguments
- key and value
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
- show()
- Opens the Contacts app for this contact
- call()
- If the device is a phone, calls 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)
JSContact Properties
- fullName
- The full name of this contact
- phone
- The primary phone number of this contact
- The primary email address 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.
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
- lat
- Latitude, 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.
Built-in Objects Examples
See Trigger Examples#Built-in Objects Examples.
See also
Examples of trigger scripts | Trigger Examples |
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 |
Libraries Examples
See Trigger Examples#Libraries Examples.