Platform design mini-manifesto

How can tech be made more simple, easy and less of a drain on budgets and manpower? Answering this question is not hard if all you are doing is looking back on what has been done in the past and continuing on in the same trajectory, but what about new possibilites for the future? Are there unconventional ways we can push forward, accelerating things toward greater reduction of code authoring effort and fewer maintainence burdens? Taking what has worked in the past and using it more effectively is an important part of the answer. Consolidation of tasks that are common to a set of applications can be continued, and we should continue to place shared services into a framework or platform... but isn't there something more that can be done?

Whereas it may not be groundbreaking tech to place commonly shared processing into a single shared stack, much of the effort and toil required for CRUD (create, replace, update, delete) and saving to permanent storage should be done this way... it may, on the other hand, prove to be a game changing concept to have a wider range of web apps utilize a common codebase with a shared set of primitives, by limiting their internal data representation and having their gui interface conform to a single set of underlying patterns so that more can be done with a smaller codebase and less code maintenence and rewrite effort.

By reducing the number of design paradigms and streamlining a design process that conforms to unifying goals and economically satisfying objectives, a truly wonderful thing can happen: end users can get back to the business of developing and perfecting business logic, and focusing on domain relevant info and data rather than spinning their wheels on the endless parade of me-too technologies that don't necessarily gravitate toward streamlined endeavors or interoperability. A single set of GUI patterns is important, because consistent navigational cues can accelerate many processes in and around an unlimited number of applets and activities. Presumably, a single platform install process alleviates a lot of pain and frustration as well.

More specifically, what is also needed are platforms allowing users to generate scaffolding and an index-like lattice for the internet that conforms to this streamlined paradigm, with the help of software developers who will benefit from and use such common platforms to make applets available for end-user consumption.

This concept of end user navigation being enhanced, is not just a peripheral consideration for Unitraverse. It's the number one thing! Even if we nail it by having more apps benefiting from a powerful and flexible shared codebase, we will end up with more, possibly much more of the same thing that we currently have on the internet. More toll roads with annoying billboards, walls and gates that eat away valuable time for learners and students. But making it easier and faster and more enjoyable for users to find information, and having the process be part of the learning experience,... well, this can redeem the web, and accelerate extraordinary changes in society...for the better.

Content aside, forthcoming guidelines will light a path for applet developers to mimic some of the navigational cues and behaviors of the basic list applet. For example, the 'Enter' button should take people somewhere, or launch a building out process that converts a simple percept into an object that can be referenced and explored. The up and down arrow buttons should cycle through tabs that enable a set of menu items, sometimes familiar and conventional, sometimes special to the applet.

The goal is to realize a dream of effortless navigation, unimpinged activity and access, a uniform visual fabric and most importantly a content lattice, that will prove to be the favorite way to surf for learners and researchers of the world.

Unitraverse Client App APIs

Note: this section builds on concepts and ideas in previous sections. If something seems unclear or missing, it may be helpful to go back to the preceding documents.

To access the platform methods and variables you use the 'core' object. There are a couple different ways to get the 'core' object. When you are initializing your application and drawing HTML, the object is passed in as a function parameter. The first parameter in both the applet-provided initialization and HTML drawing methods is the 'core' object that exposes the API methods and data.

The other way to get the core object is by using a globally defined 'SharedGlobal' variable. This is the method you need to use when your code is running inside an event handler or other function that doesn't have access to the 'core' parameter mentioned above. Here is how you get the globally accessible object:

Variables (alphabetically)

a global integer value that indicates the height of the window's title bar.

DETAILS:

Used by applets that wish to mimic the title bar.

Title bars are drawn by the platform and, at this time the value is set to 34 pixels by default. It is currently modifiable directly and new values should persist until the user reloads the web application inside the browser, or some other applet modifies it.

a string that indicates the device platform that we are running on.

DETAILS:

Values are 'mac' | 'win' | 'android' | 'ipod' | 'iphone'. These are obtained by examining the navigator.useragent inside the clients browser environment.

an associative array whose keys are a resource id, and values are a string of comma separated group monikers.

DETAILS:

Shows membership of some resources in 1 or more tagged resource groups

a boolean value that indicates whether group mode is currently on or off

a JavaScript object that provides the screen aspect and position of the main content area of the web client application

DETAILS:

The object defines a rectangle with integer fields: width, height, top, bottom, left and right.

an array with indices that are resource item ids with element values that are booleans to indicate whether some resource is currently open

the operating system ASCII symbol used as a delimiter in a file system path.

DETAILS:

The path separator was obtained through the python or PHP agent paired with this client.

the temporary handle for the scope item being viewed inside a window pane. This handle can be used with core platform APIs to work with vault items indirectly.

a JavaScript object that provides iteration methods for traversing a vault's tree structure, accesssor functions for location-specific state, and generation of id strings that encode helpful location values.

DETAILS:

When the vault changes structure, the tracker variable does not get updated necessarily or automatically. It's better to always use'getTracker( )' to get an updated vault iterator. See the tracker api section for more details.

a string whose value is the globally unique identifier for the currently loaded vault.

Functions (alphabetically)

A convenience method for all applets to be able to prevent further propagation of the current event happening in the browser.

