Basic applet development

Until now, the UD App has been talked about as a browser application, but it actually provides a platform for doing whatever the user community chooses to do with this tool. The number and type of future innovations seems boundless. At the moment, the horizon is wide open for devising various styles and creating applets that add a new look and feel. And also, the possibilities for new kinds of interactions between the user and the vault data are vast. At some future point, there will need to be an automated way to load or pipe data to the vault, something that lies, to some extent, within the scope of what applets do.

The developer will need to create the following items in order to produce an applet:

• A JavaScript file that handles rendering a context node page. Aside from this required task, this file will optionally initialize the app, handle mouse clicks and keybord input, and override what copy and paste command does.
• An optional CSS file.
• A modified addons.js file, one that contains an entry, in other words a stanza, for their application.
• A modified wrapper .html file, one that includes script tags pointing to their javascript and css.

Adding code to 'addons.js'

The addons.js file is what UD App uses to load JavaScript methods into the browser. A basic stanza for an application looks like this:

The required fields for a minimal applet are 'module', 'component_id', 'selection_string', and 'draw_method'. The following are explanations of all of the platform-significant fields:

'module' - (formerly 'provider') - this is a unique string that represents a group of applets that are united by a single purpose, author or provider. The module does not of and by itself uniquely identify a particular stanza in the addons.js file. Composing a string that is the concatenation of module plus component id can be used as a key to get stanza information when the applet is running. This unique string will therefore indicate unambiguously what set of methods and values apply to any specific applet.

'component_id' - this number will allow the platform to distinguish between stanzas that comprise the same module. For now, this is a required field, even if there is only one component offered by the module.

'contact_info' - this is an email that can be used to report issues with your applet code.

'selection_string' - this string value will be used in the dropdown box during vault construction or authoring. This string is stored in the vault with the node that is configured to use your applet code.

'draw_method' - this is the name of the JavaScript method that renders html for the applet. In order for this code to be called it must exist in the global space of the browser process that UD App is running in. Therefore (for 1.4 and earlier versions) it must be defined in the JavaScript (.js) file provided by the developer and linked to in the wrapper.

'keydown_handler' - this is the name of the JavaScript method that handles a keyboard event. The method will be passed a standard event object that can be used to determine the key code that the browser has detected. If the handler returns true, the platform will not continue to process the event. In order for this method to be called it must exist in the global space of the browser process. Therefore it must be defined in the JavaScript (.js) file provided and linked to in the wrapper.

'click_handler' - this is the name of the JavaScript method that handles a mouse click event. The method will be passed an event object. If the handler returns true, the platform will not continue to process the event. In order for this method to be called it must exist in the global space of the browser process. Therefore it must be defined in the JavaScript (.js) file provided and linked to in the wrapper.

'copy_function' - this is the name of the JavaScript method that overrides what happens when the user does a 'copy' of something if the scope item is configured as an instance of your applet. The method will be passed an event object that has an 'altKey' field. Copy behavior might need to be modified if the user has pressed the 'ALT' key while issuing the copy command. The Snippetizer applet demonstrates how the copy_function override can be used. The method calls the core interface method 'writeToInternalClipboard' to complete its task. This method must be defined in the global space in your applet's JavaScript (.js) file provided and linked to in the wrapper.

'initializer' - most complex applets will have an initializer. This is the name of the JavaScript method that sets up your default values or prepares them if they reside at some field attached to the scopeItem. The VaultBuilders.js file has a table applet that demonstrates some basic initializer setup. This method must be defined in the global space in your applet's JavaScript (.js) file provided and linked to in the wrapper.

Recommendations for developers

The following are some recommended practices, some things to do and not do when developing your own applet.

• Do not directly modify the vault structure
  Use createAndInsertVaultItem() and removeVaultItem() to attach and remove objects from the vault when it changes the basic tree structure of the vault. These are the APIs that are used by the sample apps. Developers should never change the structure of the vault tree from any variables providing the basic structure, such as 'cdrn' or 'labs', even if they are visible via Firebug or Chrome's debugger. Direct tampering with the vault outside of the 'core' object will be detected by the platform and user's will have the very frustrating experience of not being able to save their data. This prohibition and the safety feature that blocks the 'save' operation is designed to protect the user's vault from catastrophic data loss.
