Triggers: Difference between revisions

Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 175: Line 175:
-----
-----
<br/>
<br/>
== 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''' &mdash; 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
:: [[#Object File|'''''File''''' object]]
<br/>
=== 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 &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.
:; getLineNumber: Get the current line number
::; Returns: The line number, or position, in the file
<br/>
=== Files Examples ===
See '''[[Trigger Examples#Files Examples]]'''.
<br/>
-----
<br/>
== 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'''.
<br/>
=== Object ''Http'' ===
Interface for processing HTTP requests
==== ''Http'' Methods ====
===== get(url) =====
: Execute HTTP get request
:; Argument: '''url''' &mdash; HTTP address, starting with http or https
:; Result: '''HttpResult''' &mdash; Object containing the result of the execution of the HTTP request
<br/>
=== Object ''HttpResult'' ===
Result of the execution of the HTTP request
==== ''HttpResult'' Properties ====
: '''code''' &mdash; HTTP code of the response, if the request is successful (usually 200).
: '''body''' &mdash; The response in text form
<br/>
=== Http Examples ===
See '''[[Trigger Examples#Http Examples]]'''.
<br/>
-----
<br/>
== Interaction with the System ==
=== ''System'' Global Functions ===
==== message(text) ====
: Shows the user a brief notification
:; Argument: '''text''' &mdash; 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: [[#Object System|'''''System''''' object]]
==== log(text) ====
: Write a line to the log file
:; Argument: '''text''' &mdash; text to be written to the log
==== guid() ====
: Generates random text identifier
:; Result: Random string identifier
==== intent(action) ====
: 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.
:; Argument: '''action''' &mdash; Line that defines standard action (eg, view, pick)
:; Result: [[#Object Intent|'''''Intent''''' object]] &mdash; 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 [https://developer.android.com/reference/android/content/Intent.html '''here'''].
<br/>
=== Object ''System'' ===
This object contains information about the system.
==== ''System'' Properties ====
: '''os''' &mdash; Name of the operating system executing the script
<br/>
=== 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 &mdash; 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 &mdash; 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
<br/>
=== System Examples ===
See '''[[Trigger Examples#System Examples]]'''.
<br/>
-----
<br/>
== 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
:; email: 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.
<br/>
=== 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.
<br/>
-----
<br/>
=== Built-in Objects Examples ===
See '''[[Trigger Examples#Built-in Objects Examples]]'''.
<br/>
-----
<br/>
== See also ==
{| class="wikitable" style="font-size:120%"
|-
| Examples of trigger scripts || '''[[Trigger Examples]]'''
|-
|}
<br/>
-----
<br/>
== JavaScript links ==
{{Template:JavaScriptLinks}}


[[Category:Spec]]
[[Category:Spec]]
Retrieved from "https://wiki.mementodatabase.com/index.php?title=Triggers"