Skip to content

JavaScript

Zuar Portal provides a means for adding custom JavaScript code to any Page. For practical, copy-able examples, see JavaScript Patterns.

Creating Snippets

Snippets can be created in two places:

  1. Admin Console - Navigate to the JavaScript section of the Admin panel. Add your code as a Snippet, rename it, and click Save.
  2. Sidebar Editor - When editing a page, open the Page section of the sidebar. The JavaScript Snippets area allows you to add, remove, and reorder snippets for that page.

Snippets are edited using the Code Editor, which provides syntax highlighting and code completion for JavaScript. You can use the inline editor in the sidebar or open the full external Code Editor window for a larger editing surface.

Adding Snippets to Pages

Snippets can be added to one or more Pages and will be run once the page loads. Multiple Snippets can be added and loaded in the desired order by dragging and dropping.

You can use JavaScript Snippets to perform tasks such as pulling data from a 3rd party API and displaying it in an HTML block. You can utilize the System JavaScript API to access data about the Page, Blocks, and more from your Snippet.

Loading Order

JavaScript Snippets in Zuar Portal are loaded after all blocks on the page have finished loading and have the data they are configured to receive via their queries.

Unloading of JavaScript

When using JavaScript on Pages to add event handlers, it is important to properly unload it. Let's imagine that we want to track a global click event using Page JavaScript with next the following Snippet.

let clickListener = function () {
    console.log('document click', new Date().toISOString());
}
document.addEventListener('click',clickListener);

Navigating through Portal pages will create and register new event listener every time the JavaScript Snippet is called. To avoid such behaviour, we need to properly clean up all side affects of our Page JavaScript. To do so, we can modify the snippet above by returning an object with an onDestroy property set to our clean up function.

let clickListener = function () {
    console.log('document click', new Date().toISOString());
}
document.addEventListener('click',clickListener);

return {
    onDestroy:function() {
        document.removeEventListener('click',clickListener)
    }
}

The function returned in the onDestroy property in our new snippet will be called when the user leaves the page.

JavaScript Snippets versus HTML Blocks

Admins may add custom JavaScript to a portal using Snippets or via <script> tags in HTML blocks. To help decide when to use either option, consider these suggestions:

JavaScript snippets are recommended when:

  • JavaScript is required but not tied to any page specific UI elements
  • JavaScript affects the DOM across multiple blocks
  • You need to define a global function that multiple blocks need to call

JavaScript within HTML blocks is recommended when:

  • The JavaScript is required to build a UI or act on HTML in the same block
  • The JavaScript needs to run before all blocks are finished loading