• Use the TrackingObject
  Each of the sample applets are using the object provided in the core interface as core.tracker in order to generate ids for any objects that will be part of the tab cycle. The sample applets (listed below) show how this tracker is used. The object has a next() and a down() method that inform the tracker of the current vault location. The tracker can then provide appropriate ids that reflect the relative location from the current scope item.
• Don't pollute the global space
  By encapsulating your applet methods in a container object, there will be fewer naming collisions. The global methods that are declared in the addons.js file should also be unique, so that they don't collide with names of other applets that describe a similar function. A good practice for these globally visible methods is to include the applet name in the method itself. For all other methods, a good practice is to wrap them in an object that can be easily tied to your applet.
• Postpend a 'drawing instance token' to your DOM element ids
  When your applet adds something to the DOM that will require an id, you may need to attach a drawing instance token to the end of the id to make sure it is unique for all instances of a drawn applet. One challenging aspect of this environment is that your end users may be viewing multiple instances of your applet. Not only might your applet be used to present different vault locations simultaneously, but multiple instances of the same vault location can be viewed at the same time too. This type of reuse of your app will mean that the applet code you write is executed multiple times whenever the screen is updated. You as a developer must understand when a DOM id will need to be unique to an execution context, or be commonly shared and known by all execution instances of your applet methods.

  When ids are created, generally that means either a menu or the applet drawing methods must be able to use the correct ids. This is easy in the case of platform based menus, because only a single location and DOM id are needed. If, however, a non-platform menu or widget or DOM object of some kind must be updated or tweaked, the entire set of instances must be updated, each separate instance having it's own unique id. Drawing instance tokens are used to make them unique.

  'Drawing instance tokens' are available with the most recent downloads (version 1.3.30 or later) of the UD App. To get a drawing instance token, simply use the core object api:

  core.getDrawingInstanceToken()
• Use vault storage only if necessary
  If you use a scope item (taken from core.scopeItem ) and then add fields to that scopeItem, it will inevitably be saved by users, and become a permanent part of their vaults. This increases vault size and ultimately affects performance, so follow a policy of only saving to the vault when it is appropriate. It should go without saying, adding child nodes or labels will result in those items becoming a permanent part of the vault if the users saves, and this is probably the normal case.

  You will see that other applets will use the method of creating a temporary vault item and installing it as a guest. That is done with the following two lines:

  var myItem = SharedGlobal.core.createNewVaultItem();
  SharedGlobal.core.installGuest(scopeItem,0,null,myItem);

  This prevents the vault from retaining myItem, but also allows the UD App to temporarily incorporate it into the working structure that users experience and interact with. The need for this approach is limited to certain cases where info is stored somewhere other than the vault but is loaded when the user visited an applet instance.

OOTB applet testing

The out-of-the-box testing capability comes in the form of the following HTML and JavaScript modules:

1. 'manual-gui-checks.html'
2. 'test-basics.js'
3. 'manual-gui-checks.js'

When you point your browser to:

... you will be able to step through a series of screens, one of which will look much like this:

To semi-manually run through the checks, you will follow the instruction prompt at the bottom of the screen and proceed through a series of applet actions that are verified by 'checker' code in the text codebase. The results are displayed in real time as you proceed through the checks. This not only assures that the applets you develope are actually doing what the users expect, but it is also helpful in guiding developers toward the goal of creating applets that are complete and that conform to the platform design paradigm.

A list of sample applets

The code that provides each of the different 'default presentations' currently, is available for reference when developing your own applets. Here is a list of applets, basically taken from the Edit Page popup, and the JavaScript files that contain their global methods:

• list (VaultBuilders.js)
• wrapping comma-separated list (VaultBuilders.js)
• key-value pairs (VaultBuilders.js)
• two-level view (VaultBuilders.js)
• entire branch (SampleCustomizer.js)
• table (SampleCustomizer.js)
• deep doc (Snippetizer.js)
• file cabinet (FileCabinet.js)

email: support@unitraverse.com

Our company was founded in July 2017 by Bradley Pliam.

The headquarters is currently in Austin, Texas.

Ideas that have been in gestation since the early 2000s have now finally been given 'wings'.

The mission of the company is to deliver happiness in the form of value and great user experience via high quality software, being honest about what is being delivered, and up-front about any current limitations. The world of software has some great things, along with some insidiously bad aspects. We intend to be a positive influence.

Meet our current staff...