PARAMETERS:

event
a JavaScript object that is a valid HTML DOM event.

RETURN VALUE:

undefined

overwrites the item data for the specified node with an empty JavaScript object.

DETAILS:

Each vault item object has a dedicated data object that is intended for use by applets. At some point it seems desireable to have item data wiped clean if and when the applet is quite certain that it is likely not to be sharing nodes with other applets. This method is not guaranteed to be offered in the future.

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

undefined

converts an existing vault item, to one that is temporary, and whose contents is never saved to permanentt storage

DETAILS:

For more than a few situations, the loaded or generated vault items are not such that they should be stored permantently with the rest of the vault. Often the loading of documents or data from other sources should be incorporated into the vault only on a temporary basis.

There must be an existing vault item. This is not the most convenient approach to loading data into a vault, and is far from the most elegant. It is likely that at some future point this requirement of having an existing stub vault item will be elimanated. The work and testing needed to accomplish this is straightforward, but the bandwith is not there just now!

PARAMETERS:

parent_handle
a string that is numeric that is the id of the existing parent vault item.

child_index
an index location under the parent where the existing child vault item resides

label
a string value that will be added as a label.

app_data
a JavaScript object that will be installed as the temporary nodes vault item data object.

RETURN VALUE:

undefined

creates a new vault item and adds it to the specified location.

DETAILS:

This method will alter the vault structure if successful.

Calling this function sets a flag that will cause temporary scaffolding ids to be regenerated. That behavior is expected to change so that vault ids remain valid until the next tab refresh.

If the label is not an empty string and if it is different from the 'subject' parameter, this label will become an alias within in the parent item when it wants to refers to the child object or string.

PARAMETERS:

parent_handle
a string that is numeric that is the id of the existing parent vault item.

child_index
an index location under the parent where the new vault item will get inserted.

label
a string value that will be added as a label.

subject
a string value that becomes the main subject of the newly aded vault item.

RETURN VALUE:

a number that is the new vault item id.

creates a resource item that can can be added to a vault tree and will take on the look and feel of resources items provided by the 'add' -> 'file', 'add' -> 'url', or 'add' -> 'doc' menu commands.

PARAMETERS:

type
a string that indicates the type of resource. Expected values are 'doc' | 'url' | 'file'.

title
a string that indicates the title if the resource type is 'doc'.

filename
a string that indicates the filename of the file associated with the resource.

extension
a string that indicates the file extension of the file associated with the resource. Expected formate is '.*'.

RETURN VALUE:

a JavaScript object that is the resource item.

closes the currently open dialog box if one is open

RETURN VALUE:

undefined

shows a platform defined dialog box or popup

DETAILS:

Each platform provided dialog that is usable by applets will have popup-specific ways to provide data to, and recieve data from the popup DOM fields. Please see the sample applications for more info on this.

PARAMETERS:

popup_id
a string that indicates the popup id. The Expected values are 'simple-edit-pane' | 'alert-pane'.

RETURN VALUE:

undefined

takes a JavaScript object whose attributes are a description for generating a customized arrangment of HTML form inputs in a dialog box. The HTML is added to the DOM, as content for the custom dialog popup.

DETAILS:

The custom popup displays a variety of controls in a variety of styles. To see the available styles you can run the sample applications and check out the JSON info that they provide to 'displayCustomPopup'.

How to specify controls:
Each control that you need in the popup will have it's own JavaScript object with the following field attributes:

• value
  a boolean, string or integer value that determines the default content or state of the control. Which type to use will depend on the kind of control.
• type
  a string that must be one of the following: 'normal_text' | 'bold_text' | 'oversized_text' | 'radio' | 'checkbox' | 'edit' | 'std_edit' | 'multi_line_edit' | 'dropdown_listbox'
• box_class
  a string that must be one of the following: 'micro' | 'short' | 'medium' | 'long' | 'large' | 'listbox'
• key
  a unique string value that your applet callback function can use to access the response value for a specific control.
• text
  a string that is the message to be displayed for static text.
• options
  a list of strings that are used as options in a listbox.
• label
  an optional string that appears next to the form component to prompt users for the information that is sought.
• fmt_delim
  a string that was used as a separator inspecifying values of a series of edits on a single line. The Timeline.js applet demonstrates the placement of multiple edit boxes on a single line, as well as the usage of 'fmt_delim'.

How to obtain responses:
A callback that recieves user responses must expect a parameter value that is a map of the results from the user. The keys to the map are those same keys supplied by the 'displayCustomPopup' function. See the code sample below for more clarity on recieving user responses.

PARAMETERS:

custom_dialog_info
a JavaScript object that is a vault item.

accept_values_fn
a callback function that accepts the modified values.

CODE SAMPLE:

  function getFavoriteColorChoice(){

    var customDlgInfo = {"fields":[

        {type:"edit", label: "my favorite color:", box_class: "medium", value: "", key: "clr"}
    ]};
    SharedGlobal.core.displayCustomPopup(customDlgInfo,acceptUserResponses));
  }

  function acceptUserResponses(resultMap){
    var colorChoice = resultMap['clr'];
    doSomethingWithFavColor(colorChoice);  
  } 

