Tips:Using JavaScript in Memento: Difference between revisions
mNo edit summary |
|||
(36 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
{{Stamp| | {{Stamp|2023-08-12|5.0|2.0}} | ||
{{BannerMenu}} | |||
{{PageTitle|Tips<br/>Using JavaScript in Memento}} | |||
These are tips & techniques for using JavaScript for expressions in JavaScript fields and for scripts in triggers. | |||
== Field tips == | |||
Tips for calling ''field()'' for various field types. | |||
{{FieldTypeReturnValues}} | |||
== | === Simple fields === | ||
Fields that function as JavaScript type String, Number, Boolean, and Date operate in a direct manner. For example: | |||
{| | |||
! JavaScript field | |||
|- | |||
|<source lang="JavaScript"> | |||
field("linkedLib.integerField")*100 | |||
</source> | |||
|- | |||
! Trigger script | |||
|- | |||
|<source lang="JavaScript"> | |||
entry().set("percent", entry().field("linkedLib.integerField")*100); | |||
</source> | |||
|} | |||
[[ | ==== Date & Time fields ==== | ||
JavaScript Date & time functions expect & return time '''in milliseconds'''. This differs from Calculation fields, which use seconds. | |||
Also, Memento includes an optional JavaScript library '''moment.js''' that provides flexible formatting of dates and times. For a summary of this library, see [http://momentjs.com '''http://momentjs.com''']. For extensive details, see [http://momentjs.com/docs '''http://momentjs.com/docs''']. Skip over the first section "Where to Use It".<br/> Note that the particular library included in Memento at this time is called moment.min.js. | |||
Also, see '''[[Date field]]''', '''[[DateTime field]]''', or '''[[Time field]]''' for general information about the Memento user interface for dates & times. | |||
=== Multiple-choice fields === | |||
The ''field()'' function returns an array of selected items from multiple-choice (Checkboxes & Multiple-choice list) fields. Therefore, if a comma-separated list of selections is desired for the result of a JavaScript field expression, it is necessary to fetch the items from the array and combine them into a string, separated by commas. This is easily done with the array method ''join()''. | |||
==== Getting a comma-separated list of checked items from a multiple-choice field ==== | |||
{| | |||
! JavaScript field | |||
|- | |||
|<source lang="JavaScript"> | |||
field("Menu Choices").join() | |||
</source> | |||
|} | |||
This solution is needed for trigger scripts that want to use such a comma-separated string, such as for the ''set()'' method of the Entry object. | |||
{| | |||
! Trigger script | |||
|- | |||
|<source lang="JavaScript"> | |||
entry().set("menuSelections"), entry().field("remoteLibrary.menuChoices").join()); | |||
</source> | |||
|} | |||
== JavaScript | ==== Handling checked items individually ==== | ||
If the trigger script needs to handle each of the choices individually, it can be done as follows: | |||
{| | |||
! Trigger script | |||
|- | |||
|<source lang="JavaScript"> | |||
var e = entry(), items = e.field("remoteLibrary.menuChoices"); | |||
for (var item in items) { | |||
// Handle each item (items[item]) here | |||
} | |||
</source> | |||
=== Link to Entry fields === | === Link to Entry fields === | ||
The Link to Entry field has its own structure, unique among the field types. | |||
: field | |||
{| | ==== Using ''field()'' to access the value of local and remote field values ==== | ||
! JavaScript field | : '''Argument''' | ||
:# The name of the field whose value you want | |||
: '''Returns | |||
:: An array of Entry objects. | |||
:To access fields in the linked library, use: | |||
:{| | |||
! JavaScript field | |||
|- | |- | ||
|<source lang="JavaScript"> | |<source lang="JavaScript"> | ||
Line 24: | Line 83: | ||
} | } | ||
</source> | </source> | ||
|- | |||
! Trigger | |||
|- | |||
|<source lang="JavaScript"> | |<source lang="JavaScript"> | ||
var e = entry(), links = e.field("Link field name"); | var e = entry(), links = e.field("Link field name"); | ||
Line 32: | Line 94: | ||
</source> | </source> | ||
|} | |} | ||
<br/> | |||
==== Using ''set()'' in a trigger to set the value of a local field ==== | |||
: '''Arguments''' | |||
:# Name of the field whose value is to be set | |||
:# Comma-separated list of Entry Names | |||
: To set a link field to point to an entry of another library and set another link field to point to two entries, use: | |||
{| | |||
! Trigger | |||
|- | |||
|<source lang="JavaScript"> | |||
var e = entry(); | |||
e.set("First link", "InterOpera Group"); | |||
e.set("Second link", "Mozilla,Google"); | |||
</source> | |||
|} | |||
<br/> | |||
==== To copy a link's value to another link ==== | |||
:* The remote library must be set to use unique Entry Names. | |||
:* Both links must point to the same library | |||
{| | |||
! Trigger | |||
|- | |||
|<source lang="JavaScript"> | |||
var e = entry(), | |||
library = "Software firms", | |||
from = "First link", | |||
to = "Second link", | |||
lib = libByName(library); | |||
if (lib != null) { | |||
// Copy the link | |||
var entryNames = [], | |||
entries = e.field(from); | |||
for (var i in entries) | |||
entryNames.push(entries[i].title); | |||
e.set(to, entryNames.join()); | |||
} | |||
</source> | |||
|} | |||
== How Trigger & JavaScript field scripts differ == | |||
You'll notice in this page that the code for JavaScript fields and that for triggers are very similar, but also that they different. Here's how they are different: | |||
=== Context === | |||
* Context is set for you in a JavaScript field, and that context is the current entry. So, if you call ''field()'', that implicitly invokes the ''field()'' function on the current entry. | |||
* Context is not set in a trigger, so only global functions are initially available, and using those, you can set up context for functions you want to call on the objects you're interested in. | |||
{| | {| | ||
! JavaScript field | ! JavaScript field | ||
|- | |- | ||
|<source lang="JavaScript"> | |<source lang="JavaScript"> | ||
field("Fraction") * 100 | |||
</source> | </source> | ||
|- | |- | ||
Line 47: | Line 151: | ||
|- | |- | ||
|<source lang="JavaScript"> | |<source lang="JavaScript"> | ||
var e = entry(), | var e = entry(), lib = lib(); | ||
message("Library " + lib.title + ", entry " + e.title); | |||
</source> | </source> | ||
|} | |} | ||
== | === Semicolons === | ||
In JavaScript, the use of semicolons is theoretically optional. In practice, however, without their use, problems arise in certain cases, and it is strongly recommended to use them to guarantee clarity and correctness. | |||
However, if you aren't sure about such things, you can omit them, and most of the time there will be no consequences, particularly in the case of JavaScript fields, in which the requirement is only to state about expression. Most JavaScript fields are just one or two lines long, so the need for statement terminators is minimal. | |||
Trigger scripts are straight JavaScript, so the code should obey strict JavaScript rules, including statement terminators. | |||
== | == General JavaScript Tips == | ||
=== JavaScript Coding Style Guidelines === | |||
[[TBD]] | [[TBD]] | ||
== | === JavaScript Best Practices === | ||
[[TBD]] | |||
=== Common JavaScript Coding Errors === | |||
Probably the most common coding error is using = (assignment, as to a variable) in an if statement when == (a test for equality) is intended. | |||
== Links == | === Links === | ||
[[Triggers]] [[Trigger | [[JavaScript field]], [[Triggers]], [[Trigger Examples]] | ||
{{Template:JavaScriptLinks}} | {{Template:JavaScriptLinks}} | ||
[[Category:Tips]] | [[Category:en]] [[Category:Tips]] [[Category:Sc]] |
Latest revision as of 08:58, 23 August 2023
Wiki Home |
About Wiki | Memento |
Getting started Wiki | Memento |
Indexes Mobile | Desktop | Scripting |
Support Wiki | Memento |
Tips |
These are tips & techniques for using JavaScript for expressions in JavaScript fields and for scripts in triggers.
Field tips
Tips for calling field() for various field types.
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, ...] |
Simple fields
Fields that function as JavaScript type String, Number, Boolean, and Date operate in a direct manner. For example:
JavaScript field |
---|
field("linkedLib.integerField")*100
|
Trigger script |
entry().set("percent", entry().field("linkedLib.integerField")*100);
|
Date & Time fields
JavaScript Date & time functions expect & return time in milliseconds. This differs from Calculation fields, which use seconds.
Also, Memento includes an optional JavaScript library moment.js that provides flexible formatting of dates and times. For a summary of this library, see http://momentjs.com. For extensive details, see http://momentjs.com/docs. Skip over the first section "Where to Use It".
Note that the particular library included in Memento at this time is called moment.min.js.
Also, see Date field, DateTime field, or Time field for general information about the Memento user interface for dates & times.
Multiple-choice fields
The field() function returns an array of selected items from multiple-choice (Checkboxes & Multiple-choice list) fields. Therefore, if a comma-separated list of selections is desired for the result of a JavaScript field expression, it is necessary to fetch the items from the array and combine them into a string, separated by commas. This is easily done with the array method join().
Getting a comma-separated list of checked items from a multiple-choice field
JavaScript field |
---|
field("Menu Choices").join()
|
This solution is needed for trigger scripts that want to use such a comma-separated string, such as for the set() method of the Entry object.
Trigger script |
---|
entry().set("menuSelections"), entry().field("remoteLibrary.menuChoices").join());
|
Handling checked items individually
If the trigger script needs to handle each of the choices individually, it can be done as follows:
Trigger script | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
var e = entry(), items = e.field("remoteLibrary.menuChoices");
for (var item in items) {
// Handle each item (items[item]) here
}
Link to Entry fieldsThe Link to Entry field has its own structure, unique among the field types. Using field() to access the value of local and remote field values
Using set() in a trigger to set the value of a local field
To copy a link's value to another link
How Trigger & JavaScript field scripts differYou'll notice in this page that the code for JavaScript fields and that for triggers are very similar, but also that they different. Here's how they are different: Context
SemicolonsIn JavaScript, the use of semicolons is theoretically optional. In practice, however, without their use, problems arise in certain cases, and it is strongly recommended to use them to guarantee clarity and correctness. However, if you aren't sure about such things, you can omit them, and most of the time there will be no consequences, particularly in the case of JavaScript fields, in which the requirement is only to state about expression. Most JavaScript fields are just one or two lines long, so the need for statement terminators is minimal. Trigger scripts are straight JavaScript, so the code should obey strict JavaScript rules, including statement terminators. General JavaScript TipsJavaScript Coding Style GuidelinesJavaScript Best PracticesCommon JavaScript Coding ErrorsProbably the most common coding error is using = (assignment, as to a variable) in an if statement when == (a test for equality) is intended. LinksJavaScript field, Triggers, Trigger Examples
|