Call JS/TS Functions from XML
Introduction
Developers can call JavaScript or TypeScript functions from most component attributes in the view XML. This allows attribute values to be determined programmatically, and in most cases be dynamic. This enables more complex use cases than hardcoded attribute values.
Some examples are:
Dynamically determining text to display in a view
Populating tables with custom data (e.g. translated data or data aggregates)
Generating the content of sidebar items
Syntax & Basic Example
The basic syntax for calling a function defined in the view's JS/TS from the XML is:
$:myFunctionName(myParameter)
In the below example, a button's disabled state is determined by evaluating an object's field:
<var name="form" type="application_form" />
<button label="Save" disabled="$:isDisabled(view.form)" disabled-message="Complete all fields before saving" on-press=":$saveForm()"/>
function isDisabled(form) {
if (form && form.details_pending) {
return true;
}
else {
return false;
}
}
What goes on in the background
Everything after the $:
is evaluated as if it were part of the view's JS/TS. This also means that:
You are able to execute single lines of JS from the XML, e.g.
<info show-if="$:view.my_counter === 3">You have no remaining attempts.</info>
<button on-press="$:journey.dialog.simple({title: 'Not implemented yet'})" />
2. You are able to call functions from your Shared JS (or App Modules for TypeScript apps), e.g.
<button show-if="$:sharedShowCredentials() === true" />
JavaScript AND Operator
AND Operator
The JavaScript AND operator (&&
) is a reserved character in XML and will not parse correctly if you include it in the XML function. It is recommended to extract the logic into a JavaScript/TypeScript function instead, as explained below.
In your view's JS/TS, the &&
operator can be used:
function shouldShow() {
return view.my_counter === 3 && view.num_of_attempts < 4;
}
The &&
operators does not work correctly within your view's XML, so call the function defined above:
<button show-if="$:shouldShow()" />
Passing View Variables
When using the $:
syntax, view variables aren't automatically inferred anymore. To use a view variable, prepend it with view.
, e.g.
<button show-if="$:myFunction(view.my_view_variable)" />
where my_view_variable
is the name of a view variable (i.e. defined as <var name="
my_view_variable" .. />
)
Global variables such as user
and journey
do not get prepended with view.
. They need to be called directly, e.g.
<button show-if="$:myFunction(user.name)" />
Format Strings
Format strings resolve to the return value of the function. For example:
Defining a button in your view's XML like this:
<button label="{$:getLabel()}" />
and the function in your view's JavaScript like this:
function getLabel() {
return "Click me!";
}
will result in a button with label Click me!
JS/TS events (e.g. on-press
, on-change
)
on-press
, on-change
)JavaScript/TypeScript functions can be called when a JS/TS event is triggered:
<button on-press=”$:myFunction()” />
function myFunction() {
var confirm = jouurney.dialog.confirm({title: "Are you sure you want to navigate away?"});
if (confirm) {
return navigate.link("my_view");
}
}
You can pass parameters from XML to JS/TS:
<button on-press="$:confirmAndNavigate('nextView')" />
function confirmAndNavigate(viewPath) {
var confirm = jouurney.dialog.confirm({title: "Are you sure you want to navigate away?"});
if (confirm) {
return navigate.link(viewPath);
}
}
object-table
fields
object-table
fieldsWithin an object-table
each row is exposed as $object, which can be used in your table as follows:
<model name="total" label="Total">
<field name="total1" label="Total 1" type="number" />
<field name="total2" label="Total 2" type="number" />
</model>
<var name="my_collection" type="query:total" />
<object-table query="my_collection" label="My Totals">
<column heading="Total">{$:calculateTotal($object)} </column>
</object-table>
function calculateTotal(myObject) {
return myObject.total1 + myObject.total2;
}
Similarly, $selection
can be passed as a parameter when defining an object-table
action:
<object-table ...>
<action on-press="$:rowAction($selection)" validate="false" />
...
</object-table>
function rowAction(selectedObject){
// Do something with the object
console.log(JSON.stringify(selectedObject));
}
Other common XML attributes
The below table lists other common XML attributes where JS/TS functions can be used. Note that this is not a complete list.
Note that only Format Strings are wrapped in {}
.
A view function with custom parameters
<button on-press="$:confirmAndNavigate('my-path')" />
state
(found in a sidebar
item
)
A view variable
- function returning "normal"
, "active"
or "disabled"
<sidebar>
<item state="$:getMyState()" />
<item state="myState" />
</sidebar>
Note: In this example, myState
is a view variable.
Last updated