RETURN VALUE:

undefined

checks to see if the item specified by a particular vault item id exists

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a boolean value that is true if the item exists, false if it does not

provides the window pane index for the currently active window.

RETURN VALUE:

a number that is the active pane index

provides a unique application instance id

DETAILS:

It is expected that after obtaining this app instance id, applet code will setup the scope item as a uniquely identified applet instance using the platform API 'setItemAppInstanceId' method.

When it is important to differentiate between applet instances, for example, for storing and accessing applet state that users will expect to be unique to some particular applet instance, an app instance id can be used.

An applet might be used for any number of vault items that have been configured to run it. With this comes the possibility of more than a single instance of some particular applet using the code, associated storage and DOM objects at the same time.

For more insight about this, check out the sample applets listed here.

RETURN VALUE:

a number that is an app instance id

gets a label string from an appropriate location, either from the parent, from an existing child object at the specified location, or from the leaf string stored at the specified location

DETAILS:

A method was needed for applets to uniformly deal with the complexity of 3 different options for determing the location of the string that represents a vault item. The three locations were necessitated by concerns with redundancy, and the need for aliasing of names of objects. The three locations, all of which are specific to a particular parent and child index, are:

• as a leaf string
• as the subject of a child object
• as an alias (a.k.a. percept) maintained with the parent object, to refer to the child object

It would have been possible to allow each applet to look in the exact same location where it placed the string, but for other applets to access that string without knowing the location, we use this conceptualization referred to as auto-configuring.

If a valid label is not found, the method returns an empty string.

PARAMETERS:

parent_handle
a string that is the vault id for the parent item

child_index
a number that is the child index location where code will look for a label

RETURN VALUE:

a string that is the item label

will obtain the current tab ids rgn.

DETAILS:

Tab ids regions are contiguous sections of the tab cycle that correspond to GUI regions on the screen. It simplifies having behavior that is taylored to the location of the current selection within the tab cycle. They are used to route control and to expedite software responses to events that dictate what is an is not appropriate behavior.

The possible regions are 'out of bounds', 'navpath', 'container', 'child', and 'resource'.

RETURN VALUE:

a string that is one of the aforementioned regions.

obtains a unique string token that differentiates numerous redundant applet drawing instances from one another so that DOM collisions and other cached memory collisions can be avoided.

DETAILS:

Applets will often need to create HTML containing id attributes that will eventually become part of the DOM. When code must later tweak the position or modify data associated with these ids, id collisions will prevent all but the last instance of that DOM object from being updated. This situation arises from the fact that having multiple windows as well as support for sym links can cause many instances of the same vault item to be displayed at the same time.

RETURN VALUE:

a string that is the drawing instance token

provides the index of the window pane that is currently being drawn.

RETURN VALUE:

a number that is the index of the currently drawn window.

obtains a WindowPane object that is the window pane that is host to the vault objects currently of concern in the execution flow of JavaScript code.

DETAILS:

The selected window is not always the window that we need to know about. Sometimes the code running because of events triggered by the active window pane needs to redraw or manipulate items that relate to some other window pane. The host window pane is the window that applet code should concern itself with when it is not responding directly to user interaction with the 'active' pane.

One common use of WindowPane objects is to obtain the 'paneId' as a basis for computing DOM ids. Ids that applets need to generate in their HTML and access later should have ids that are differentiated from other ids depending on the expected frequency of usage of the component. If an applet will always have at most one version of any scope item rendering, then it is not important to use a window pane id to qualify or make special the DOM ids. On the other hand, if there will be a different rendering or view of some scope item that can vary from window to window, then it is imperative to make sure the pane id is used to create DOM ids that are unique to each window for a particular scope item or descendant node.

WindowPane objects are needed to set the window size using the 'setMaxWindowSize' method.

Also a WindowPane object is required to obtain size information about a window using 'getContentAreaSize'

RETURN VALUE:

a JavaScript object that is the current window pane

provides the index of the window pane that is currently being drawn.

RETURN VALUE:

a number that is the index of the currently drawn window.

provides the relative path to images that reside in a platform designated folder

DETAILS:

The returned path will not include a forward slash nor a backslash as the final character. This path will not include the server name, sub-domains or TLD., but instead will be a relative path based on the whether the url points to localhost or to a cloud location.

RETURN VALUE:

a string that is the images directory relative path

obtains the current data object that was saved to the internal web application clipboard.

DETAILS:

Note that the internal clipboard is not the operating system's clipboard. There is no guarantee that web applications will have access to the OS clipboard, so an app clipboard is there as a backup. When we save to the OS clipboard we save JSON. When we save to the internal clipboard, we save JavaScript or potentially DOM objects.

RETURN VALUE:

a JavaScript object having no specific format or restrictions, that was saved previously.

obtains the application code from the specified item

DETAILS:

Note that the app code is not an app instance id. Many vault nodes can potentially share the same app code, but they will each have their own app instance ids, if one has been assigned. App codes are used to determine what applet code will be used to draw and provide interactive functionality for a node. If no app code is assigned, the default view will be the list view when a user visits that node.

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a JavaScript object having no specific format or restrictions, that was saved previously.

