host

This file defines the host object.  This framework is comprised of services and constructors.  The host object contains all of the services.

Systems

ioprovides communication with the server via cookies, server push, and XMLHTTPRequests [ POST | GET | DELETE]
errorsprovides global exception handling with a cookie-based talkback system that logs client errors to the server.
statesaves gui state on server and restores it from the server.
drag and drophandles all underlying drag-and-drop functions ( you can think if it like an X-Y shipyard crane over the whole canvas).  To get specific behaviors, this system passes events through to the specific drag-drop handler of any grabbed object.
skinssystem for changing appearance and even layout on the fly.
constructorsdynamically loads constructors as they’re needed, and plugs them into host for the next use.  Many constructors (will) require CSS class definitions from constructors.css, which is located in each skin definition.
contextkeeps tack of which panel, dialog, etc. is currently focused.  This way, events like keystrokes and right mouse clicks can have context-specific results.
event routingroutes key events to the currently focused panel, dialog, etc.
panelsthe larges structural element of an app, features a cascading resize system for handling changes in the gui.
global resize(this is occluded in the app) a global resize function that calls the cascading resize functions of panel contents.
global closer(this is occluded in the app) a global function to close all menus, context menus, temp dialogs, etc in response to mouse clicks in the canvas.

Layers

gui logicGUI logic is controlled by JS code within the constructors and the specific application’s logic.
gui appearanceBecause the skin system works by swapping style sheets, appearance should be defined entirely in the CSS space.
dataThe data layer is NOT a part of host.  It should be an isolated part of each application, contained in its own namespace like myApp.data.  Methods specific to this data should be stored here too.

host also contains a collection of diverse utilities.

