LabArchives Default JavaScript

Understanding the Seven Methods of the LabArchives Default Script

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.

As described in the introduction to the Script Editor, the widget script is actually contained within an object called by default. The HTML script that you edit within the HTML editor is contained within a tag with the attribute , should you need to reference it in your JavaScript. There are 7 default methods within ; these are , , , , , , and . Each of these methods calls a method of the same name. Because as the object name could be edited by the user, within the full HTML document this saves to another object called , which LabArchives then references to attach functionality. You can view the script here to review more deeply what happens when each method is called.

init

Default LabArchives method:

The method is called when the form is being initialized. It has two parameters, and . The describes whether the form is being displayed in a state (such as saved to a page) or state (being edited by the user). There are also and states for during development.

is generated by the method, and it contains the user inputs to the form when the widget is saved. It is important to note that all information necessary to set up the form that is not explicitly within the HTML must be contained within the object. If you choose to extend the functionality of the widget with dynamic content, such as a new table row that is generated when a button is clicked, then this dynamic content must also be tracked and stored within , which is the job of the method.

The code snippet defines the general actions that I take within the method. I’ll give a brief description of each action here, providing the outline for when each step is necessary. It’s important to note that you will not necessarily need each of these steps for every widget that you might design. You can view the full code for widgets that I have designed if you want to explore these actions in context at my GitHub repository: https://github.com/gibson-amandag/LabArchivesWidgetTemplates.

Parse init json. This step is necessary if you have added additional parameters to the output object. The string must be parsed into an object that can be manipulated within the method. When the widget is loaded to a page, is passed to the method as a string. However, when the widget is under development, is a function. Therefore, we’ve added an statement to check the .

Initialize dynamic content. If you’ve chosen to add any dynamic content to your widget, you will need to get this additional information stored within and use it to recreate dynamic components of the form.

Define window resize function. Define the function to be used when the window is resized to make sure that all of the form content remains visible, as there is no vertical scrollbar when saved to the page. I check for the window being resized with and then call my method. Within this method, I readjust the size of any elements that contain tables and then call the method.

Add event listeners. Define the actions that should be taken when the user interacts with the form. This could be clicking a button, checking a box, making a selection, or filling in an input, for example

Call the parent class init method. Supply the current mode and the string containing the form input to the method. Here, we are returning the component of the object, and turning it back into a string, as this method expected. Passing the to the method is the only action of the default method.

Add required field indicators. Add markers to the page to let the user know which elements are required to save the form, for example

Set up the initial state. Use the current form input to make decisions about how the form should be displayed. This is most relevant for after the user has saved the widget to the page. For example, you might only display a certain element if a box has been checked. In addition to defining this with an event listener, you need to check the state of the box when you initialize the page

Adjust the display based on the mode. There may be certain elements that you only want to be displayed during editing, or vice versa. In addition, if you have any input buttons within your script that you don’t want to be available when the form is saved to the page, you should disable them when the mode is not or .

to_json

Default LabArchives method:

The method is used to create a string that contains the information from the form inputs. Additionally, within this method, you must define any additional information about the page that isn’t contained directly within a form input or by the HTML. This might be a table row that is constructed by pressing a button, for instance. Within you could count the number of rows that were in the table at the time of saving, and then pass this number as a property within an object. The function could then use that property to recreate that number of rows within the table. An example of this is provided in my template widget on my GitHub repository, and this will be detailed in a later article. It is also important to remember that is a string, and therefore cannot contain complex data.

from_json

Default LabArchives method:

The method uses the to repopulate the form inputs. There is not likely to be much that you need to edit within this method. However, if you add additional parameters to the object that is returned by the method, you will need to the object within and specifically call the method using only the component of the that represents user inputs to the form elements, which are obtained by the method.

test_data

Default LabArchives method:

The method fills in the form with test data when it is under development. This involves adding strings to text inputs, randomly checking checkboxes and radio buttons, and randomly selecting from drop-down lists. If you have added any additional parameters within the output, you should return these same parameters in . For example, you may want to start a dynamic table with two rows when developing the widget.

is_valid

Default LabArchives method:

The method is called when the user tries to save the widget to the page. By default, this checks to be sure that elements that have in the name are not blank. However, I prefer to add the attribute to the inputs that I want to require users to complete before saving the widget. Therefore, I have edited the function to check for this property and return a fail log with the of the elements that have been left blank.

In order for the widget to be saved to the page, must return an empty array or . Any other , such as an with the fail log will prevent the page from being saved.

is_edited

Default LabArchives method:

The method is called to track whether or not the widget has been edited since being saved (or during development, since the method is called). You should not need to edit this.

reset_edited

Default LabArchives method:

The method can be called during development to remove the message, as if the page were saved. You should not need to edit this.

PhD Candidate in Neuroscience at University of Michigan. Hope College Grad. Enjoys data organization. Passionate about teaching science. gibsonamanda.com