LabArchives Script Editor

Introduction to the Script Editor and a Brief Overview of JavaScript

This article is part of a series on how to get started with designing custom LabArchives Widgets. You can find the introduction and links to the other articles in the series here.

The third tab within the Widgets Manager is the Script Editor, which provides the JavaScript instructions for how to display, save, and work with the form elements. This is really where the power of these widgets lies, as the JavaScript code can be used to validate the form data, make calculations, or change components of the form. It was also the most challenging for me, as a novice, to understand.

If you’re familiar with JavaScript and jQuery, you can likely skip this article and move right into the article describing the methods called by the default widget script. However, I’d like to take a brief aside and introduce some of the key features of this language that I think are critical to understanding how to edit the default script for your purposes.

• IDs and Classes. When you create form elements in HTML, you should assign them a unique id attribute. You can also assign a class to elements that may have something in common to be able to refer to multiple elements at once. Classes do not have to be unique, and you can apply multiple classes to the same object. You can then reference these items within the Script Editor using pure JavaScript with getElementById(elementID) and getElementsByClass(elementClass)or more easily using jQuery with $("#elementID") and $(".elementClass"), respectively. $() is the notation to use jQuery functions, and the contents are known as the “selector.” jQuery works with CSS-style selectors, meaning that # denotes and id and . denotes class. You can read more about CSS selectors here.
• Document Object Model (DOM). The DOM is a representation of the HTML that the widget script can access and update. This is often known as a DOM tree, as it represents the relationships between different elements. You can find elements and update elements based on these relationships using different JavaScript and jQuery methods
• Objects. The best description of objects that I have found is in Chapter 3 of Jon Duckett’s JavaScript & jQuery: interactive front-end web development book:

Objects group together a set of variables and functions to create a model of something you would recognize from the real world. In an object, variables and functions take on new names… variables become known as properties… functions become known as methods. (p100; emphasis added)

• Objects (cont). Within an object, properties (variables) and methods (functions) are separated by commas. To write a function within an object, you use the notation funcName: function () {}. That function is now a method of that object and to call it, you can use the notation objectName.funcName(). Importantly, the portion of the widget script that you will edit is actually within an object. Therefore, any custom functions that you write are actually methods of my_widget_script and need to be written and referred to as such
• Events. When the user interacts with the form, such as by clicking on a button or entering inputs, these are known as events. These events can be captured, and they can be used to trigger specific actions within the script editor.
• JavaScript Object Notation (JSON). JSON is how the form data is stored to be able to refill the form contents when it is saved to the page. This converts the form input into a simple string. That string is generated by the to_json method described below when the widget is saved. Then, the init method and the from_json method use that JSON string to create the form as intended based on the user input.

In addition to the brief overview here, I would suggest going through the W3Schools JavaScript and jQuery tutorials or the MDN JavaScript resources. You can also reference the official jQuery website. The most clarifying resource for me, however, has been Jon Duckett’s JavaScript & jQuery: interactive front-end web development book.

My GitHub Repository with Widget Templates

You can find the full code for a template widget and other examples at https://github.com/gibson-amandag/LabArchivesWidgetTemplates.

gibson-amandag/LabArchivesWidgetTemplates

Other Articles in this Series

Getting to Know the LabArchives Widget Manager

LabArchives Widget HTML Editor

LabArchives Default JavaScript

LabArchives Widget Manager Tips and Tricks