obtains a number that is the app instance id for a particular vault item that has applet status

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a number that is the app instance id. Returns -1 if there is no app instance id

obtains a path string that is the bound location for a particular vault item

DETAILS:

Not every node will have a bound location. This is part of platform governed node configuration. At some future point we might roll this method together with 'getItemConfiguration' to provide all configuration info with a single method call.

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a string that is the full path pointing to a file system location. Returns an empty string when no location has been configured.

obtains the number of children that a particular parent has

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a number that is the number of children. Returns -1 if the input parameters are invalid.

a number that is the handle for the vault item located under the specified parent and at the specified child index

DETAILS:

Child handles are vault identifiers for a specified child item.

Vault item handles are what we use to programmatically access vault item properties rather than directly interacting with vault item implementation objects. These are somewhat low-level and temporary identifiers that become invalid when the vault structure changes. In the future it may be preferrable to have them continue to remain valid across structural vault edits, at least until the browser tab that is host to the Unitraverse application is reloaded.

The handle for a vault item is different from any other identifiers such as app instance ids or target ids, which are permanent identifiers for special vault items. Whereas these special ids are created intentionally by applets and their users, the basic low-level handle ids this method pertains to are generated by the platform based (for the present time) on depth-first tree iteration order.

When traversing a branch of the vault, cycles are possible. Handles are not unique for each location in a fully assembled tree, and so some other mechanism must be used to differentiate instances of the same vault item encountered during recursive iterations of a branch.

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a number that is the handle of the vault item. If the specified location is not a valid location, or if the object at that location is not a JavaScript object, -1 is returned.

obtains information about what exists at the specified child index location under a specified parent.

DETAILS:

Child info helps developers get at the important information about a vault item without exposing the raw JavaScript object, which can lead to broken vaults and data loss if developer code interacts directly with certain variables impacting vault structure.

Child info fields:
The returned JavaScript object contains the following fields:

• exists
  a boolean that indicates if something exists for the specified location
• typeof
  the result of the 'typeof' operator being invoked on whatever thing exists at the given location
• isNull
  a boolean flag that will be set to true if a value of NULL resides at the specified location, otherwise it will be set to false.
• handle
  a number that is the either a valid vault item handle when the specified location points to a JavaScript vault item object, or -1 for all other cases.

PARAMETERS:

parent_handle
a string value that identifies a parent vault item.

child_index
a number or numeric string value that identifies an index location for some child item.

RETURN VALUE:

a JavaScript object that contains information about whether something exists at a specified child location, and what it is.

obtains a string that is the configuration type for the specified vault item

DETAILS:

Node configuration has specific values that indicate special handling that can happen for vault items. This is an older property of vault items that has not proven to be that necessary, as of yet.

Configuration types:

• app-defined
  this means that applets have set the bound location field rather than the platform

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a string that is the configuration type. Returns an empty string of no setting is specified.

obtains a JavaScript object that is the container for all applet-defined data associated with a vault item.

DETAILS:

The item data attatched to vault items is stored permanently in a vault. This special location is shared by any applets that may acquire responsibility for the vault item nodes containing data. The core platform is not expected to use or assign values to the item data object and no naming collisions will arise on account of the platform's use of that object.

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a JavaScript object that contains all applet data.

obtains a value that corresponds to the specified name that is contained by the data object at the specified vault item

DETAILS:

The vault item data object is available to app code, but sometimes it will be easier to just get a specific attribute of that object using this method.

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

attribute_name
a string value that identifies the object field needed from the specified vault item.

RETURN VALUE:

a value that is either a JavaScript object, string, number, boolean, specified by the method inputs

obtains a string that is the most appropriate string for a label for the given location

DETAILS:

The algorithm used to fetch a label using this method is to return the first string found using an ordered list of specific locations: first check for any parent-held alias that represents this vault item/child location. If none is found, we search for a leaf string that exists at the actual specified location. If that is not found, then we try to get the subject field of a child object. When all else fails an empty string is returned.

PARAMETERS:

parent_handle
a string that is the vault id for the parent item

child_index
a number that is the child index location where code will look for a label

RETURN VALUE:

a string that is the configured label

obtains the JavaScript object that is the specified resource item

DETAILS:

The index provided does not pertain to the child items that largely dictate the vault structure. It relates only to a resource array of resource objects at a particular vault item.

The following fields are provided by resource objects:

Resource object fields:

• type
  this string indicates the type of resource item, which will be one of the following: 'url' | 'doc' | 'file'
• ttl
  a string that is the title of the resource
• url
  a string that is the url location for resources of type 'url'
• filename
  a string that is the filename of the resource for resources of type 'doc' or 'file'
• ext
  a string that is the filename extension for resources of type 'doc' or 'file'
• path
  a string that is the full or relative path for resources of type 'doc' or 'file'

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

resource_index
a number that identifies the location in the resources array

RETURN VALUE:

a JavaScript object that is the resource object.

obtains the JavaScript array that holds resource items for the given vault item

DETAILS:

For more info about resource items, see the 'details' section in the 'getItemResource' method documentation (above).

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a JavaScript array that is a list of resource objects

obtains the string that is the main subject of the specified vault item

DETAILS:

