Tips:Using JavaScript in Memento: Difference between revisions

From Memento Database Wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Stamp|2017-02-17|4.2.1|1.0.8}}
{{Stamp|2017-02-20|4.2.1|1.0.8}}
 
'''[[This page is under development. Information is incomplete and potentially incorrect.]]'''


These are tips & techniques for using JavaScript for expressions in JavaScript fields and for scripts in triggers.
These are tips & techniques for using JavaScript for expressions in JavaScript fields and for scripts in triggers.


== FIELD tips ==
== Field tips ==
Tips for various field types.
Tips for calling ''field()'' for various field types.
{{FieldTypeReturnValues}}
{{FieldTypeReturnValues}}


Line 21: Line 19:
|-
|-
|<source lang="JavaScript">
|<source lang="JavaScript">
entry().set("percent", field("linkedLib.integerField")*100);
entry().set("percent", entry().field("linkedLib.integerField")*100);
</source>
</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 ===
=== 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().
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
! JavaScript field
Line 34: Line 40:
</source>
</source>
|}
|}
The same 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.
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
! Trigger script
Line 42: Line 48:
</source>
</source>
|}
|}
==== 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.
The 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 ''field()'' to access the value of local and remote field values ====
: '''Argument'''
: '''Argument'''
:# The name of the field whose value you want
:# The name of the field whose value you want
Line 75: Line 93:
|}
|}
<br/>
<br/>
==== Using set() in a trigger to set the value of a local field ====
==== Using ''set()'' in a trigger to set the value of a local field ====
: '''Arguments'''
: '''Arguments'''
:# Name of the field whose value is to be set
:# Name of the field whose value is to be set
Line 92: Line 110:
<br/>
<br/>


=== To copy a link's value to another link ===
==== To copy a link's value to another link ====
:* The remote library must be set to use unique Entry Names.
:* The remote library must be set to use unique Entry Names.
:* Both links must point to the same library
:* Both links must point to the same library
Line 119: Line 137:
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:
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 ===
* 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 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.
* 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.
{|
{|
Line 137: Line 155:


=== Semicolons ===
=== Semicolons ===
To make things as simple and straightforward as possible, not only is context set up for you in JavaScript fields, but the need for using JavaScript semicolons is removed.
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]]


If you know where to put semicolons, their use is recommended, 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. Most JavaScript fields are just one or two lines long, so the need for statement terminators is minimal.
=== JavaScript Best Practices ===
[[TBD]]


Trigger scripts are straight JavaScript, so the code must obey JavaScript rules, including statement terminators.
=== Common JavaScript Coding Errors ===
[[TBD]]


== Links ==
=== Links ===
[[JavaScript field]], [[Triggers]], [[Trigger Examples]]
[[JavaScript field]], [[Triggers]], [[Trigger Examples]]



Revision as of 02:49, 5 March 2017

« Page as of 2017-02-20, editions Mobile 4.2.1, Desktop 1.0.8 »

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 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, ...]

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 fields

The 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

Argument
  1. 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
var links = field("Link field name");
if (links.length > 0) {
    var name = field(links[0].field("Name");
    // Put your code to handle name here
    }
Trigger
var e = entry(), links = e.field("Link field name");
if (links.length > 0) {
    var name = e.field(links[0].field("Name"));
    // Put your code to handle name here
    }


Using set() in a trigger to set the value of a local field

Arguments
  1. Name of the field whose value is to be set
  2. 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
var e = entry();
e.set("First link", "InterOpera Group");
e.set("Second link", "Mozilla,Google");


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
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());
    }

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
field("Fraction") * 100
Trigger
var e = entry(), lib = lib();
message("Library " + lib.title + ", entry " + e.title);

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

JavaScript Best Practices

TBD

Common JavaScript Coding Errors

TBD

Links

JavaScript field, Triggers, Trigger Examples

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