Namespace jabberwerx.util (MINIMAL)

Namespace that holds a collection of functions and properties used throughout the library.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	jabberwerx.util

Field Summary
Field Attributes	Field Name and Description
<static>	jabberwerx.util.config
<static>	jabberwerx.util.debug Jabberwerx debug console.

Method Summary
Method Attributes	Method Name and Description
<static>	jabberwerx.util.clearGraph(tag) Clears storage associated with the namespace `_jw_store_`.
<static>	jabberwerx.util.clone(The) Depth-first recursively clone passed argument.
<static>	jabberwerx.util.decodeSerialization(s) Decodes a string from an obfuscated form.
<static>	jabberwerx.util.encodeSerialization(s) Encodes a string into an obfuscated form.
<static>	jabberwerx.util.findReachableGUIDs(start)
<static>	jabberwerx.util.generateInvocation(object, methodName, boundArguments) Invocations are function objects that do two nifty things.
<static>	jabberwerx.util.getLoadedGraphAge(tag) Return the delta in dates between when the graph was saved and now.
<static>	jabberwerx.util.getLoadedGraphTimestamp(tag) Return the date at which a graph was saved.
<static>	jabberwerx.util.getMaxGraphAge() Retrieve the maximum age a persisted graph can be before it is ignored and cleared on load
<static>	jabberwerx.util.invoke(invocationObject) Invoke an invocation function object.
<static>	jabberwerx.util.isArray(it) Adapted from dojo.isArray Checks if the parameter is an Array.
<static>	jabberwerx.util.isGraphSaved(tag) Returns true if the storage engine reports that the passed tag has a value stored in the namespace `_jw_store_`.
<static>	jabberwerx.util.isJWInvocation(ref) Determines if the passed reference is one of our invocation objects.
<static>	jabberwerx.util.isJWObjGUID(ref) Determines if the passed reference is a GUID for a JWBase-derived object.
<static>	jabberwerx.util.isJWObjRef(ref) Determines if the passed reference is a JWBase-derived object.
<static>	jabberwerx.util.isString(it) Adapted from dojo.isString Checks if the parameter is a String.
<static>	jabberwerx.util.loadApp(appClass) Load or create the persisted application instance.
<static>	jabberwerx.util.loadGraph(tag) Returns a ref to the root object originally stored with this tag, connected to its stored graph.
<static>	jabberwerx.util.map(arr, callback, thisObject) Adapted from dojo.map Applies callback to each element of arr and returns an Array with the results.
<static>	jabberwerx.util.newObjectGUID(className) Generate a quasi-guid for object tracking.
<static>	jabberwerx.util.persistedApplicationClass(appClass) Set or retrieve the primary application class.
<static>	jabberwerx.util.persistedApplicationInstance() Retrieve the persisted application instance.
<static>	jabberwerx.util.saveApp(appInst) save the given jabberwerx.JWApp instance to store using object's classname as key.
<static>	jabberwerx.util.saveGraph(root, tag, callback) Save an object graph.
<static>	jabberwerx.util.serialize(it, prettyPrint, _indentStr) Adapted from dojo.toJson Serialize an object; Object cycles will cause inifinite recursion.
<static>	jabberwerx.util.serializeXML(n) Generates XML for the given Node.
<static>	jabberwerx.util.setDebugStream(streamName, value) Add or overwrite the setting on a debug stream.
<static>	jabberwerx.util.setMaxGraphAge(age) Set the maximum age a persisted graph can be before it is ignored and cleared on load
<static>	jabberwerx.util.slugify(string, separator) Almost, but not quite, like WordPress's sanitize_title_with_dashes.
<static>	jabberwerx.util.unserializeXML(s, wrap) Parses the passed XML and returns the document element.
<static>	jabberwerx.util.unserializeXMLDoc(s, wrap) Pass an xml string, get back an xml document.

Namespace Detail

jabberwerx.util

Field Detail

<static> jabberwerx.util.config

Deprecated:
do not use

<static> jabberwerx.util.debug

