Memento JavaScript Library: Difference between revisions

From Memento Database Wiki
Jump to navigation Jump to search
mNo edit summary
Tags: Mobile edit Mobile web edit
(29 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Stamp|2018-04-07|4.4.5|1.3.5}}
{{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'' 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 41: Line 41:


=== 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'' Methods ====
==== ''Library'' methods ====


===== create(values) =====
===== create(values) =====
Line 68: Line 68:


===== findByKey(name) =====
===== findByKey(name) =====
: Search all entries by the Entry Name. The library must be set for unique Entry Names.
: Search all entries by the entry name. The library must be set for unique entry names.
: '''Argument'''
: '''Argument'''
::; name: the Entry Name field value
::; 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 82:
: 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 90: 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 ====


===== field(name) =====
===== field(name) =====
Line 108: Line 109:
===== 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 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.
:'''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 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 ====
:; 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 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) =====
Line 156: Line 163:


=== Library & Entry objects examples ===
=== Library & Entry objects examples ===
See '''[[Trigger Examples#Libraries Examples]]'''.
See '''[[Trigger Examples#Libraries examples]]'''.
<br/>
<br/>
-----
-----
Line 166: 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) ====
Line 181: 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.
:; close(): Close the file. It can subsequently be reopened.
Line 204: Line 211:
:; writeLine(text): Write strings and a newline to the file stream
:; writeLine(text): Write strings and a newline to the file stream


==== ''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.  
<br/>
<br/>


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


==== ''Http'' Methods ====
==== ''Http'' methods ====
 
===== http() =====
: Get the Http object
<br/>


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


=== ''System'' Global Functions ===
=== 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


==== message(text) ====
var cfg = {"host" : "smtp.example.com" , "port":25,
: Shows the user a brief notification
"user":"username" , "pass":"password" , "from":"username@example.com"};
: '''Argument'''
email().send(cfg , "to@email.com" , "Subject" , "Text");
::; text: Text of the notification
</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 278: Line 352:
==== intent(action) ====
==== intent(action) ====
: Create an information exchange object &mdash; Intent. This function can send a request for action to another application.
: Create an information exchange object &mdash; 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 284: Line 358:
: 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 289: Line 378:
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 299: Line 388:
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) =====
Line 305: Line 394:
: '''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 322: Line 406:
::; 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 327: Line 416:
<br/>
<br/>


=== System Examples ===
=== System examples ===
See '''[[Trigger Examples#System Examples]]'''.
See '''[[Trigger Examples#System examples]]'''.
<br/>
<br/>
-----
-----
Line 341: Line 430:
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 372: Line 462:
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 386: Line 476:
<br/>
<br/>


=== Built-in Objects Examples ===
=== Built-in Objects examples ===
See '''[[Trigger Examples#Built-in Objects Examples]]'''.
See '''[[Tips:Trigger Examples#Examples of built-in object use|Examples of built-in object use]]'''.
<br/>
<br/>
-----
-----
Line 393: Line 483:


== See also ==
== See also ==
; [[Script Actions]]: Memento Actions
; [[Actions]]: Memento Actions
; [[Script Data Sources]]: Memento Data Sources
; [[Data Sources]]: Memento Data Sources
; [[Triggers]]: Memento Triggers
; [[Triggers]]: Memento Triggers
; [[Trigger Examples]]: Examples of Memento Triggers
; [[Trigger Examples]]: Examples of Memento Triggers
Line 404: Line 494:
-----
-----
<br/>
<br/>
[[Category:Spec]]
 
[[Category:en]] [[Category:Spec]]

Revision as of 08:10, 4 March 2022

« Page as of 2021-02-26, editions Mobile 4.9.3, Desktop 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 (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

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
Result
Entry object — the new entry in the library
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.
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 Return Values
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
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.

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

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

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:

  1. Script execution must be asynchronous, so HTTP requests go in the last Phase of an Event.
  2. 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

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

email
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