The subject of a vault item is the main string characterization for what that vault item is about. The subject string is intended to be used in title bars, headings and possibly as a path component for the navigation path for a window.

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a string that is the subject for a vault item

ascertains whether or not the title bar is visible for the specified vault item

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

a boolean that is true if the title bar is visible, otherwise false

obtains a string that is the persistent drawing instance token for distinguishing drawing instances in the multi-window environment

DETAILS:

The need for tokens can be understood when we consider multiple windows and mutlitple instances of an app. The various windows and app instances will invoke the same code and that code must somehow be wise enough to know where to find state information that is approprate for multiple windows and sometimes multiple instances of the same node drawn inside the same window. Also, DOM elements that need to be given an id must have some way of being unique, and this method is another way to make such ids unique among all drawn instances within the Unitraverse client application.

This method obtains drawing tokens that will be either constructed by the platform without any applet assistance, or built by a provider applet. In order to supply applet-built tokens, your code must use the 'core.supplyPersistentDrawingInstanceToken()' api method. The process of obtaining a token does not change, but when a hosting applet is the scope item and has hosted applets that must self-draw and track their state, the scope item applet will need to queue up the correct token for any particular context. See the 'core.supplyPersistentDrawingInstanceToken()' api for more information on applet-provided tokens.

Platform-generated tokens are specific to a vault item's 'appInstanceId' and the window id that is used to display applet HTML. Clearly, platform-built tokens are not adequate when your applets anticipate multiple instances of the applet will be drawn inside the same window. One side-affect, therefore is that a scope item that does not have an 'appInstanceId' will be given one in cases where this method is called and no 'provider' has queued up a token. Supplied tokens continue to be used until the user navigates away from the scope item or the window is closed, whichever happens earliest.

RETURN VALUE:

a string that is the drawing-instance token.

obtains a tracker object that is set to a specific node within the vault tree relative to the current scope item.

DETAILS:

No input parameters are needed by this function because the relative position is computed from the current tab id selection. See the tracker api section for more information about trackers.

RETURN VALUE:

a JavaScript object that is a tracker set to begin iteration and tracking at a specified descendant position.

obtains a tracker set to a vault position supplied by the caller.

DETAILS:

See the tracker api section for more information about trackers.

A path route extension, or prx, is an array of child indices that describe a route from the scope item of a specified window pane, to some descendant location within the scope item branch. One example might be the prx '2.4.9', which describes the 10th child of the 5th child of the 3rd child of the scope item node.

PARAMETERS:

prx
a string that is the 'path route extension'.

child_index
a number that is the child index of the selected child label that belongs to the deepest vault item implied by this position.

pane_index
a number that is the index of the specified window pane.

RETURN VALUE:

a JavaScript object that is a tracker set to begin iteration and tracking at a specified descendant position.

obtains a JavaScript object whose fields hold the values that define the current selection state.

DETAILS:

Selection state involves more than just a simple single selected item, it entails a selected child under a selected parent and the tab cycle id grouping called a zone (a.k.a. 'region').

RETURN VALUE:

a JavaScript object indicating the current selection with the following fields:

scopeIndex
a number that is the item id for the current scope.

rgn
a string that indicates the current contiguous range (a.k.a. 'zone') in which the selected tab id is found, for a given window. Values can be 'out-of-bounds' | 'navpath' | 'container' | 'child' | 'resource'.

zoneIndex
a number that is the nth index for some zone or region. For example, if the 'rgn' is 'child' then the zone index is a child index. If the region is 'resource', then the zoneIndex is valid for accessing items in the resources array.

scopeItem
a JavaScript object that is the current scope item for some window.

accessScopeIndex
a number that is the parent id of a selected item in either a multi-level view or a single level view.

accessZoneIndex
a number that is the child index of a selected item in either a multi-level view or a zone index in a single level view.

obtains the current position in the tab cycle array.

DETAILS:

The tab id pos is specific to the current active pane in a response to user events. This method will not work properly for code execution intended for windows that are not the active pane.

Hanging on to a tab id is never a good idea, because users can move about in the same scope very quickly and a function to get the current position in the tab cycle is needed instead of a static tab position.

RETURN VALUE:

a number that is the zero-based index associated with the current tab id array position.

obtains a unique temporary id for any use or purpose specific to the current vault.

DETAILS:

No other temporary id assigned will collide with ids obtained via this function unless they are kept permantently, which is a misuse of this id. The temporary id will be valid until the next load of the web application. Rather than force the vault's resource or link id counters up, only to leave unused ids down the road, a separate counter for temporary ids is used to provide the ids.

RETURN VALUE:

a unique number that is the temporary id.

obtains a JavaScript object that is a tracker set to the scope item position.

DETAILS:

Trackers are used to iterate through a vault tree branch and the perform some bookkeeping duties that allow it to generate proper id strings for the tab cycle. When using the tracker to generate ids, the platform can handle higlighting of selected items in the tab cycle and navigation into the child items when users press the 'Enter' button.

Code will push the tracker generated ids to a tab cycle array during drawing in the following way...

