Namespace RapidContext.Util

Provides utility functions for basic objects, arrays, DOM nodes and CSS. These functions are complementary to what is available in MochiKit and/or jQuery.

Source code: RapidContext.Util.js

Namespace Summary
 
Method Summary
<static>  
RapidContext.Util.attributeArray(node)
Returns an array with DOM node attribute name and value pairs.
<static>  
RapidContext.Util.blurAll(node)
Blurs (unfocuses) a specified DOM node and all relevant child nodes.
<static>  
RapidContext.Util.childNode(parent, indexOrNode)
Returns an immediate child node from a parent DOM node.
<static>  
RapidContext.Util.createDOMExt(ns, tag, attrs)
Creates a DOM node with a namespace.
<static>  
RapidContext.Util.createDOMFuncExt(ns, tag, args, attrs)
Returns a function for creating a specific kind of DOM nodes.
<static>  
RapidContext.Util.createTextNode(text)
Creates a DOM text node from the specified text.
<static>  
RapidContext.Util.dict(itemsOrKeys, values)
Creates a dictionary object from a list of keys and values.
<static>  
RapidContext.Util.functionName(func)
Returns the name of a function.
<static>  
RapidContext.Util.isDOM(obj)
Returns true if the specified object looks like a DOM node.
<static>  
RapidContext.Util.isHTML(obj)
Returns true if the specified object looks like an HTML or XHTML DOM node.
<static>  
RapidContext.Util.mask(src, keys)
Filters an object by removing a list of keys.
<static>  
RapidContext.Util.registerFunctionNames(obj, name)
Registers function names for anonymous functions.
<static>  
RapidContext.Util.registerSizeConstraints(node, width, height, aspect)
Registers algebraic constraints for the element width, height and/or aspect ratio.
<static>  
RapidContext.Util.resizeElements()
Resizes one or more DOM nodes using their registered size constraints and their parent element sizes.
<static>  
RapidContext.Util.resolveURI(uri, base)
Resolves a relative URI to an absolute URI.
<static>  
RapidContext.Util.toTitleCase(str)
Converts a string to a title-cased string.
Namespace Detail
RapidContext.Util
Method Detail
<static> {Object} RapidContext.Util.dict(itemsOrKeys, values)
Creates a dictionary object from a list of keys and values. Optionally a list of key-value pairs can be provided instead. As a third option, a single (non-array) value can be assigned to all the keys.

If a key is specified twice, only the last value will be used. Note that this function is the reverse of MochiKit.Base.items(), MochiKit.Base.keys() and MochiKit.Base.values().
RapidContext.Util.dict(['a','b'], [1, 2])
⇒ { a: 1, b: 2 }
RapidContext.Util.dict([['a', 1], ['b', 2]])
⇒ { a: 1, b: 2 }
RapidContext.Util.dict(['a','b'], true)
⇒ { a: true, b: true }
Parameters:
{Array} itemsOrKeys
the list of keys or items
{Array} values Optional
the list of values (optional if key-value pairs are specified in first argument)
Returns:
{Object} an object with properties for each key-value pair

<static> {Object} RapidContext.Util.mask(src, keys)
Filters an object by removing a list of keys. A list of key names (or an object whose property names will be used as keys) must be specified as an argument. A new object containing the source object values for the specified keys will be returned. The source object will be modified by removing all the specified keys.
var o = { a: 1, b: 2 };
RapidContext.Util.mask(o, ['a', 'c']);
⇒ { a: 1 } and modifies o to { b: 2 }
var o = { a: 1, b: 2 };
RapidContext.Util.mask(o, { a: null, c: null });
⇒ { a: 1 } and modifies o to { b: 2 }
Parameters:
{Object} src
the source object to select and modify
{Array/Object} keys
the list of keys to remove, or an object with the keys to remove
Deprecated:
This function will be removed in the future.
Returns:
{Object} a new object containing the matching keys and values found in the source object

