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.
At the time of writing this, no developer community has come together around the goal of building applets for the UD App. It could be, since you are reading this, that you are at the very leading edge of it. There is not a news letter or email chain. There's not a dedicated website or Git repository. This article is just the start of what I hope grows into something that people care about and that they will use to make life better for themselves and perhaps eventually, their clients.
The developer will need to create the following items in order to produce an applet:
- An optional CSS file.
- A modified addons.js file, one that contains an entry, in other words a stanza, for their application.
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.
Do notdirectly modify the vault structure
Use core.addVaultItem() and core.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();
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.
A list of sample applets
A list of sample applets
- 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)
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...