Jabberwerx debug console. Exposes a subset of Firebug methods including log, warn, error, info, debug and dir. Jabberwerx console methods may only be passed one log message (Firebug allows formatted strings and values, ala printf) and a "stream". Streams are message types and allow finer filtering of log messages.

For example jabberwerx.util.debug.log("my foo", "bar") will log "my foo" if the stream "bar" is enabled see jabberwerx.util.setDebugStream.

If the built in console (jabberwerx.system.console) does not support a particular method the given message is not logged.

Method Detail

<static> jabberwerx.util.clearGraph(tag)

Clears storage associated with the namespace `_jw_store_`. If no tag is passed, the entire namespace is cleared. Otherwise, only the store marked by the passed tag is cleared.

Parameters:
{String} tag Optional: Optionally specify a specific, tagged store to clear.

<static> {Anything} jabberwerx.util.clone(The)

Depth-first recursively clone passed argument. Cyclical references will result in infinite recursion. Will shallow-copy an argument's prototype if it exists, and will shallow-copy functions.

Parameters:
{arg} The: object/array/whatever to clone.

Returns:: {Anything} The new cloned whatever.

<static> {String} jabberwerx.util.decodeSerialization(s)

Decodes a string from an obfuscated form.

Parameters:
{String} s: The string to decode

Returns:: {String} The un-obfuscated form of {s}

<static> {String} jabberwerx.util.encodeSerialization(s)

Encodes a string into an obfuscated form.

Parameters:
{String} s: The string to encode

Returns:: {String} The obfuscated form of {s}

<static> {String[]} jabberwerx.util.findReachableGUIDs(start)

Parameters:
{CFBase} start: The object at which to start traversing.

Deprecated:
Traverses the object graph from the passed object and records the guids of evey object reachable from the passed object.

Returns:: {String[]} An array of guids.

<static> {function} jabberwerx.util.generateInvocation(object, methodName, boundArguments)

Invocations are function objects that do two nifty things.

They wrap an (optional) JW object reference and method name, and an invocation of the bare invocation object reference is secretly an invocation of the named method on the JW object.
We treat invocation objects specially during serialization and unserialization. They carry their object GUID and method name along with them into persistence-land, and we rehydrate that info into a real function when we load the graph.

The former nifty thing means you can pass an invocation object as a callback to any service expecting a bare function reference, and, when invoked, the callback will be applied within object scope, rather than global scope.

We also cache invocation objects, so you will always get the same function object back from each call to generateInvocation when passing the same object and method name. This is useful for registering an invocation as a handler for some service that registers/unregisters handlers by function reference, (eg, dom or jQuery events) and then unregistering it later.

The latter nifty thing means that callback handlers among JW objects will be preserved across graph loading and storing and automatically re-connected when the graph is rehydrated. That's assuming, of course, that the target object was stored in the graph to begin with. Since models are generally stored, callback networks among model objects can be expected to be stored, while callbacks involving other kinds of objects will have to be re-created after unserialization. jabberwerx.JWBase.wasUnserialized and jabberwerx.JWBase.graphUnserialized are usually good places to do this.

Parameters:
{jabberwerx.JWBase} object: Any JW object
{String} methodName: The name of the method this invocation represents.
{Array} boundArguments Optional: An optional array of arguments to pass to the invocation. These will PRECEED any arguments passed to the invocation at the actual call site.

Returns:: {function} object An "invocation"-type function object.

<static> {Date} jabberwerx.util.getLoadedGraphAge(tag)

Return the delta in dates between when the graph was saved and now.

Parameters:
{String} tag Optional: The tag of the saved graph (returns null if null/undefined)

Returns:: {Date} The delta in dates between when the graph was saved and now. Returns null if tag is null/undefined, or if no store with stored tag could be found.

<static> {Date} jabberwerx.util.getLoadedGraphTimestamp(tag)

Return the date at which a graph was saved. A graph must have been loaded via jabberwerx.util.loadGraph.

Parameters:
{String} tag: Tag name for the stored graph.

