Class CQ.Util

Package:	CQ
Class:	Util
Extends:	Object
Clientlib:	cq.widgets

A helper class providing a basic set of utilities.

This class is a singleton and cannot be created directly.

Public Properties

Property		Defined By
	COMMENT_I18N_SUFFIX : String <static> The parameter name suffix for translation comments for properties.	Util
	FORMAT_ONLY : Number <static> The mode for formatData to only format the data.	Util
	I18N_ONLY : Number <static> The mode for formatData to only translate the data.	Util
	NO_I18N_SUFFIX : String <static> The parameter name suffix for properties that should not be translated.	Util
	ROOT_ID : String <static> The ID of the root element harboring all CQ-related elements.	Util

Public Methods

Method		Defined By
	addListenerToConfig( `Object obj`, `String event`, `Function handler` ) : void <static> Add an event listener to an obj.listeners config. This is the same as obj.listeners[event] = handler, ... <static> Add an event listener to an obj.listeners config. This is the same as `obj.listeners[event] = handler`, but will also handle the case if there is already a listener defined for that event. The provided handler will be called when the event is triggered after the function that is already defined in the config object. This method can be used on the raw config object as read from JSON, it will automatically convert string-based functions using CQ.Util.formatData. Parameters: `obj` : Object the config object; events are set on the "listeners" child `event` : String name of the event for which the function should listen to `handler` : Function function to listen for the event Returns: `void` Added in CQ 5.6.	Util
	applyDefaults( `Object base`, `Object defaults` ) : Object <static> Applies default properties if inexistent in the base object. Child objects are merged recursively. Exa... <static> Applies default properties if inexistent in the base object. Child objects are merged recursively. Example: `var base = { a: "a", b: "b" }; var upgrade = { b: "B", c: "C" }; CQ.Util.applyDefaults(base, upgrade);` Result: `{ a: "a", b: "b", c: "C" }` Parameters: `base` : Object The base object `defaults` : Object The defaults object Returns: `Object` The base object with defaults	Util
	build( `Object/String data`, [`Boolean noFormatting`], [`Function callback`], [`Object extensions`] ) : CQ.Ext.Component <static> Builds a component using the specified data object or URL. <static> Builds a component using the specified data object or URL. Parameters: `data` : Object/String The data object or URL `noFormatting` : Boolean (optional) If true, data object will not be formatted. `callback` : Function (optional) The callback function to call after the data object has been retrieved from the URL `extensions` : Object (optional) The component's extensions. Each item contains an array of config objects. Sample: `{ "tabs": [ { "xtype": "contentfindertab" } ], "buttons": [ { "xtype": "button" } ] }` Returns: `CQ.Ext.Component` The component or, if the request is asynchronous, the transaction ID	Util
	cancelObservation( `CQ.Ext.Component component`, [`String interval`] ) : void <static> Removes a component from the list of observed components. The interval can be one of: VERY_SHORT_INTE... <static> Removes a component from the list of observed components. The interval can be one of: VERY_SHORT_INTERVAL SHORT_INTERVAL (default) LONG_INTERVAL VERY_LONG_INTERVAL Parameters: `component` : CQ.Ext.Component The component `interval` : String (optional) The interval Returns: `void`	Util
	clearDocumentSelection( [`Window win`] ) : void Deprecated: Use CQ.DOM.clearDocumentSelection instead <static> Clears the text selection in the document. If no window is specified, the current window will be used. <static> Clears the text selection in the document. If no window is specified, the current window will be used. Parameters: `win` : Window (optional) The window Returns: `void`	Util
	compareValues( `Object v1`, `Object v2` ) : Number <static> Compares two values. <static> Compares two values. Parameters: `v1` : Object The first value `v2` : Object The second value Returns: `Number` 0 if values match, 1 if first value is greater than second, -1 if second value is greater than first	Util
	copyObject( `Object object` ) : Object <static> Returns a copy of the specified object. <static> Returns a copy of the specified object. Parameters: `object` : Object The object to copy Returns: `Object` The copy	Util
	createId( [`String id`] ) : String <static> Creates a unique ID by adding a counter to the specified ID. <static> Creates a unique ID by adding a counter to the specified ID. Parameters: `id` : String (optional) The base ID Returns: `String` The unique ID	Util
	escapePath( `String path` ) : String Deprecated: Use CQ.shared.HTTP.encodePath instead <static> Escapes a path for use as a URL using the standard encodeUriComponent function, but leaving the path d... <static> Escapes a path for use as a URL using the standard encodeUriComponent function, but leaving the path delimiters (/) as-is. Parameters: `path` : String The path Returns: `String` The escaped path	Util
	eval( `Object response` ) : Object Deprecated: Use CQ.shared.HTTP.eval instead <static> Evaluates and returns the response text of the specified response object. <static> Evaluates and returns the response text of the specified response object. Parameters: `response` : Object The response object Returns: `Object` The evaluated object	Util
	evalHTML( `String html` ) : Object <static> Evaluates and returns the specified HTML code. <static> Evaluates and returns the specified HTML code. Parameters: `html` : String The HTML code Returns: `Object` The evaluated object	Util
	evalNode( `Node node`, [`Object obj`] ) : Object <static> Evaluates and returns the specified HTML node. <static> Evaluates and returns the specified HTML node. Parameters: `node` : Node The document or node to parse `obj` : Object (optional) The evaluated object if recursing Returns: `Object` The evaluated object	Util
	externalize( `String url` ) : String Deprecated: Use CQ.shared.HTTP.externalize instead <static> Makes sure the specified relative URL starts with the context path used on the server. If an absolute ... <static> Makes sure the specified relative URL starts with the context path used on the server. If an absolute URL is passed, it will be returned as-is. Parameters: `url` : String The URL Returns: `String` The externalized URL	Util
	formatData( `Object data`, [`Number mode`] ) : Object <static> Formats and/or translates the given data object for building components. See also build. Formatting tr... <static> Formats and/or translates the given data object for building components. See also build. Formatting transforms jcr:primaryType into xtype, collections into arrays, and strings of numbers or booleans (e.g. "12", "true") will be converted into their respective types. Translation looks up values of well-known text properties (e.g. title, text, fieldLabel) in the current user's language. Parameters: `data` : Object The data object to format `mode` : Number (optional) FORMAT_ONLY skips the translation I18N_ONLY skips the formatting Returns: `Object` The formatted data object	Util
	formatFileSize( `Number size` ) : String Returns a human readable filesize including the unit, e.g "12 MB". Returns a human readable filesize including the unit, e.g "12 MB". Parameters: `size` : Number The filesize Returns: `String` The formatted filesize	Util
	getAbsoluteParent( `String path`, `Number level` ) : String Returns the absolute parent of the given path, at the position of the given level. Returns the absolute parent of the given path, at the position of the given level. Parameters: `path` : String The path whose parent to return. Must be an absolute path (start with "/"). `level` : Number The level of the parent to return. Returns: `String` The absolute parent or null if either the path or level are not defined, or the path doesn't start with a slash.	Util
	getContextPath() : String Deprecated: Use CQ.shared.HTTP.getContextPath instead <static> Returns the context path used on the server. <static> Returns the context path used on the server. Parameters: None. Returns: `String` The context path	Util
	getFlashVersion() : void Deprecated: Use CQ.endorsed.swfobject.getFlashPlayerVersion() instead. <static> <static> Parameters: None. Returns: `void`	Util
	getPath( `String url` ) : String Deprecated: Use CQ.shared.HTTP.getPath instead <static> Removes all parts but the path from the specified URL. Examples:/x/y.sel.html?param=abc => /x/y htt... <static> Removes all parts but the path from the specified URL. Examples: `/x/y.sel.html?param=abc => /x/y` `http://www.day.com/foo/bar.html => /foo/bar` Parameters: `url` : String The URL Returns: `String` The path	Util
	getRoot() : CQ.Ext.Element <static> Returns the root element harboring all CQ-related elements. <static> Returns the root element harboring all CQ-related elements. Parameters: None. Returns: `CQ.Ext.Element` The root element	Util
	internalize( `String url`, [`String doc`] ) : String Deprecated: Use CQ.shared.HTTP.internalize instead <static> Removes scheme, authority and context path from the specified absolute URL if it has the same scheme a... <static> Removes scheme, authority and context path from the specified absolute URL if it has the same scheme and authority as the specified document (or the current one). Parameters: `url` : String The URL `doc` : String (optional) The document Returns: `String` The internalized URL	Util
	isAcceptedMimeType( `String[] acceptPatternArray`, `String mimeType` ) : Boolean <static> Checks if the specified mime type is accepted. <static> Checks if the specified mime type is accepted. Parameters: `acceptPatternArray` : String[] The array of patterns to check `mimeType` : String The mime type Returns: `Boolean` True if mime type is accepted	Util
	isEmptyObject( `Object obj` ) : Boolean <static> Returns true if the specified object is empty. Note that an undefined object will not be treated as em... <static> Returns true if the specified object is empty. Note that an undefined object will not be treated as empty. Parameters: `obj` : Object The object Returns: `Boolean` True if object is empty	Util
	isIntersecting( `Object firstObj`, `Object secondObj`, [`Object exclude`] ) : Boolean <static> Returns true if at least one property of the first object is also a property of the second object. <static> Returns true if at least one property of the first object is also a property of the second object. Parameters: `firstObj` : Object The first object `secondObj` : Object The second object `exclude` : Object (optional) The properties to exclude Returns: `Boolean` True if object is intersecting	Util
	isLiteral( `String str` ) : Boolean Indicates whether or not the string represents a literal. Indicates whether or not the string represents a literal. Parameters: `str` : String The source string. Returns: `Boolean` True if the string is wrapped in either single or double-quotes.	Util
	logout() : void Deprecated: Use CQ.User.logout() instead <static> Logs the current user out. <static> Logs the current user out. Parameters: None. Returns: `void`	Util
	merge( `Object base`, `Object upgrade` ) : Object <static> Merges one object into the other. Child objects are merged recursively. Example:var base = { a: "a", b... <static> Merges one object into the other. Child objects are merged recursively. Example: `var base = { a: "a", b: "b" }; var upgrade = { b: "B", c: "C" }; CQ.Util.merge(base, upgrade);` Result: `{ a: "a", b: "B", c: "C" }` Parameters: `base` : Object The base object `upgrade` : Object The upgrade object Returns: `Object` The merged object	Util
	observeComponent( `CQ.Ext.Component component`, [`String interval`] ) : void <static> Adds a component to the list of observed components. These components are observed regulary by calling... <static> Adds a component to the list of observed components. These components are observed regulary by calling their observe method. See also runComponentObservation and cancelObservation. Note that the observe method can be called quite often, which potentially has an impact on performance. Make sure any action performed in the observe method is really required. The interval can be one of: VERY_SHORT_INTERVAL SHORT_INTERVAL (default) LONG_INTERVAL VERY_LONG_INTERVAL Parameters: `component` : CQ.Ext.Component The component `interval` : String (optional) The interval Returns: `void`	Util
	patchText( `String text`, `String/String[] snippets` ) : String <static> Replaces occurrences of {n} in the specified text with the texts from the snippets. Example 1 (single ... <static> Replaces occurrences of `{n}` in the specified text with the texts from the snippets. Example 1 (single snippet): `var text = CQ.Util.patchText("{0} has signed in.", "Jack");` Result 1: `Jack has signed in.` Example 2 (multiple snippets): `var text = "{0} {1} has signed in from {2}."; text = CQ.Util.patchText(text, ["Jack", "McFarland", "x.x.x.x"]);` Result 2: `Jack McFarland has signed in from x.x.x.x.` Parameters: `text` : String The text `snippets` : String/String[] The text(s) replacing `{n}` Returns: `String` The patched text	Util
	pin( `CQ.Ext.Component/CQ.Ext.Element item` ) : void <static> Keeps the specified component or element at its current position on the screen, repositioning it when ... <static> Keeps the specified component or element at its current position on the screen, repositioning it when the document gets scrolled to achieve the impression that it is actually pinned to the screen. See also unpin. Parameters: `item` : CQ.Ext.Component/CQ.Ext.Element The item Returns: `void`	Util
	quote( `String str` ) : String Wraps a string in double-quotes. Wraps a string in double-quotes. Parameters: `str` : String The source string. Returns: `String` The quoted string.	Util
	reload( [`Window win`], [`String url`] ) : void <static> Reloads the window or replaces its location with the specified URL. If no window is specified, the cur... <static> Reloads the window or replaces its location with the specified URL. If no window is specified, the current window will be used. Parameters: `win` : Window (optional) The window to reload `url` : String (optional) The URL Returns: `void`	Util
	renderDate( `String date` ) : String <static> Returns a nicely formatted date. This function can be used directly as a renderer for widgets. <static> Returns a nicely formatted date. This function can be used directly as a renderer for widgets. Parameters: `date` : String The date string to format Returns: `String` The formatted date	Util
	runComponentObservation( [`String interval`] ) : void <static> Steps through all observed components and calls their observe method. The interval can be one of: VER... <static> Steps through all observed components and calls their observe method. The interval can be one of: VERY_SHORT_INTERVAL SHORT_INTERVAL (default) LONG_INTERVAL VERY_LONG_INTERVAL Parameters: `interval` : String (optional) The interval Returns: `void`	Util
	sortByRanking( `Object[] array` ) : Object[] <static> Sorts the specified array of objects by their ranking properties. <static> Sorts the specified array of objects by their ranking properties. Parameters: `array` : Object[] An array of objects Returns: `Object[]` The sorted array	Util
	toggleComponent( `CQ.Ext.Component component`, `boolean enableCondition` ) : void <static> Enables or disable a componnent <static> Enables or disable a componnent Parameters: `component` : CQ.Ext.Component The component to enable/disable `enableCondition` : boolean Component will be enabled if this condition is true, disabled otherwise Returns: `void`	Util
	trim( `String str` ) : String Safely removes whitespace from a string (safe for null and undefined string parameters). Safely removes whitespace from a string (safe for null and undefined string parameters). Parameters: `str` : String The source string. Returns: `String` The trimmed string.	Util
	unpin( `CQ.Ext.Component/CQ.Ext.Element item` ) : void <static> Removes the pin from the specified component or element, letting it scroll with the document again. <static> Removes the pin from the specified component or element, letting it scroll with the document again. Parameters: `item` : CQ.Ext.Component/CQ.Ext.Element The item Returns: `void`	Util
	unquote( `String str` ) : String Removes enclosing single- or double-quotes from a string. Removes enclosing single- or double-quotes from a string. Parameters: `str` : String The source string. Returns: `String` The un-quoted string.	Util
	unwrapParens( `String str` ) : String Removes an enclosing pair of parentheses (and any adjoining whitespace) from a string. Removes an enclosing pair of parentheses (and any adjoining whitespace) from a string. Parameters: `str` : String The source string. Returns: `String` The unwrapped (and trimmed) string.	Util

Public Events

This class has no public events.