CODE SAMPLE:

  function generateHTML(core,callback){

     var html = "";

     var iter = core.getTracker();

     var len = iter.childCount();

     for(var i=0; i<len; i++){

        var curIdString = iter.getIdString();

        SharedGlobal.tic.push(curIdString);

        html += '<div id="' + curIdString + '">' + 

           iter.label() + '</div>';
 
        iter.next();

     }
 
  }

See the tracker api section for more details.

RETURN VALUE:

a JavaScript object that is a tracker.

obtains a storage object intended for all instances of some applet or applet grouping.

DETAILS:

The vault shared storage is a permanent location in the current vault that can store information that is useful for all users of the vault. It would not be the ideal place to keep user-specific information, but thus far no facility is yet in place for that kind of storage. The shared storage object is just a non-descript JavaScript object that can have custom fields added to it, in order to accomodate and store any data required by the applet.

RETURN VALUE:

a JavaScript object that is the shared storage for the given key.

obtains a stringified version of the vault after first collapsing it.

DETAILS:

A collapsed vault has none of the cycles or duplicate branches that happen because of sym links. In other words, none of the guest vault items are installed, only the link stubs that are present when the vault is saved to disk. Other associated data, such as external links relavent to this vault, or user info referencing it, is not captured by this function.

RETURN VALUE:

a string that is a copy of the collapsed vault.

obtains a window pane from the window pane index.

PARAMETERS:

pane_index
a number that is the index of the desired window pane.

RETURN VALUE:

a JavaScript object that is the window pane.

obtains HTML from vault locations chosen by applet code.

DETAILS:

When an applet draws a page, it may want to bring in HTML from some other node that is knows will contribute something belonging to it's own page. This enables nested drawing with some limitations on things such as the tab cycle or injection of menuitems.

RETURN VALUE:

a string that is the generated HTML

inserts a string value as a child of the specified parent at the specified child index location

DETAILS:

The vault structure is a tree that has inner nodes and leaf nodes. The structure of the tree is determined more by inner nodes than leaves. When a string is added as a child to some vault item, it becomes a leaf node.

This non-homogenous design for children vault items allows for spacial efficiency when the vault is stored to the file system.

PARAMETERS:

parent_handle
a string that is the vault id for the parent item

child_index
a number that is the child index location where code will look for a label

RETURN VALUE:

undefined

inserts a JavaScript object that is the new resource item to be added to the specified vault item

DETAILS:

This provides a way for applets to add their own resources to look and behave like the resources that are added by the platform when the users use the 'add' menu commands for adding resources. The properties that resource objects might require are mentioned in the 'getItemResources()' method documentation.

To get more information on the usage of this method, check out the sample applet 'FileCabinet.js'

PARAMETERS:

parent_handle
a string that is the vault id for the parent item

child_index
a number that is the child index location where code will look for a label

resource_object
a JavaScript object that is the resource to be added. The fields

RETURN VALUE:

undefined

indicates whether or not there are changes to the vault that haven't yet been saved to disk.

RETURN VALUE:

a boolean value that is true if there are unsaved changes to the vault, false otherwise.

changes the current scope for the active window pane to a specified location.

PARAMETERS:

handle
a string that is the temporary handle of the vault item to open, making it the current location, (a.k.a. making it the scope item) for the active window pane.

RETURN VALUE:

undefined

indicates if a given point is inside a given rectangle.

DETAILS:

The input point and rectangle are assumed to have the same coordinate systems.

PARAMETERS:

x_coordinate
the x coordinate in pixels

y_coordinate
the y coordinate in pixels

rectangle
a JavaScript object with integer fields: width, height, top, bottom, left and right.

RETURN VALUE:

true if the point exists inside the rectangle, otherwise false.

converts a null or string child for the specified vault location into an object that can be navigated into

DETAILS:

Direct access to vault item objects are not provided in the API. When an applet needs to convert a string child or null child into an full fledged vault item object, this provides a way to do so without deleting and creating in separate steps.

PARAMETERS:

parent_handle
a string value that identifies a parent vault item.

child_index
a number that is the index location of the child target item under the parent.

hide_title_bar
a boolean value that indicates whether the platform should display the title bar or not.

RETURN VALUE:

undefined

alerts the user unsaved changes that have been made to the vault. Users will see an asterisk (*) near the save menuitem. They will also get an alert box when attempting to navigate away from the Unitraverse application without first saving their changes.

RETURN VALUE:

undefined

causes any selected item inside the currently active window pane to be removed from the vault.

DETAILS:

This method removes the currently selected vault item in the active window pane. In most cases user interaction is directed toward the active window pane, however, in the case where removal must be done in a window pane that is not currently the active pane, applet code should use the alternative 'removeVaultItemAtArbitraryLocation()' method.

RETURN VALUE:

undefined

causes the specified vault item to be removed from the vault.

DETAILS:

This method removes a vault item pointed to by the given location. This location is not dependent on the item selected in the currently active window.

When 'remove-branch' is provided as a subtype, the entire branch is removed, including the descendant items

When 'remove-item' is provided as a subtype, the behavior mimics ALT-remove

PARAMETERS:

operation_subtype
a string that specifies if the entire branch should be removed or only the selected object. Expected values are 'remove-item' | 'remove-branch'

parent_handle
a string value that identifies a parent vault item.

