API Docs for JavaScript File WidgetMainApi.js

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.

• Map of of username::widgetname --> Unix checksum for the Widget DB
• Sept 2022: removing old naive checksum technique
• __databaseCheckSum : {},


• MAX_GET_PARAM_VALUE : 2000,
• https://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers
• Could actually be much smaller than this


• lookupItem : function(tabname, itemid)
• Find the item with the given ID for the given table and return it.
• Error if the item does not exist, if you are uncertain whether the ID exists or not,
• call haveItem(tabname, itemid)


• getItemList : function(tabname)
• Get the full list of records associated with given table.
• This is one of the most fundamental operations of the framework.
• Error if the table name is not loaded on the current page.
• If you are uncertain if the table will be present, use haveTable(...) to check


• buildItem : function(tabname, record)
• Create a new record for the given table.
• The record argument is a hash with keys corresponding to the column names of the table.
• It is optional to provide the "id" column, if you do not provide it, the framework
• will allocate a new id and assign it to the record.
• Other than the id column, all columns must be explicitly provided.
• IMPORTANT: this method creates the record but does not sync it to the server.
• To sync, call syncItem on the returned JS representation of the record.


• haveItem : function(tabname, itemid)
• Check if the given table has an item with the given ID.
• This is logically equivalent to calling getItemList
• and checking each record to see if it has the ID,
• but is faster because it uses the index on the table.


• haveTable : function(tabname)
• Return true if the table is in the data for the page.


• getTableOwner : function(tabname)
• Return the owner of the given table


• haveWriteAccess : function(tabname)
• True if the current user has write access to the given table
• Widgets that serve multiple users, some of whom have write access and some of whom do not,
• should check this function before displaying UI options that will perform write actions.
• The backend will disallow such writes anyway, but it will be a less pleasing user experience


• getFieldList : function(tabname)
• Return the list of fields/columns in the given Table
• These correspond exactly to the columns in the underlying SQLite table
• This is basically equivalent to calling Object.keys(..) on one of the items,
• but this works even if you don't have an instance of the item


• getWidgetTableList : function()
• Get all the tables that have been registered on this page.


• newBasicId : function(tabname)
• Creates a new ID for the given table name.
• In general, users should not need to call this method; it is called automatically
• when the "id" column is not explicitly supplied in the buildItem(...) data.
• The ID is allocated by generating a random integer in the the useable range
• and checking to make sure it is not already in use in the table.
• The useable range is -2147483648 to 2147483647, with an exception for -1000 to 0


• newIncrementalId : function(tabname)
• Creates a new ID for the given table name.
• The new ID is 1 greater than the previous max ID currently in the table
• This approach to ID allocation is not recommended because it can cause problems in multi-user settings


• serverSideNewDbId : function(tabname, callback)
• Queries the server to obtain a new unused database ID for the given table
• In other words, this is a server-side version of newBasicId(...)
• It is generally better to use the client-side version. This method is intended to be used
• in cases where you do not have all the records for the given table loaded in the client
• For example, if you use the no_data=true option to load the table manager without loading any records


• getBlobStoreUrl : function(username, widgetname, tablename, recordid)
• Gets the Blob Store URL for the given item
• NOTE: you should not use this function directly, instead call method with same name, but no arguments
• that is attached to the Widget Blob item
• Example : W.lookupItem("my_blob_table", itemid).getBlobStoreUrl()


• checkTableName : function(tabname)
• Checks that the given table name exists and is loaded.
• Error if it is not.


• bulkUpdate : function(tablename, idlist, options)
• Bulk update of records to the given table.
• You must supply the list of IDs that are to be updated; all such IDs much correspond to real records
• To use this, first perform the desired updates on the given records
• Instead of calling syncItem on each record, call this function with the target IDs
• This method refreshes the page after the update is complete, to ensure the changes have been picked up
• Third argument is a hash that is reserved for allowing modifications to the behavior of this function


• bulkDelete : function(tablename, idlist, options)
• Bulk delete of records to the given table.
• You must supply the list of IDs that are to be deleted; all such IDs much correspond to real records
• This method refreshes the page after the update is complete, to ensure the changes have been picked up
• Third argument is a hash that is reserved for allowing modifications to the behavior of this function


• createIndexForTable : function(tablename, fnamelist)
• Create an index on the given table
• fnamelist is a list of field names in the table that you want to index


• createIndexIfAbsent : function(tablename, fnamelist)
• Same as createIndexForTable, but if the index is already present, return early


• lookupFromIndex : function(tablename, lookup)
• This is the main exposed API call
• The tablename is a normal Widget tablename
• Lookup is a JS has with K/V pairs corresponding to the query
• Eg to lookup everyone who lives in California, use { state : "CA" } as lookup
• You will get an error if the lookup specifies keys that do not match an index
• (But they do not need to match the WHOLE prefix)


• createNewIdRandom : function(datamap)
• Create a new ID by generating a random integer in the the useable range
• and checking to make sure it is not already in use.
• The useable range is -2147483648 to 2147483647, with an exception for -1000 to 0


• __getListFuncMap : {},
• Map of table name to get full item list


• __buildItemFuncMap : {},
• table name to builder function


• __readOnlyAccess : [],
• List of tables for which the current user has read access only


• __tableNameIndex : new Map(),
• Map of short table name to Widget Table objects


• __MAGIC_NULL_STRING : "_x_NULL_y_",
• WWIO converts nulls to this string. This must match CoreUtil.MAGIC_NULL_STRING


• __augmentWithCheckSum : function(opurl)
• Look up the widget owner and name from the url
• Use that info to find the current checksum value
• This needs to be looked up just-in-time, before the request is sent,
• AFTER it is enqueued


• __finalIndexUpdateSub : function(item, updatefunc, indexes)
• Note: for these three functions, indexes = null => all indexes for the table