Javascript Guide
chevron down
back search icon cancel search
 
 

Javascript Guide

Overview

The application logic written in JavaScript (.js) files, and can interact with the user interface using document object events and functions. JavaScript running on the device uses the Device API.

import * as document from "document";

let img = document.getElementById("image");
img.href = "another-image.jpg";

Interacting with Elements

To manipulate or interact with an element in JavaScript, you first need to assign an id or class to it.

<svg>
  <text id="demo">Hello!</text>
  <text class="red">Red Text</text>
  <text class="red">Also Red Text</text>
</svg>

Use the document object to get a reference to the elements, then manipulate them.

getElementById()

For example, to change the text inside a <text> element by its id:

import * as document from "document";

let demo = document.getElementById("demo");
demo.text = "Hello World!";

You can also use a parent element to get one of it's child elements:

<svg>
  <svg id="demoparent">
    <text id="demochild" />
  </svg>
</svg>

import * as document from "document";

let parent = document.getElementById("demoparent");
let demo = parent.getElementById("demochild");
demo.text = "Hello World!";

getElementsByClassName()

To manipulate multiple elements, you also can get a reference by using a common class name. This method will return an array of elements which match the specified class name.

import * as document from "document";

let elements = document.getElementsByClassName("red");
elements.forEach((element) => {
  element.text = "Hey Red!";
});

getElementsByTagName()

To manipulate multiple elements, you also can get a reference by using their tag name. This method will return an array of elements which match the specified tag name.

import * as document from "document";

let elements = document.getElementsByTagName("circle");
elements.forEach((element) => {
  element.style.fill = "blue";
});

Element Styling

Once you have a reference to an element, you can change its .style properties.

import * as document from "document";

let demo = document.getElementById("demo");
demo.style.fill = "red";
demo.style.fontSize = 20;
demo.style.fontFamily = "System-Regular";

Move an Element

You can reposition an object by changing its x and y coordinates, but you can only use pixel coordinates, you cannot use percentage values e.g. 100%.

import * as document from "document";

let demo = document.getElementById("demo");
demo.x = 42;
demo.y = 90;

Resize an Element

You can resize an object by changing its width and height properties, but you can only use pixel sizes, you cannot use percentage values e.g. 100%.

import * as document from "document";

let demo = document.getElementById("demo");
demo.width = 336;
demo.height = 336;

Layer Stacking Order (z-index)

By default, elements are rendered bottom upwards, based on the order in which they appear within the .view file. You can dynamically affect the stacking order of elements, by changing the .layer property. Elements with a higher layer value will appear on top of elements with an undefined or lower layer value. This is similar to the behavior of z-index in CSS.

import * as document from "document";

let demo = document.getElementById("demo");
demo.layer = 2;

Hiding/Showing an Element

import * as document from "document";

let demo = document.getElementById("demo");
// Hide
demo.style.display = "none";
// Show
demo.style.display = "inline";

// Toggle Show/Hide
function toggle(ele) {
  ele.style.display = (ele.style.display === "inline") ? "none" : "inline";
}

toggle(demo); // hidden
toggle(demo); // visible

You can also use the visibility attribute:

import * as document from "document";

let demo = document.getElementById("demo");
demo.style.visibility = "hidden";  // Hide
demo.style.visibility = "visible"; // Show

Note:

  • display can be changed from inline to none to hide an element. e.g. demo.style.display = "none";
  • Elements cannot be programmatically created, they must exist within the .view file when the application is launched.

Events

Many UI elements can generate events, for example when the user taps on it. To generate events, you will need to set the pointer-events property to visible within the .view file.

<svg fill="black">
  <rect id="myRect" pointer-events="visible" />
</svg>

Click Event

You can attach a handler to the click event for any elements which have pointer-events="visible". 

import * as document from "document";

let myRect = document.getElementById("myRect");

myRect.addEventListener("click", (evt) => {
  console.log("click");
});

Touch Events

You can attach a handler to the mouseup, mousedown and mousemove events. These occur when the display is touched. Each event callback includes the screenX and screenY coordinates for any element which is visible for pointer events (pointer-events="visible").

<svg>
  <rect id="myButton" width="100%" height="100%"
        fill="red" pointer-events="visible" />
</svg>

import * as document from "document";

let myButton = document.getElementById("myButton");

myButton.addEventListener("mousemove", (evt) => {
  console.log(`Mouse moved - x: ${evt.screenX}, y: ${evt.screenY}`);
})

See the SVG 1.1 specification for more information on the pointer-events property.

Triggering Animations

JavaScript can be used to trigger animations on the instance of a Template Symbol:

elementinstance.animate("EVENT-NAME")

import * as document from "document";

let myElement = document.getElementById("myElement");
myElement.animate("enable");

For more information see JavaScript Animations in the Animations Guide.

JavaScript Animations

The requestAnimationFrame() method can be used to perform frame based animations in JavaScript. The method takes a single callback function as an argument which is invoked before the screen is repainted.

function callback(timestamp) {
  // Perform animation frame logic here

  // Request next frame
  requestAnimationFrame(callback);
}

requestAnimationFrame(callback);

The animation frame requests are only invoked while the display is on, so a developer does not need to perform additional logic to optimize for changes in the display state.

previous
CSS Guide
SVG Components Guide
next