child_index
a number that is the index location of the child target item under the parent.

RETURN VALUE:

undefined

sends a request to the Python or PHP agent paired with this web application for files and subdirectories contained in a specified OS file system location.

PARAMETERS:

path
a string that is the complete or relative path to a file directory.

callback
a function that will recieve the directory content info.

RETURN VALUE:

undefined

sends a request to the Python or PHP agent paired with this web application for the contents of a specific OS file system file.

PARAMETERS:

file_fqfn
a string that is the fully qualified filename (including the OS directory path) for the file.

callback
a function that will receive the contents of the file.

RETURN VALUE:

undefined

starts an immediate redraw for the entire vault.

DETAILS:

Any applet can request a redraw at any time. This redraw does not reload any applets or run their initialization functions.

RETURN VALUE:

undefined

adds an object and attribute to the auto-manage list and initializes the specified attribute and object with the given initial value.

DETAILS:

Protecting our permanently stored vault from accumulating large amounts of temporary runtime data will have a direct impact on end-user experience. However, using 'scope items' to stash some state information is a seemingly necessary thing to do, so one of the solutions is to create a field that is automatically removed before serialization. This function provides just such a field.

Note: it is not necessary that the supplied object be a context node. Any object that becomes attached to the vault but should not be permanently saved to disk can be auto-managed, with a few exceptions that should seem obvious... such as auto-managing some object that is critical for the serialization routine to function.

PARAMETERS:

object
a JavaScript object.

attribute_name
a string that is the name of the field that is removed during save operations and restored immediately after.

initial_value
any valid JavaScript primative, object or value.

RETURN VALUE:

undefined

sets the app code value for the specified vault item

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

undefined

sets the app instance id value for the specified vault item

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

undefined

sets the configured path location for the specified vault item

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

undefined

sets the configuration string for the specified vault item

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

RETURN VALUE:

undefined

sets the value for the specified attribute name for the specified vault item

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

attribute_name
a string value that is a data attribute name for the specified vault item's associated data

value
a value that is the value to be set for the specified attribute.

RETURN VALUE:

undefined

sets the subject for the specified vault item

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

subject
a string value is the subject

RETURN VALUE:

undefined

specifies whether the platform provided title bar is visible or not when the item is the scope item

PARAMETERS:

item_handle
a string value that identifies a particular vault item.

is_visible
a boolean value to indicate if the platform should render a title bar

RETURN VALUE:

undefined

specifies whether the platform provided title bar is visible or not when the item is the scope item

DETAILS:

When there is a maximum size, the benefit for larger screens is that some windows are then not allowed to stretch across or down the entire screen where applet code determines this is generally not needed.

The default window size is determined by the platform to use as much or all of the space that is available. When there are multiple applet windows being used, the available space is shared, causing the windows to become smaller. The available horizontal space is used by default. A window's content can be the primary determining factor for verical sizing of windows if it doesn't exceed the available vertical space. A maximum size overrides all of these factors.

PARAMETERS:

window
a JavaScript object that is the window object

max_width
the maximum width in pixels that the window should expand to max_height
the maximum height in pixels that the window should grow to

RETURN VALUE:

undefined

puts in place a callback function that will receive the results of the simple edit popup if the user accepts the new value.

CODE SAMPLE:

RETURN VALUE:

undefined

adds a menuitem at the specified menu location and with the specified handler and shortcut

DETAILS:

the platform provides a shared menu, with a degree of uniform structure, for the benefit of the user. The 'responsive' nature of the created menuitem means that it turns off and on (becomes active and deactivates) when the appropriate things are selected in the active window, provided that any applet-supplied 'allow' function also returns true.

PARAMETERS:

window_id
a number that is the index for the window that sends the menuitem contribution two the composite menu.

group_name
a string that is the name of the top-level branches of the main menu. There are four supported group names that appear in the following order in the main menu:

• 'gleaner' - currently seafoam green menuitems that have to do with users that are purely consumers of vault data rather than authors
• 'author' - currently lavender menuitems that provide actions related to editing and authoring of vault content.
• 'applet' - currently yellow menuitems that provide actions related to the current applet.
• 'platform' - currently pink menuitems that are odd & ends or related to the platform or environment.

command_sequence
a string that describes the menuitem location. The provided command sequence is used to generate components that start with a root menuitem and extends to the final, operative menuitem, using auto-generated submenus that are populated using multiple calls to this method.

tab_cycle_region_code
a string that signifies the selection locations in a window pane that allows the target menuitem to be active. Values can be 'out-of-bounds' | 'navpath' | 'container' | 'child' | 'resource'.

allow_function
a function that adds an extra requirement for enabling menuitem activation. Regardless of how restrictive or inclusive the set of tab cycle regions being specified for activation might be, this function increases the restrictiveness, returning true if the menuitem can be active and false if it should not be.

label_id
a number that is the id for the text element of the menuitem that can be used by applets to manipulate or decorate.

shortcut_key
a string that is the shortcut key, (implemented by other code).

menu_action
a function that is the handler for click events on this menuitem.

MORE DETAILS:

It can be safely assumed that when handlers are invoked, the current window is the active window. Handlers are associated with a window and deactivated when their window is not the active window.

