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 my_widget_script by default. The HTML script that you edit within the HTML editor is contained within a <form> tag with the attribute id="the_form", should you need to reference it in your JavaScript. There are 7 default methods within my_widget_script; these are init, to_json, from_json, test_data, is_valid, is_edited, and reset_edited. Each of these methods calls a parent_class method of the same name. Because my_widget_script as the object name could be edited by the user, within the full HTML document this saves to another object called form_script, which LabArchives then references to attach parent_class functionality. You can view the parent_class script here to review more deeply what happens when each method is called.
init
Default LabArchives init method:
init:function (mode, json_data) {
this.parent_class.init(mode, json_data);
}The init method is called when the form is being initialized. It has two parameters, mode and json_data. The mode describes whether the form is being displayed in a view state (such as saved to a page) or edit state (being edited by the user). There are also view_dev and edit_dev states for during development.
json_data is generated by the to_json 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 json_data 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 json_data, which is the job of the to_json method.
The code snippet defines the general actions that I take within the init 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.
var parsedJson = this.parseInitJson(json_data);Parse init json. This step is necessary if you have added additional parameters to the to_json output object. The json_data string must be parsed into an object that can be manipulated within the init method. When the widget is loaded to a page, json_data is passed to the init method as a string. However, when the widget is under development, json_data is a function. Therefore, we’ve added an if statement to check the typeof json_data.
this.initDynamicContent(parsedJson);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 json_data and use it to recreate dynamic components of the form.
window.onresize = ()=> this.resize();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 window.onresize and then call my resize() method. Within this method, I readjust the size of any <div> elements that contain tables and then call the parent_class.resize_container() method.
this.addEventListeners();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
this.parent_class.init(mode, () => JSON.stringify(parsedJson.widgetData));Call the parent class init method. Supply the current mode and the JSON string containing the form input to the parent_class.init method. Here, we are returning the widgetData component of the parsedJson object, and turning it back into a string, as this parent_class.init method expected. Passing the json_data to the parent_class.init method is the only action of the default init method.
this.addRequiredFieldIndicators();Add required field indicators. Add markers to the page to let the user know which elements are required to save the form, for example
this.setUpInitialState();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
this.adjustForMode(mode);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 edit or edit_dev.
to_json
Default LabArchives to_json method:
to_json:function () {
return this.parent_class.to_json();
}The to_json method is used to create a JSON 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 to_json 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 output object. The init 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 JSON is a string, and therefore cannot contain complex data.
from_json
Default LabArchives from_json method:
from_json:function (json_data) {
this.parent_class.from_json(json_data);
}The from_json method uses the json_data 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 json_data object that is returned by the to_json method, you will need to parse the json_data object within from_json and specifically call the parent_class.from_json method using only the component of the json_data that represents user inputs to the form elements, which are obtained by the parent_class.to_json method.
test_data
Default LabArchives test_data method:
test_data:function () {
return this.parent_class.test_data();
}The test_data 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 to_json output, you should return these same parameters in test_data. For example, you may want to start a dynamic table with two rows when developing the widget.
is_valid
Default LabArchives is_valid method:
is_valid:function (b_suppress_message) {
return this.parent_class.is_valid(b_suppress_message);
}The is_valid 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 _mandatory in the name are not blank. However, I prefer to add the required 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 required property and return a fail log with the id of the elements that have been left blank.
In order for the widget to be saved to the page, is_valid must return an empty array [] or NULL. Any other return, such as an alert with the fail log will prevent the page from being saved.
is_edited
Default LabArchives is_edited method:
is_edited:function () {
return this.parent_class.is_edited();
}The is_edited method is called to track whether or not the widget has been edited since being saved (or during development, since the reset_edited method is called). You should not need to edit this.
reset_edited
Default LabArchives reset_edited method:
reset_edited:function () {
return this.parent_class.reset_edited();
}The reset_edited method can be called during development to remove the is_edited message, as if the page were saved. You should not need to edit this.
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.