Summary
This file defines the host object.
Creates instances from constructor.
General init function for host.js.
host.conf conveniently stores variables that are subject to change
{boolean} when true, the cookie-based exception reporting system is active.
container for server paths
{String} relative path to directory on server containing constructors
container for date formats used with lib_nerveDate and lib_nerveDateUTC
{String} default date mask in the format “1/1/2001 01:01 PM”
host.kernel contains most services not related to managing the gui
functions for interacting with the server
direct HTTP requests
performs HTTP GET.
performs HTTP POST.
performs HTTP DELETE.
{HTMLDiv} reference to HTML DIV used by modalShield system.
starts a server-push persistent connection.
functions for getting, setting, deleting, and counting cookies
gets a cookie by name
creates cookie by name, or updates cookie if one already exists by passed name
deletes cookie by name
collection of various utilities, some of these may not be useful in enough cases to justfy being in here.
determines if DOM element has a parent
determines an element’s top and left values relative to the window object.
determines inner width of window object.
determines inner height of window object.
reads a style rule from the currently loaded style sheet(s)
for the element passed, determines the value of a style property as determined in the style sheet, not the current DOM
creates array of keys in a JS Object object
returns the position of an element within an array.
convenience method to delete an element from an array.
convenience method to get last element from an array.
convenience method to get first element from an array.
finds position of element matching passed value and returns the value of the next element, wraps around end of array if val matches last element
finds position of element matching passed value and returns the value of the previous element, wraps around beginning of array if val matches element 0
appends a new HTML attribute to a DOM element
empties a DOM element of all children
This function allows the programmer to inject new lines of code into any function at runtime.
creates Document Object from XML string
some random math functions
determines if a point is contained within a bounding box.
creates a random integer between defined min and max values
functions for working with URI strings
returns current document URI’s search string as hash of name/value pairs.
searches current document URI’s search string for value matching specified name
assembles a URI string from passed values.
assembles a parameters for HTTP POST.
functions for “path” strings used by viewer_folderTree constructor.
returns the number of nodes in a path
returns the last node string or “node name” of this path.
browser detection functions.
performs browser detection
JSON serialize/deserialize functions
JSON serializer
converts JS object into JSON string.
exception-handling functions
general exception-handling function.
writes formatted error object into cookie so the server can collect and clear it later.
displays all arguments in a nicely formatted text box, good for debugging.
container for constructors
Creates an HTML table with built-in references to all internal cells and rows.
Creates an Image object and applies a src property.
container for all things GUI
{DOMElement} reference to the whole document BODY
{DOMElement} reference to the whole document HEAD
placeholder method, it is expected that this is occluded in the application.
loads the specified stylesheet and applies its rules to gui.canvas.
container for GUI state system.
{Object} contains all local state data
sets one of an element’s state properties to a value.
gets the value of one of an element’s state properties.
Fetches all state data and copies into state_o.
sets the value of one of an element’s state property to “” in state_o and on the server.
Container for event router and event-handling methods
Binds a context menu to a DOM element via the mousedown event.
Appends an event listener to a DOM elemnent
Removes an event listener from a DOM elemnent
Returns the target of an event
Returns the target of an event
stops propagation of event object
Container for key-event-handling methods
Starts key capture, routing events to listen
Stops key capture.
Central key-handling function.
Stops propagation and prevents default action of an event.
Container for mouse-event-handling methods
This method is called whenever any mouse click occurs.
This method returns a string [“left”|”right”] depending on which mouse button was pressed.
Disables the browser’s native context menu for a specific DOM element, can be applied to the whole document body.
Binds a context menu to a DOM element via the mousedown event.
binds and object to the drag/drop system and its own internal drag/drop behaviors Each bound object’s dragDropHandler handles the specifics of drag-and-drop behavior
initiates the drag/drop process, calls the target object’s own grab function
middle of the drag/drop process, calls the target object’s own trackMouse function
ends the drag/drop process, calls the target object’s own ungrab function
Container for methods and properties to handle focus, open, and close of custom context menus
{Object} Reference to currently focused menu.
activates the current context menu
deactivates the current context menu
Container for context system.
{Array} Array of references to panels with context.
{DOMElement} reference to the panel with current persistent focus.
{DOMElement} reference to the panel with current momentary focus.
returns reference to the panel that currently has context.
Points current context (momentary or persistent) to a panel.
“tabs through” panels, pointing current persistent context to current panel.
Provides a good global place to store references to images
Provides a good global place to store reference to root panelSet
Provides a good global place to store references to dialog boxes
Provides a good global place to store references to popups windows
Closer is the system which closes all open menus, contextMenus, floaters, etc.
responds to mouse action by closing all open menus, contextMenus, floaters, etc.
The modalShield is an event-capturing div with a z-index between the canvas and a modal dialog.
{HTMLDiv} reference to HTML DIV used by modalShield system.
{boolean} tracks whether is modalShield.div is attached to the DOM
creates modalShield.div, should be called at init of app.
Makes the modalShield active.
Makes the modalShield inactive.

Functions

nu

host.nu = function(name_str,
params_o)

Creates instances from constructor.  If constructor is not found in host.kernel.constructors, it downloads it from the server and stores it in host.kernel.constructors.

Parameters

name_str(String) name of constructor

Returns

(Object) new instance from constructor.

init

host.init = function()

General init function for host.js.  This calls the init functions of other systems.

host.conf

host.conf conveniently stores variables that are subject to change

Summary
{boolean} when true, the cookie-based exception reporting system is active.

Properties

talkback

{boolean} when true, the cookie-based exception reporting system is active.  Default value is false.

host. conf. paths

container for server paths

Summary
{String} relative path to directory on server containing constructors

Properties

constructors

{String} relative path to directory on server containing constructors

host. conf. dateFormats

container for date formats used with lib_nerveDate and lib_nerveDateUTC

Summary
{String} default date mask in the format “1/1/2001 01:01 PM”

Properties

global

{String} default date mask in the format “1/1/2001 01:01 PM”

host. kernel

host.kernel contains most services not related to managing the gui

host. kernel.io

functions for interacting with the server

host. kernel. io. server

direct HTTP requests

