Unitraverse Desktop Productivity
Application
Documentation
Section 15
Products
Contact us
About us
Section 15
Unitraverse Desktop Productivity Application - Version 1.4

Tracker objects

A tracker object provides an interface that allows applet code to traverse the vault tree structure and access it's contents. In this regard it is an 'iterator', but there's more to the story. It is not merely an iterator because it also provides services and keeps track of travel state when users navigate into the vault.

A tracker design decouples vault data and methods from applet code that will want to be free of the implementation details. At the same time, this intermediate object can protect the vault from direct manipulation, which is discouraged and can end up blocking a user's ability to save their data.

To obtain a tracker object you must first have the core object:

var tracker = SharedGlobal.core.tracker;

or you must have a tracker object pointing to a parent and use 'down()' to get a new tracker positioned at (a.k.a. pointing to) the current child:

var tracker = parentTracker.down();

Tracker variables (alphabetically)

tracker.levelDepth

a number that is the current depth relative to the initial depth from which the first tracker (not spawned from another tracker) was positioned at.

DETAILS: The levelDepth is set initially at level 1 upon creation of the tracker regardless of the location it initially points to in the tree. When a tracker is created via the function 'down()', this depth level is not set to 1, but rather is taken from the previous tracker and incrememted. The passed along value is continually incremented in this way until it reaches maxDepth. Trackers do not descend further once maximum depth has been reached.

tracker.maxDepth

a number that is the current limit on how many levels deep a tracker can descend into any descendant nodes.

DETAILS: The depth starts at level 1 upon creation of the tracker regardless of the location it initially points to in the tree. When the tracker is created via the function 'down()', the level is incrememted until it reaches the maxDepth. Trackers do not descend further once maximum depth has been reached.

An expanded tree can have cycles, and forcing applets to explicitly change the max recursion depth places a safeguard around infinite recursion issues. In other words, this member variable can be set by the applet that has possession of the tracker.

A value of -1 will cause maxDepth to be infinite. The default is set at 60 levels.

tracker.tempChildIndex

a number that is the child index for a visited item (a.k.a. a temporary scope item).

DETAILS: The child index is the position, in other words the 'rank', of a vault item among its siblings.

tracker.tempScopeItemIndex

a number that is the index for a visited item (a.k.a. a temporary scope item).

DETAILS: The tracker object provides a tempScopeItemIndex, whereas the core object provides a scopeItemIndex. The scope item is more permanent than the temporarily visited scope item that trackers have in their buffers.

Tracker functions (alphabetically)

tracker.child()

obtains the child vault item from an array index.

PARAMETERS:

child_index
a number that is the index of the child being accessed.

tracker.childItemCount()

obtains the number of children at the current tracker location.

RETURN VALUE:

the number of children.

tracker.down()

obtains a JavaScript object that is a new tracker, positioned at the location implied by the current child index and parent

RETURN VALUE:

a JavaScript object that is the new tracker.

tracker.getIdString()

obtains an encoded string that is used by applets as a unique DOM id for an HTML object and as a value from which the platform can extract navigation hints.

DETAILS: The four part id not only is unique, but it also tips off the core platform when the user has chosen to visit a location encoded by the id. When the id is split, the string becomes:

  1. the vault item id
  2. the child index
  3. the region id
  4. a unique drawing token

Note: if applet-provided HTML generation code does not use this id string format in the tab sequence, navigation using the 'Enter' key or via double-clicking will not function.

The following code pattern can be seen throughout the sample applets JavaScript:


    SharedGlobal.tabIdsPos++;
    DefaultFormat.cnItemDex++;
    var curIdString = tracker.getIdString();
    var html = "<div class=\"basic-child-item\" id=\"" + curIdString 
            + "\">" + tracker.label(0);
    SharedGlobal.tabIdsBuffer[SharedGlobal.tabIdsPos] = curIdString; 

RETURN VALUE:

a string that is the encoded id string.

tracker.getPathRouteExtensionString()

obtains the current path route string.

DETAILS: the 'prx' that is in string form will be delimited by the '.' decimal character. See the 'getRelativePositionTracker' explanation for the 'prx' parameter.

RETURN VALUE:

a number that is the index for a vault item.

tracker.getScopeIndex()

obtains the current temporary scope item index.

RETURN VALUE:

a number that is the index for a vault item.

tracker.getScopeItem()

obtains the current temporary scope item

DETAILS: The temporary scope item will usually differ from the current scope item for the drawn window. Temporary scope items are visited briefly in order to draw or do some other sort of processing.

RETURN VALUE:

a JavaScript object that is the scope item for the current tracker position.

tracker.isChildEmpty()

detects whether or not the child item is both non-null and has vault objects of its own either in the children array or the resources array.

RETURN VALUE:

true if the child exists and has at least one child object of its own or at least one resource, otherwise false.

tracker.isEngraftingLocation()

detects whether or not the current vault item was placed there via the linking mechanism or not.

RETURN VALUE:

true if the parent and child index of the current vault item are associated with a link target, otherwise false.

tracker.label()

obtains a string that is the label (a.k.a. 'percept') for a vault item at the specified child position.

PARAMETERS:

child_index
a number that is the index of the child being accessed.

RETURN VALUE:

a string that is the vault item's label.

tracker.next()

advances the child index.

RETURN VALUE:

undefined

tracker.resource()

obtains a JavaScript object that is the resource at the provided resource index.

PARAMETERS:

resource_index
a number that is the index of the resource being accessed.

RETURN VALUE:

a JavaScript object that is the resource.

tracker.resourceItemCount()

RETURN VALUE:

obtains the number of resource items contained in the current vault item.

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...

Brad Pliam - Dev lead

Unitraverse