API Docs for JavaScript File WidgetUtil.js



This file is a catchall container for a variety of functions that are generally useful for Widget development. There are a couple of categories of functions that are logically related to each other.

Generic Record Actions

These functions are simple, generic updaters that can be helpful to reduce the amount of code required for basic operations. The best way to see this is through an example: 

        function updateRecordName(itemid)
        {
            const item = W.lookupItem("my_table", itemid);            
            const newname = prompt("Please enter a new name for the record: ", item.getName());

            if(newname) 
            {
                item.setShortName(newname);
                item.syncItem();
                redisplay();
            }
        }

This update function is a bit verbose, given it's performing a very simple operation. It can be replaced with the following code: 

        function updateRecordName(itemid)
        {
            genericEditTextField("my_table", "short_name", itemid);
        }

This function will prompt the user for a new value for the field "short_name", update the record with the resulting value, sync the change to the server, and then redisplay the page. The function genericEditIntField does the same thing, except it checks that the input is a valid integer before doing the update. The function genericDeleteItem performs a delete operation, after checking to confirm that it's okay to delete.

HTML / HTTP utilities

There are a couple of simple functions that are just very helpful when dealing with HTML and HTTP. One useful trick is the ability to extract parameters from the HTTP query string. This allows you to create links to Widget code that will automatically set certain values when the page loads. For example, suppose you have a page that shows all the events for a certain date. By default, when the page loads, it shows all the events that happened yesterday. But you would like to create Widget links that contain a date argument, such as: 
https://webwidgets.io/u/dburfoot/eventinfo/widget.jsp?datetarget=2022-01-05

This can be implemented using the getUrlParamHash function: 

        // Global variable, loaded at start of script section
        DATE_TARGET = getUrlParamHash()["datetarget"];

        function redisplay()
        {
            const items2show = getItemList("event_info").filter(item => item.getDayCode() == DATE_TARGET);
            ... // show items 

        }

The functions decodeQString2Hash and encodeHash2QString are inverse functions that convert between query strings and hashes.

Auto-Extracted Documentation

The following information is automatically extracted from the JS code files. Methods and variables that begin with the double underscore ("__") are considered to be part of the private API of the library.