Summary
performs HTTP GET.
performs HTTP POST.
performs HTTP DELETE.
{HTMLDiv} reference to HTML DIV used by modalShield system.
starts a server-push persistent connection.

Functions and Properties

getServerData

getServerData:function(url,
str_returnFormat,
_async_bool)

performs HTTP GET.

Parameters

urlthe URL being requested
str_returnFormatthe format of the returned value [“text”|”xml”]
_async_boolboolean values sets HTTP request to synchronous/asynchronous [true|false]

Returns

data from server as string or XML doc See Also: postServerData deleteServerData

postServerData

postServerData:function(url,
payload_str,
str_returnFormat,
_async_bool)

performs HTTP POST.

Parameters

urlthe URL being requested
payload_strHTTP POST payload,
str_returnFormatthe format of the returned value [“text”|”xml”]
_async_boolboolean values sets HTTP request to synchronous/asynchronous [true|false]

Returns

data from server as string or XML doc

See Also

getServerData deleteServerData

deleteServerData

deleteServerData:function(url,
str_returnFormat,
_async_bool)

performs HTTP DELETE.

Parameters

urlthe URL being requested
str_returnFormatthe format of the returned value [“text”|”xml”]
_async_boolboolean values sets HTTP request to synchronous/asynchronous [true|false]

Returns

data from server as string or XML doc.  See Also: getServerData postServerData

listenerIFrame

{HTMLDiv} reference to HTML DIV used by modalShield system.

initPushListener

initPushListener:function(url_str)

starts a server-push persistent connection.

Parameters

url_str{String} url of server-push persistent connection

host. kernel. io. cookies

functions for getting, setting, deleting, and counting cookies

Summary
gets a cookie by name
creates cookie by name, or updates cookie if one already exists by passed name
deletes cookie by name

Functions

get

get:function(name_str)

gets a cookie by name

Parameters

name_strcookie name

Returns

contents of cookie (as string) or null See Also: set del getCount

set

set:function(name_str,
value,
days)

creates cookie by name, or updates cookie if one already exists by passed name

Parameters

name_strcookie name
valuestring to be stored in cookie
daysnumber of days to store cookie

Returns

nothing See Also: get del getCount

del

del:function(name_str)

deletes cookie by name

Parameters

name_strcookie name

Returns

nothing

See Also

get set getCount

getCount

getCount:function()
returns number of cookies visible to browseruseful for avoiding cookie limit

Returns

integer See Also: get set del

host. kernel. utils

collection of various utilities, some of these may not be useful in enough cases to justfy being in here.  Need to evaluate.

Summary
determines if DOM element has a parent
determines an element’s top and left values relative to the window object.
determines inner width of window object.
determines inner height of window object.
reads a style rule from the currently loaded style sheet(s)
for the element passed, determines the value of a style property as determined in the style sheet, not the current DOM
creates array of keys in a JS Object object
returns the position of an element within an array.
convenience method to delete an element from an array.
convenience method to get last element from an array.
convenience method to get first element from an array.
finds position of element matching passed value and returns the value of the next element, wraps around end of array if val matches last element
finds position of element matching passed value and returns the value of the previous element, wraps around beginning of array if val matches element 0
appends a new HTML attribute to a DOM element
empties a DOM element of all children
This function allows the programmer to inject new lines of code into any function at runtime.
creates Document Object from XML string

Functions

hasParent

hasParent:function(element_ref)

determines if DOM element has a parent

Parameters

element_refreference to DOM element

Returns

[true|false]

getAbsOffsets

getAbsOffsets:function(domElement_ref)

determines an element’s top and left values relative to the window object.  This needs to be updated to include border values in the total.

Parameters

domElement_refreference to DOM element

Returns

{ left_int:left_int, top_int:top_int };

getWindowWidth

getWindowWidth:function()

determines inner width of window object.  Needed because of browser differences

Returns

window width integer

getWindowHeight

getWindowHeight:function()

determines inner height of window object.  Needed because of browser differences

Returns

window height integer

getStyleValue

