Overview

This article contains the Gtmhub best practices for writing insight JavaScript.

The Script Tag

Only use one JavaScript tag per insight
All script tags should start by attaching a function to the widget ready event, which can be done like this: widget().on('ready', function(evt, angularScope). All code should then go inside the function and will be fired when the insight is fully loaded.

❌Avoid This

<script>
let i = 'some value'
//Do something with i
</script>

❌Avoid This (this is an older standard that is deprecated)

<script>
(function() {
    let i = 'some value';
    //Do something with i;
})();
</script>

✔️Do This

<script>
widget().on('ready', function(evt, angularScope) {
    //Your code goes here
});
</script>

The debugger key word should not be used in “production” code. It should only be used when actively debugging something
Do not output to the console unless outputting information necessary to help debug when an unexpected error occurs
- Using the console during development is OK, but clean up when done

Use Angular to handle interactions between the HTML and JavaScript
- Avoid using jQuery (see below) or pure JavaScript
Each insight will have its own Angular scope. This scope should only be referenced using the variable passed in to the event handler for widget ready. We should not retrieve it with jQuery (this was done in the past).

❌Avoid This

const angularScope = angular.element("#wrapperDiv").scope();
angularScope.someValue = 'val1';

✔️Do This

widget().on('ready', function(evt, angularScope) {
    angularScope.someValue = 'val1';
});

❌Avoid This

$('#someHtmlId').hide();

✔️Do This

HTML

<div ng-show="showSomeElement">Words</div>

JavaScript

angularScope.showSomeElement = false;

❌Avoid This

$('#someHtmlId').val('some value');

✔️Do This

HTML

<input ng-model="inputValue">

JavaScript

angularScope.inputValue = 'some value';

❌Avoid This

$('#someHtmlId').on('click',function() {
    //Do something on click
});

✔️Do This

HTML

<div ng-click="doSomethingOnClick()">Words</div>

JavaScript

angularScope.doSomethingOnClick = function() {
    //Do something on click
};

Avoid using JavaScript event handlers in the HTML. Use their Angular equivalents instead.

❌Avoid This

HTML

<div onclick="someFunction()">Click Me!</div>

JavaScript

function someFunction() {
  //Do stuff
};

✔️Do This

HTML

<div ng-click="doSomethingOnClick()">Words</div>

JavaScript

angularScope.doSomethingOnClick = function() {
    //Do something on click
};

Favor using Angular's http module for API calls when able
- Use of jQuery for Ajax calls is OK, but if you modify the Angular data model after the API call finishes, you may need to use $apply() to render the changes
All API calls should handle the failure case
- Or have a comment indicating why a silent failure is OK
Do not make synchronous API calls (I.E. using async: false property)
- Doing so can cause the page to become unresponsive if the API takes a while
When making API calls that may take a substantial amount of time, use a processing spinner in the UI to indicate that something is happening
Avoid letting the user make multiple duplicate API calls (I.E. allowing two unintentional button clicks)

In general, avoid using an external library if there are any alternatives
Any library used in Quantive Results may be referenced and used in insights
- Reference libraries using Angular’s require instead of script tags when available
Quantive blocks most references to 3rd party script hosting sites. If you want to include a library that is not available, reach out to Quantive Support to start a request
- You can attempt to inline a library, but this can have unexpected side effects