Returns:: {Date} Date at which a graph was saved. Returns null if no graph was found for passed in tag value.

<static> {Number} jabberwerx.util.getMaxGraphAge()

Retrieve the maximum age a persisted graph can be before it is ignored and cleared on load

Returns:: {Number} The maximum age

<static> jabberwerx.util.invoke(invocationObject)

Invoke an invocation function object. Clients shouldn't need to call this. The first argument is the invocation object, remaining arguments are arguments to pass through to the method.

Parameters:
{Object} invocationObject: The invocation object.
{Anything} ... Optional: Remaining arguments are passed on to the invocation method.

<static> {Boolean} jabberwerx.util.isArray(it)

Adapted from dojo.isArray

Checks if the parameter is an Array.

Parameters:
{Object} it: Object to check.

Returns:: {Boolean} true if object is an array, false otherwise.

<static> {Boolean} jabberwerx.util.isGraphSaved(tag)

Returns true if the storage engine reports that the passed tag has a value stored in the namespace `_jw_store_`.

Parameters:
{String} tag: Tag name for the stored graph.

Throws:
{jabberwerx.util.JWStorageRequiresjQueryjStoreError}: if `_jw_store_` does not exist, or if it is not ready.

Returns:: {Boolean} true if the storage engine reports that the passed tag has a value stored in the namespace `_jw_store_`, otherwise false.

<static> {Boolean} jabberwerx.util.isJWInvocation(ref)

Determines if the passed reference is one of our invocation objects.

Parameters:
{Object} ref: Reference to check.

Returns:: {Boolean} true if passed reference is one of our invocation objects, otherwise false.

<static> {Boolean} jabberwerx.util.isJWObjGUID(ref)

Determines if the passed reference is a GUID for a JWBase-derived object.

Parameters:
{Object} ref: Reference to check.

Returns:: {Boolean} true if passed reference is a GUID for a JWBase-derived object, otherwise false.

<static> {Boolean} jabberwerx.util.isJWObjRef(ref)

Determines if the passed reference is a JWBase-derived object.

Parameters:
{Object} ref: Reference to check.

Returns:: {Boolean} true if passed reference is a JWBase-derived object, otherwise false.

<static> {Boolean} jabberwerx.util.isString(it)

Adapted from dojo.isString

Checks if the parameter is a String.

Parameters:
{Object} it: Object to check.

Returns:: {Boolean} true if object is a string, false otherwise.

<static> {jabberwerx.JWApp} jabberwerx.util.loadApp(appClass)

Load or create the persisted application instance. Insures jabberwerx.JWApp#appInitialize is called. Applications that want their lifetime managed via jabberwerx.app#persistedApplicationClass should use this function and not call jw#loadGraph directly.

Parameters:
{String|null} appClass Optional: The name of the jabberwerx.JWApp subclass that should be created or loaded. appClass is used as the storage key. If null this method attempts to load the managed application.

Returns:: {jabberwerx.JWApp} The newly loaded or created application

See:: jabberwerx.util#persistedApplicationClass

<static> {CFBase} jabberwerx.util.loadGraph(tag)

Returns a ref to the root object originally stored with this tag, connected to its stored graph.

Parameters:
{String} tag: Tag name stored with root object.

Throws:
{jabberwerx.util.JWStorageRequiresjQueryjStoreError}: if it is not ready.

Returns:: {CFBase} The root object originally stored with this tag.

<static> {Array} jabberwerx.util.map(arr, callback, thisObject)

Adapted from dojo.map

Applies callback to each element of arr and returns an Array with the results. This function corresponds to the JavaScript 1.6 Array.map() method. In environments that support JavaScript 1.6, this function is a passthrough to the built-in method.

For more details, see: http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/map

Parameters:
{Array|String} arr: The array to iterate on. If a string, operates on individual characters.
{Function|String} callback: The function is invoked with three arguments: item, index, and array and returns a value
{Object} thisObject Optional: May be used to scope the call to callback

Returns:: {Array} passed in array after the callback has been applied to each item