getStyleValue:function(DOMElement_ref,
cssRule_str)

reads a style rule from the currently loaded style sheet(s)

Parameters

DOMElement_refDOM element reference
cssRule_strname of CSS rule

Returns

value of CSS rule

element_getStyle

element_getStyle:function(el,
styleProp)

for the element passed, determines the value of a style property as determined in the style sheet, not the current DOM

Parameters

elreference to a DOM element
stylePropstring name of style property

Returns

CSS property value, as a string

object_keyArray

object_keyArray:function(obj)

creates array of keys in a JS Object object

Parameters

objreference to a JS Object object

Returns

array of keys, unsorted

array_indexOf

array_indexOf:function(a,
val)

returns the position of an element within an array.  It returns -1 when there is no match.

Parameters

areference to array being searched
valthe value being sought.  May be any kind of JS object.

Returns

integer from -1 to a.length+1

array_deleteElementAt

array_deleteElementAt:function(a,
pos)

convenience method to delete an element from an array.

Parameters

areference to array
posposition integer

Returns

new array with element removed

array_getLastValue

array_getLastValue:function(a)

convenience method to get last element from an array.  (requested by a user, not sure if it’s useful)

Parameters

areference to array

Returns

value of last element

array_getFirstValue

array_getFirstValue:function(a)

convenience method to get first element from an array.  (requested by a user, not sure if it’s useful)

Parameters

areference to array

Returns

value of first element, or undefined if array is empty

array_getNextValue

array_getNextValue:function(a,
val)

finds position of element matching passed value and returns the value of the next element, wraps around end of array if val matches last element

Parameters

areference to array
valelement sought

Returns

value of element matching following element having passed value val

array_getPreviousValue

array_getPreviousValue:function(a,
val)

finds position of element matching passed value and returns the value of the previous element, wraps around beginning of array if val matches element 0

Parameters

areference to array
valelement sought

Returns

value of element matching preceding element having passed value val

appendNewAttribute

appendNewAttribute:function(obj_ref,
attName_str,
attValue)

appends a new HTML attribute to a DOM element

Parameters

obj_refDOM element
attName_strname or new attribute
attValuevalue of new attribute

Returns

nothing, modifies obj_ref in place

element_empty

element_empty:function(DOMelement_ref)

empties a DOM element of all children

Parameters

DOMelement_refDOM element

Returns

nothing, modifies DOMelement_ref in place

augmentFunction

augmentFunction:function(function_ref,
code_str,
lineNum_int)

This function allows the programmer to inject new lines of code into any function at runtime.  This is very useful for extending functions generated from prototypes because it’s shorter than occluding large functions with nearly-identical copies of them.  But it might also be a terrible idea, as it could make maintainance very confusing.

Parameters

function_refreference to the function being augmented
code_strstring of code being inserted, may contain line breaks as “\n”
lineNum_intline number (within function) to insert code_str

Returns

augmented function_ref

xmlStr2XmlDoc

xmlStr2XmlDoc:function(xml_str)

creates Document Object from XML string

Parameters

xml_strstring containing valid XML

Returns

Document Object

host. kernel. utils.math

some random math functions

Summary
determines if a point is contained within a bounding box.
creates a random integer between defined min and max values

Functions

isPointInRect

isPointInRect:function(x_int,
y_int,
topRightBottomLeft_a)

determines if a point is contained within a bounding box.  helpful for determining drop targets

Parameters

x_intx value of point
y_inty value of point
topRightBottomLeft_aan array of values describing bounding box coordinates

Returns

[true|false]

randomInteger

randomInteger:function(min_int,
max_int)

creates a random integer between defined min and max values

Parameters

min_intminimum value
max_intmaximum value

Returns

integer

host. kernel. utils.uri

functions for working with URI strings

Summary
returns current document URI’s search string as hash of name/value pairs.
searches current document URI’s search string for value matching specified name
assembles a URI string from passed values.
assembles a parameters for HTTP POST.

Functions

parseArgs

parseArgs:function()