RETURN VALUE:

a JavaScript object that is the command info. This info is used internally, and not likely to be used by applets.

loads the specified message to the DOM object that will prompt users for a edit box response.

RETURN VALUE:

undefined

sets the background color used for platform-generated title bars for a particular window pane.

DETAILS:

The use of this function is not as straight forward as we all might like it to be! The HTML for platform-drawn title bars is rendered *before* the content code is drawn. That means if you wait for your applet to draw itself and decide to use this function in your HTML rendering code, the icon will not appear.

PARAMETERS:

window_id
a number that is the id for a window.

color
a string that is the CSS-legal color.

RETURN VALUE:

undefined

sets color used for platform-generated title bars for a particular window pane.

DETAILS:

See the 'DETAILS' section for 'setTitleBarBgColor()'.

PARAMETERS:

window_id
a number that is the id for a window.

color
a string that is the CSS-legal color.

RETURN VALUE:

undefined

sets the icon used for platform-generated title bars for a particular window pane.

DETAILS:

See the 'DETAILS' section for 'setTitleBarBgColor()'.

All of this to say, each of the above title bar functions need to be invoked during applet initialization, or when a user event is going to cause or bring about customization for a title bar.

PARAMETERS:

window
a JavaScript object that is the target window.

icon_resource
a string that is the OS path (in the future, a URL) at which resides a bitmap file.

RETURN VALUE:

undefined

sets the title of a title bar for a particular window pane, overriding the normal behavior of using the scope item's title.

DETAILS:

See the 'DETAILS' section for 'setTitleBarBgColor()'.

PARAMETERS:

window
a JavaScript object that is the target window.

title
a string that is the title.

RETURN VALUE:

undefined

specifies the token that will be used when a persistent token is requested for a particular window via the global getter method

DETAILS:

Applet-supplied tokens should be made available with this method and accessed using the 'core.getPersistentDrawingInstanceToken()' method. The intent is that when aggregator or provider applets are the scope item, they handle all the events that are important to the app instance and its hosted applets, and it is expected that such container applets supply persistent tokens that are appropriate to the handling of the event or drawing situation. After supplying an appropriate token, your applet code can invoke responses from a hosted applet or for any of its own sub-components. Tokens allow these responses to be based on a 'store' or state information that is in this way 'bound' to the applet code. This process can be repeated for any other hosted applets. Hosted applets must be written in such a way that they can be used in this context outside of the normal platform-mediated convention that is impemented when they are scope items rather than hosted by a container scope item applet.

When the platform-built token is not appropriate, as in the case when more than a single instance of an applet must draw in ways that are unique (different from other drawn instances within the same window), an applet-supplied token must be constructed and provided. A 'persistent' token will not necessarily reside in memory, although it might, but it will be an unchanging component of a key or id that can survive multiple drawing cycles. How applet-built keys might be constructed, how they might survive and be generated across multiple drawing cycles, and how they can be unique and valid in a multi-window multi-applet-instance environment is left to applet designers.

PARAMETERS:

token
a string that is the custom token that will be accessed when 'core.getPersistentDrawingInstanceToken()' is used

window
a JavaScript object that is the window that will deploy applet instances that must use the drawing token

RETURN VALUE:

undefined

updates the core platform variables to which applets are given access.

DETAILS:

The vault and platform interface variables are copies of internal values that frequently change. Moving to a new location, toggling groupMode and some other things can require that these static values are refreshed.

The following are variables that get refreshsed:

• scopeItemIndex
• pathIds
• tracker
• childIds
• groupMode

RETURN VALUE:

undefined

sets a conceptual 'label' based on the situation and configuration that exists at the specified location

DETAILS:

Thanks to certain design priorities, the platform supports three different locations for essential vault item text descriptions: percepts, vault item leaf strings, and the subject field of vault item objects. The 'auto-configured label' algorithm provides way for applets to make edits that can abstract away the underlying complexity where each location can impact a derived label.

To support a single location would work also and achieve greater code simplicity, but it is likely to have a limiting and detrimental effect on portability of vault data from one applet to another. There may be situations where an applet needs to set a specific label location explicitly.

To set a leaf string explicitly, use updateLeafString() or insertLeafString()

To set or access subject strings explicitly, the platform provides getItemSubject() and setItemSubject()

If the label is not an empty string and if it is different from the 'subject' parameter, this label will become an alias within in the parent item when it wants to refers to the child object or string.

PARAMETERS:

parent_handle
a string that is numeric that is the id of the existing parent vault item.

child_index
a number that is the child index location for which a label update will be made

label
a string value that will be used to update the parent objects perception of the child

RETURN VALUE:

undefined

sets the leaf string value at the specified location

PARAMETERS:

parent_handle
a string that is the vault id for the parent item

child_index
a number that is the child index location where code will look for a label

value
a string that will be the new leaf string value

RETURN VALUE:

undefined

copies the specified data to the internal clipboard.

DETAILS:

The internal clipboard is not the OS clipboard, and it does not persist beyond the life cycle of the current web application.

RETURN VALUE:

undefined

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 not so great things. We intend to be a positive influence.

Meet our current staff...