<static> {String} jabberwerx.util.newObjectGUID(className)

Generate a quasi-guid for object tracking.

Parameters:
{String} className: Class name of object.

Returns:: {String} a new guid

<static> {String} jabberwerx.util.persistedApplicationClass(appClass)

Set or retrieve the primary application class. This function manages the lifetime of the given application class. Creating, initializing, serializing and rehydrating as needed. Sets the persisted application instance

Parameters:
{String|null} appClass Optional: The name of the jabberwerx.JWApp subclass that should be created or loaded. appClass is used as the storage key.

Returns:: {String} the managed application classname

<static> jabberwerx.util.persistedApplicationInstance()

Retrieve the persisted application instance.

Returns:: jabberwerx.JWApp the persisted application instance or null if none exists.

<static> jabberwerx.util.saveApp(appInst)

save the given jabberwerx.JWApp instance to store using object's classname as key.

Parameters:
{jabberwerx.JWBase|null} appInst Optional: The JWBase object instance. Should be jabberwerx.JWApp instance but nothing prevents other jabberwerx.JWBase (persistable) objects from being stored. Uses JWBase#classname as store key.

See:: jabberwerx.util#persistedApplicationClass

<static> jabberwerx.util.saveGraph(root, tag, callback)

Save an object graph.

Pass an object to act as the "root" of the graph. Any objects you need to save should be reachable from this root. This is the object you will get back when you call jabberwerx.util.loadGraph.

Parameters:
{CFBase} root: A "root" JWBase or plain object for the graph.
{String} tag: A name for the stored graph.
{Function} callback: A callback to be invoked when the save is complete.

Throws:
{jabberwerx.util.JWStorageRequiresjQueryjStoreError}: if `_jw_store_` does not exist, or if it is not ready.

<static> {String} jabberwerx.util.serialize(it, prettyPrint, _indentStr)

Adapted from dojo.toJson

Serialize an object; Object cycles will cause inifinite recursion.

Parameters:
{Object} it: Object at which to start traversing the graph.
{Boolean} prettyPrint: Whether to include newlines and tabs in the output.
{String} _indentStr: Private to the recursion; clients shouldn't pass anything.

Returns:: {String} the JSON-serialization of the object

<static> {String} jabberwerx.util.serializeXML(n)

Generates XML for the given Node.

Parameters:
{XML DOM Node} n: XML node

Returns:: {String} XML for given node n. null if n is undefined.

<static> jabberwerx.util.setDebugStream(streamName, value)

Add or overwrite the setting on a debug stream.

Parameters:
{String} streamName: Debug stream name
{String} value: Debug stream value to set.

<static> {Number} jabberwerx.util.setMaxGraphAge(age)

Set the maximum age a persisted graph can be before it is ignored and cleared on load

Parameters:
{Number} age Optional: The maximum age in seconds, ignored if undefined or <= 0.

Returns:: {Number} The maximum age

<static> {String} jabberwerx.util.slugify(string, separator)

Almost, but not quite, like WordPress's sanitize_title_with_dashes. http://codex.wordpress.org/Function_Reference/sanitize_title_with_dashes

The difference with this implementation is that the seperator can be specified as an input parameter.

Parameters:
{String} string: String which to slugify
{String} separator: String value which to replace '-' with in string.

Returns:: {String} string but with all instances of '-' replaced with seperator.

<static> {Element} jabberwerx.util.unserializeXML(s, wrap)

Parses the passed XML and returns the document element.

Parameters:
{String} s: The XML to convert into DOM objects
{String} wrap Optional: The name of a tag in which you'd like your xml wrapped.

Returns:: {Element} An XML document element.

<static> {Document} jabberwerx.util.unserializeXMLDoc(s, wrap)

Pass an xml string, get back an xml document. Optionally pass the name of a tag in which to wrap the result.

Parameters:
{String} s: The XML to convert into DOM objects
{String} wrap Optional: The name of a tag in which you'd like your xml wrapped.

Returns:: {Document} An XML document.

Classes

Namespace jabberwerx.util (MINIMAL)