returns current document URI’s search string as hash of name/value pairs.  this could be updated to take any URI string as an arg.

Returns

{ name1:value1, name2:value2, name3:value3, ...  }

searchArgs

searchArgs:function(paramName_str)

searches current document URI’s search string for value matching specified name

Parameters

paramName_strparameter being sought

Returns

[ string | undefined ]

assemble

assemble:function(base_str,
params_o)

assembles a URI string from passed values.  It should be updated to escape all strings with encodeURI()

Parameters

base_strbase URI (no search string)
params_oObject object, whose name:value pairs will become params in URI search string

Returns

URI string with search string appended

assemblePostParams

assemblePostParams:function(params_o)

assembles a parameters for HTTP POST.

Parameters

params_oObject object, whose name:value pairs will become params in POST section of request header

Returns

string of post params

host. kernel. utils.path

functions for “path” strings used by viewer_folderTree constructor.  Could also be useful for dealing with file system paths.  Maybe this goes in the tree constructor

Summary
returns the number of nodes in a path
returns the last node string or “node name” of this path.

Functions

getPathLength_int

getPathLength_int:function(path_str)

returns the number of nodes in a path

Parameters

path_strpath string

Returns

number of nodes in a path

getLastPathNodeName

getLastPathNodeName:function(path_str)

returns the last node string or “node name” of this path.  example: input=’str1/str2/str3/str4’ => output=’str4’

Parameters

path_strpath string

Returns

node name (value of last path node)

getParentPath

getParentPath:function(path_str)
returns parent path for path_strmight be more compact way to do it.  example: input=’str1/str2/str3/str4’ => output=’str1/str2/str3/’

Parameters

path_strpath string

Returns

parent path (see example above)

host. kernel. utils. browserDetect

browser detection functions.

Summary
performs browser detection

Functions

init

init: function ()

performs browser detection

Returns

nothing.  stores results in host.kernel.utils.browserDetect.browser, host.kernel.utils.browserDetect.version, host.kernel.utils.browserDetect.OS

host. kernel. utils.json

JSON serialize/deserialize functions

host. kernel. utils. json. serialize

JSON serializer

Summary
converts JS object into JSON string.

Functions

toJSONString

toJSONString:function(val)

converts JS object into JSON string.  This could use some more maturity.  The standard serializers aren’t used here because all of them extended native object prototypes.  Do not feed this method any JS objects containing circular references, as it will recurse forever.

Parameters

valJS object to be serialized

Returns

JSON string

host. kernel. errors

exception-handling functions

Summary
general exception-handling function.
writes formatted error object into cookie so the server can collect and clear it later.
displays all arguments in a nicely formatted text box, good for debugging.

Functions

handleException

handleException:function(ex)

general exception-handling function.  if host.conf.talkback == true, then talkback is called

Parameters

exthe exception object

talkback

talkback:function(exObj)

writes formatted error object into cookie so the server can collect and clear it later.  This needs to be re-written.

Parameters

exObjformatted exception object

smartAlert

smartAlert:function()

displays all arguments in a nicely formatted text box, good for debugging.

host. kernel. constructors

container for constructors

Summary
Creates an HTML table with built-in references to all internal cells and rows.
Creates an Image object and applies a src property.

Functions

HTMLTable

HTMLTable:function(numRows,
numCols,
styleNameArray)

Creates an HTML table with built-in references to all internal cells and rows.  This is not a true JS constructor, do not use the new keyword with it.

Parameters

numRowsnumber of table rows
numColsnumber of table columns
styleNameArrayoptional.  if included, each element is a CSS className and will be applied to the columns in the order presented.

Returns

table with built-in references to all internal parts.  example: myTable[0] is a reference to the first row and myTable[0][0] is a reference to the first column in the first row.

graphic

graphic:function(src_str)

Creates an Image object and applies a src property.

Parameters

src_strURI of image src

Returns

Image object

host.gui

container for all things GUI

Summary
{DOMElement} reference to the whole document BODY