<static> {String} RapidContext.Util.toTitleCase(str)
Converts a string to a title-cased string. All word boundaries are replaced with a single space and the subsequent character is capitalized.

All underscore (_), hyphen (-) and lower-upper character pairs are recognized as word boundaries. Note that this function does not change the capitalization of other characters in the string.
RapidContext.Util.toTitleCase("a short heading")
⇒ "A Short Heading"
RapidContext.Util.toTitleCase("camelCase")
⇒ "Camel Case"
RapidContext.Util.toTitleCase("bounding-box")
⇒ "Bounding Box"
RapidContext.Util.toTitleCase("UPPER_CASE_VALUE")
⇒ "UPPER CASE VALUE"
Parameters:
{String} str
the string to convert
Returns:
{String} the converted string

<static> {String} RapidContext.Util.functionName(func)
Returns the name of a function. If the function is anonymous (i.e. the name property is undefined or an empty string), the value of the displayName property is returned instead.
var o = { test: function () {} };
RapidContext.Util.registerFunctionNames(o, "o");
RapidContext.Util.functionName(o.test)
⇒ "o.test"
Parameters:
{Function} func
the function to check
Returns:
{String} the function name, or undefined if not available

<static> RapidContext.Util.registerFunctionNames(obj, name)
Registers function names for anonymous functions. This is useful when debugging code in Firebug or similar tools, as readable stack traces can be provided.

This function will add a displayName property to all functions without a name property. Both the obj properties and obj.prototype properties are processed recursively, using the base name as a namespace (i.e. [name].[property] or [name].prototype.[property]).
var o = { name: "MyObject", test: function () {} };
RapidContext.Util.registerFunctionNames(o);
o.test.displayName
⇒ "MyObject.test"
Parameters:
{Object} obj
the function or object to process
{String} name Optional
the function or object (class) name

<static> {String} RapidContext.Util.resolveURI(uri, base)
Resolves a relative URI to an absolute URI. This function will return absolute URI:s directly and traverse any ../ directory paths in the specified URI. The base URI provided must be absolute.
Parameters:
{String} uri
the relative URI to resolve
{String} base Optional
the absolute base URI, defaults to the the current document base URI
Deprecated:
This function will be removed and/or renamed in the future. Better solutions for handling URL:s is to use a URL-parsing library such as URL.js.
Returns:
{String} the resolved absolute URI

<static> {Boolean} RapidContext.Util.isDOM(obj)
Returns true if the specified object looks like a DOM node. Otherwise, false will be returned. Any non-null object with a nodeType > 0 will be considered a DOM node by this function.
Parameters:
{Object} obj
the object to check
Returns:
{Boolean} true if the object looks like a DOM node, or false otherwise

<static> {Boolean} RapidContext.Util.isHTML(obj)
Returns true if the specified object looks like an HTML or XHTML DOM node. Otherwise, false will be returned. Any non-null object with a nodeType > 0 will be considered a DOM node, but only those with a matching namespaceURI will be considered HTML DOM nodes.
Parameters:
{Object} obj
the object to check
Returns:
{Boolean} true if the object looks like an HTML DOM node, or false otherwise

<static> {Array} RapidContext.Util.attributeArray(node)
Returns an array with DOM node attribute name and value pairs. The name and value pairs are also stored in arrays with two elements.
Parameters:
{Object} node
the HTML DOM node
Returns:
{Array} an array containing attribute name and value pairs (as arrays)

<static> {Node} RapidContext.Util.childNode(parent, indexOrNode)
Returns an immediate child node from a parent DOM node. If a numeric index is provided, the index will be range checked and any matching child DOM node will be returned. Otherwise, the DOM tree is traversed to find the immediate child that corresponds to the specified node.
var child = RapidContext.Util.childNode(parent, 2);
⇒ parent.childNodes[2] or null
var child = RapidContext.Util.childNode(node, evt.target());
⇒ child DOM node if descendant or null otherwise
Parameters:
{Node} parent
the parent HTML DOM node
{Number/Node} indexOrNode
the child index or a descendant node
Returns:
{Node} the child HTML DOM node, or null if no matching node was found

