LabArchives Widget Manager Tips and Tricks

Miscellaneous suggestions for navigating and troubleshooting the widget design process

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.

• Develop offline. Within the script editor, click the develope offline [sic] button. This will open the widget within a new webpage. Right click on the page and select View Page Source (if you are using Chrome). This will display the full HTML script to reproduce the widget, calling the necessary parent form methods and other helper scripts. You can then use your preferred coding application (I’ve been using VSCode) and open the local HTML file within your browser. This is much easier than trying to edit back and forth within the Widget Manager. To change the mode, scroll to the text between the JavaScript and HTML code. You can ctrl/cmd-f to search for the following:

//call to the init function in your script.  Note that you can change the mode in the call here.
//your choices are view,view_dev,edit,edit_dev,  see the parent class source for details
form_script.init("edit", function() {return form_script.test_data()});

• Develop offline (cont). Change the first parameter to the mode of your choice; generally, you will want edit or edit_dev to be able to test interaction with your form. This also calls the test_data method, meaning that your form will be populated with test data for development. Do be sure to periodically test your code back within LabArchives, as there can be additional errors that crop up, particularly with to_json and form initialization that can be difficult to catch offline.
• Inspect your code. Make use of Chrome’s DevTools to troubleshoot your widget. Right click on the page, and click inspect. To be able to view the source code and to pause implementation at particular points, add debugger; to a line of the code. You can also use console.log() and alert() to check how the code is being evaluated.
• Create a testing widgets folder in LabArchives. You’ll likely need to save your widgets to a page as you are developing them to make sure that they function correctly, especially after being saved. When you update the code for an existing widget, this can affect widgets that you have already saved to your notebook. However, elements with the same name are retained. If you edit a widget that has been saved to a page, it will update the code to the current version saved within the widget manager.
• Add CSS styles to the HTML source field. You can add your own CSS styles to help manage the style of the widget. There are also many LabArchives style sheets called by the full HTML document, which can make it challenging to edit the display of headings and tables at times. You can add Bootstrap to your page using a script. However, Bootstrap requires a later version of jQuery than is used by LabArchives (which uses jQuery 1.7.2 from 2012). To get around this, you can (1) load the new jQuery script (2) load the Bootstrap javascript (3) call jQuery.noConflict(true) to relinquish the use of $() and global jQuery variables back to the old version called by LabArchives. This is necessary to prevent errors and to allow the form to save appropriately.

• Beware of <textarea> within the script editor. The script editor itself is within a <textarea> element on the page. Therefore, if you are trying to add a <textarea> tag to the DOM using JavaScript or jQuery, it actually breaks the script editor and generates errors because the page thinks that you are closing the editing field. To get around this problem, break up the tag within the string, such as "<text" + "area id='myID' name='myname'><text" + "area>".
• Be cautious about <tag/> within script editor. If you are appending new elements within the script editor, it is safest to use <tag></tag> as sometimes LabArchives does not close these appropriately, leading to misbehaving widgets.
• Use &nbsp as a filler if you are creating a tag with no content. For example, if you create a <span id="mySpan"></span> or a <td id="myTd"></td> without any initial HTML content that you plan to fill with JavaScript, LabArchives has a habit of deleting the blank element entirely after saving the HTML. Therefore, use a non-breaking space &nbsp as filler content (<span id="mySpan">&nbsp</span>) that you can then replace with the JavaScript code.
• Resize the container after changing elements. When filling out a widget or once it is saved to the page, there is no scroll bar. If the content is too big for the allotted window, it is simply pushed off the page. Therefore, in addition to defining the resize method that should be called when the window is resized, this resize method should be called when content is show or hidden, created or removed. There is a parent.class.resize_container() method that is particularly useful for adjusting the vertical dimensions of the widget container. You can call the window.innerWidth method to get the width of the widget container and resize large elements based on that width. For example, I often make the <div> containing large tables 95% of the innerWidth to ensure that I have space to scroll around it, and I add a horizontal scroll bar with CSS for any overflowing content within it.

• Check to_json if the widget won’t save to the page. If you’re certain that all required elements have been completed and the is_valid function appropriately returns an empty array [] or NULL value, you should check to ensure that there are not any errors associated with to_json, which is called when trying to save the widget.
• “Minify” your JavaScript Code. LabArchives has limits to the number of characters that can be saved within the HTML and Script Editors. You quite reasonably may bump against some of these limits, leading to unexpected behavior of your widget. You “minify” your .js file to get rid of white space and comments for instance. This allows you to still document your code for offline development, while increasing what you can fit in LabArchives. I’ve been using a Minify extension right within VSCode.

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 Script Editor

LabArchives Default JavaScript