UI Utilities Sadjcore.js helper functionality

Bodyscript Template

The bodyscript.html Django template should be included into the main application frame immediately after the opening 'body' tag. It contains an extension of the standard SmartAdmin code for applying template themes, taking account possible server-side storage of such themes.

It also contains some helper routines for managing dependencies, to assist with constructing single-page apps, namely:

• docReady(callback) - Waits until the full DOM is loaded before executing the callback
• sadjReady(callback, dependencies) - Waits until all listed dependencies are in place

The 'sadjReady' routine waits for sadjcore.js to load, then uses code from sadjcore.js to check for the presence of any listed dependencies. If they are not present, it waits for 100ms and tries again. This is useful for constructing single-page apps, where the page may be loaded before the dependencies are in place.

Example

The Edit in Forms page requires Sadj controls (sadjcontrols.js) and the 'select2' dropdownlibrary. After a runFormsPageSetup function has been defined, the following code will wait for the sadjcore.js and sadjcontrols.js libraries to load, then wait for the select2 library to load, before executing the runFormsPageSetup function:

var dependencies = ['controls', '$.fn.select2']

 docReady( () => {sadjReady(runFormsPageSetup, dependencies);} );

Note that the sadjReady function is called within the docReady function, to ensure that the DOM is fully loaded before the sadjReady function is called. Also, the string '$.fn.select2' is used to reference the select2 library: the code will wait for '$' to be available (i.e. for JQuery to load), then for 'fn' to become available, then for 'select2'. Any number of dependencies can be listed, and they will be checked in order.

Below is a summary of some of the functionality provided by sadjcore.js and sadjcontrols.js; it is recommended that you review the data-editing example pages to see how these are hooked together with HTML components and the Django server.

Table Controls

The sadjcontrols code allows you to make a table editable in-place, see Edit in HTML Table. You need to ensure the table is structured as in the example, with a 'key' field to reference the record in the database, and 'field' and 'value' entries in the dataset on each row. Then adding a 'data-updateurl' to the table element will invoke the sadjcore code.

• initialiseTables - set events on all tables with a 'data-updateurl' attribute.
• tableElementInput - triggered by a keypress; sends pending changes to the server on the 'Enter' key; undoes pending changes on the 'Escape' key.
• tableElementEdited - triggered by keypress or paste; highlights edited cells.
• updatesFromTableCompleted - called to handle the server return value; highlights sucessful changes in green to provide immediate confirmation that the database has been updated.
• deleteTableRow - delete from the HTML, and from the database
• copyTableRow - duplicate the table row in the HTML (changes remain pending until a Save button is pressed or an 'enter' keypress)

Form Controls

Handling forms in a single-page application can be tricky, especially with multiple forms on one page. The Edit in Forms page has examples of multiple forms which work across MPA and SPA architectures by using the following calls:

• submit - POST a Django form from javascript, and set the return handler.
• handleRtn - re-render the form HTML based on the server response.