<static> {Object} RapidContext.Util.createDOMExt(ns, tag, attrs)
Creates a DOM node with a namespace.
RapidContext.Util.createDOMExt("http://www.w3.org/2000/svg", "g");
⇒ an SVG <g> element
Parameters:
{String} ns
the DOM namespace
{String} tag
the DOM tag name
{Object} attrs Optional
the node attributes, or null for none
{Object} ... Optional
the nodes or text to add as children
Returns:
{Object} the DOM node created

<static> {Object} RapidContext.Util.createTextNode(text)
Creates a DOM text node from the specified text. This is a convenience function for currentDocument().createTextNode, in order to be compatible with the withDocument() function.
Parameters:
{String} text
the text content
Returns:
{Object} the DOM text node created

<static> {Function} RapidContext.Util.createDOMFuncExt(ns, tag, args, attrs)
Returns a function for creating a specific kind of DOM nodes. The returned function will optionally require a sequence of non-null arguments that will be added as attributes to the node creation. The returned function will otherwise work similar to the createDOMExt() function, taking attributes and child nodes.
Parameters:
{String} ns
the DOM namespace, or null for HTML
{String} tag
the DOM tag name
{Array} args Optional
the array with required arguments, or null for no required arguments
{Object} attrs Optional
the default node attributes, or null for none
{Object} ... Optional
the default nodes or text to add as children
Returns:
{Function} the function that creates the DOM nodes

<static> RapidContext.Util.blurAll(node)
Blurs (unfocuses) a specified DOM node and all relevant child nodes. This function will recursively blur all <a>, <button>, <input>, <textarea> and <select> child nodes found.
Parameters:
{Object} node
the HTML DOM node

<static> RapidContext.Util.registerSizeConstraints(node, width, height, aspect)
Registers algebraic constraints for the element width, height and/or aspect ratio. The constraints may either be fixed numeric values, functions or algebraic formulas (in a string).

The formulas will be converted to JavaScript functions, replacing any % character with a reference to the corresponding parent dimension value (i.e. the parent element width, height or aspect ratio as a percentage). It is also possible to directly reference the parent values as w or h.

Constraint functions must take two arguments (parent width and height) and return a number. The returned number is set as the new element width or height (in pixels). Any returned value will also be bounded by the parent element size to avoid calculation errors.
RapidContext.Util.registerSizeConstraints(node, "50%-20", "100%");
⇒ Sets width to 50%-20 px and height to 100% of parent dimension
RapidContext.Util.registerSizeConstraints(otherNode, null, null, 1.0);
⇒ Ensures a square aspect ratio
RapidContext.Util.resizeElements(node, otherNode);
⇒ Evaluates the size constraints for both nodes
Parameters:
{Object} node
the HTML DOM node
{Number/Function/String} width Optional
the width constraint
{Number/Function/String} height Optional
the height constraint
{Number/Function/String} aspect Optional
the aspect ratio constraint

<static> RapidContext.Util.resizeElements()
Resizes one or more DOM nodes using their registered size constraints and their parent element sizes. The resize operation will only modify those elements that have constraints, but will perform a depth-first recursion over all element child nodes as well.

Partial constraints are accepted, in which case only the width or the height is modified. Aspect ratio constraints are applied after the width and height constraints. The result will always be bounded by the parent element width or height.

The recursive descent of this function can be limited by adding a resizeContent function to a DOM node. Such a function will be called to handle all subnode resizing, making it possible to limit or omitting the DOM tree traversal.
RapidContext.Util.resizeElements(node);
⇒ Evaluates the size constraints for a node and all child nodes
elem.resizeContent = MochiKit.Base.noop;
⇒ Assigns a no-op child resize handler to elem
Parameters:
{Object} ... Optional
the HTML DOM nodes to resize