Show:

Q.Tool Class

Defined in: platform/plugins/Q/web/js/Q.js:3725
Module: Q

Returns Q.Event which occurs when a tool has been activated Generic callbacks can be assigned by setting toolName to ""

Constructor

Q.Tool

(
  • [element]
  • [options]
)
Q.Tool

Defined in platform/plugins/Q/web/js/Q.js:3725

Parameters:

  • [element] Object optional

    the element to activate into a tool

  • [options] Object optional

    an optional set of options that may contain ".Tool_name or #Some_exact_tool or #Some_child_tool"

Returns:

Q.Tool:

if this tool is replacing an earlier one, returns existing tool that was removed. Otherwise returns null, or false if the tool was already constructed.

Methods

$

(
  • selector
)
Object

Defined in platform/plugins/Q/web/js/Q.js:4308

If jQuery is available, returns jQuery(selector, this.element). Just a tiny Backbone.js-style convenience helper; this.$ is similar to $, but scoped to the DOM tree of this tool.

Parameters:

  • selector String

    jQuery selector

Returns:

Object:

jQuery object matched by the given selector

_loadToolScript

(
  • toolElement
  • callback
  • [shared]
  • [parentId]
)
Boolean

Defined in platform/plugins/Q/web/js/Q.js:4648

Loads the script corresponding to a tool

Parameters:

  • toolElement DOMElement
  • callback Function

    The callback to call when the corresponding script has been loaded and executed

  • [shared] Mixed optional

    pass this only when constructing a tool

  • [parentId] String optional

    used internally to pass id of parent tools waiting for init

Returns:

Boolean:

whether the script needed to be loaded

ancestor

(
  • name
)
Q.Tool | Null

Defined in platform/plugins/Q/web/js/Q.js:4205

Returns the closest ancestor, if any, with the given tool name If more than one tool is activated with the same parent id, returns the first one.

Parameters:

Returns:

Q.Tool | Null:

byId

(
  • id
  • name
)
Q.Tool | Null | Undefined static

Defined in platform/plugins/Q/web/js/Q.js:4554

Reference a tool by its id

Parameters:

  • id String
  • name String

    optionally specify the name of the tool, useful if more than one tool was activated on the same element. It will be run through Q.normalize().

Returns:

Q.Tool | Null | Undefined:

byName

(
  • name
)
Object static

Defined in platform/plugins/Q/web/js/Q.js:4575

Find all the activated tools with a certain name

Parameters:

  • name String | Array

    This is run through Q.normalize()

Returns:

Object:

calculateId

(
  • id
)
String static

Defined in platform/plugins/Q/web/js/Q.js:4621

Computes and returns a tool's id from some string that's likely to contain it, such as an HTML element's id, a tool's id, or a tool's prefix.

Parameters:

  • id String

    the id or prefix of an existing tool or its element

Returns:

String:

calculatePrefix

(
  • id
)
String static

Defined in platform/plugins/Q/web/js/Q.js:4604

Computes and returns a tool's prefix

Parameters:

  • id String

    the id or prefix of an existing tool or its element

Returns:

String:

child

(
  • append
  • [name=""]
)
Q.Tool | Null

Defined in platform/plugins/Q/web/js/Q.js:4124

Gets one child tool contained in the tool, which matches the prefix based on the prefix of the tool.

Parameters:

  • append String

    The string to append to the tool prefix to find the child tool id

  • [name=""] String optional

    Filter by tool name, such as "Q/inplace"

Returns:

Q.Tool | Null:

children

(
  • [name=""]
  • [levels=null]
)
Object

Defined in platform/plugins/Q/web/js/Q.js:4088

Gets child tools contained in the tool, as determined by their ids.

Parameters:

  • [name=""] String optional

    Filter children by their tool name, such as "Q/inplace"

  • [levels=null] Number optional

    Pass 1 here to get only the immediate children, 2 for immediate children and grandchildren, etc.

Returns:

Object:

A two-level hash of pairs like {id: {name: Tool}}

children

() Object

Defined in platform/plugins/Q/web/js/Q.js:4234

Gets sibling tools activated on the same element

Returns:

Object:

pairs of {normalizedName: tool}

clear

(
  • elem
  • removeCached
)
static

Defined in platform/plugins/Q/web/js/Q.js:3785

Traverses children in a particular container and removes + destroys all tools. Should be called before removing elements.

Parameters:

  • elem HTMLElement

    The container to traverse

  • removeCached Boolean

    Defaults to false. Whether the tools whose containing elements have the "data-Q-retain" attribute should be removed...

define

(
  • name
  • ctor
  • [require]
  • defaultOptions
  • stateKeys
  • methods
)
Function static

Defined in platform/plugins/Q/web/js/Q.js:3805

Call this function to define a tool

Parameters:

  • name String | Object

    The name of the tool, e.g. "Q/foo". Also you can pass an object containing {name: filename} pairs instead.

  • ctor Function

    Your tool's constructor. You can also pass a filename here, in which case the other parameters are ignored.

  • [require] String | Array optional

    Optionally name another tool (or array of tool names) that was supposed to already have been defined. This will cause your tool's constructor to make sure the required tool has been already loaded and activated on the same element.

  • defaultOptions Object

    An optional hash of default options for the tool

  • stateKeys Array

    An optional array of key names to copy from options to state

  • methods Object

    An optional hash of method functions to assign to the prototype

Returns:

Function:

The tool's constructor function

define.options

(
  • toolName
  • setOptions
)
Object static

Defined in platform/plugins/Q/web/js/Q.js:3871

Call this function to define default options for a tool constructor, even if has not been loaded yet. Extends existing options with Q.extend().

Parameters:

  • toolName String

    the name of the tool

  • setOptions Object

    the options to set

Returns:

Object:

the resulting pending options for the tool

encodeOptions

(
  • options
)
String static

Defined in platform/plugins/Q/web/js/Q.js:4390

Returns a string that is already properly encoded and can be set as the value of an options attribute

Parameters:

  • options Object

    the options to pass to a tool

Returns:

String:

forEachChild

(
  • [name=""]
  • [levels]
  • [withSiblings=false]
  • callback
)

Defined in platform/plugins/Q/web/js/Q.js:4340

Do something for every and future child tool that is activated inside this tool

Parameters:

  • [name=""] String optional

    Filter by name of the child tools, such as "Q/inplace"

  • [levels] Number optional

    Optionally pass 1 here to get only the immediate children, 2 for immediate children and grandchildren, etc.

  • [withSiblings=false] Boolean optional

    Optionally pass true here to also get the sibling tools activated on the same element

  • callback Function

    The callback to execute at the right time

from

(
  • toolElement
  • [toolName]
)
Q.Tool | Null static

Defined in platform/plugins/Q/web/js/Q.js:4534

Returns a tool corresponding to the given DOM element, if such tool has already been constructed.

Parameters:

  • toolElement Element

    the root element of the desired tool

  • [toolName] String optional

    optional name of the tool attached to the element

Returns:

Q.Tool | Null:

the tool corresponding to the given element, otherwise null

getElementsByClassName

(
  • className
)
NodeList

Defined in platform/plugins/Q/web/js/Q.js:4328

Returns all subelements with the given class name.

Parameters:

  • className String

    the class name to look for

Returns:

NodeList:

a list of nodes with the given class name.

jQuery

(
  • name
  • ctor
  • defaultOptions
  • stateKeys
  • methods
)
static

Defined in platform/plugins/Q/web/js/Q.js:3895

Call this function to define a jQuery plugin, and a tool with the same name that uses it.

Parameters:

  • name String

    The name of the jQuery plugin and tool, e.g. "Q/foo"

  • ctor Function

    Your jQuery plugin's constructor

  • defaultOptions Object

    An optional hash of default options for the plugin

  • stateKeys Array

    An optional array of key names to copy from options to state

  • methods Object

    An optional hash of method functions to assign to the prototype

jQuery.options

(
  • pluginName
  • setOptions
)
Object static

Defined in platform/plugins/Q/web/js/Q.js:3992

Call this function to define default options for a jQuery tool constructor, even if it has not been loaded yet.

Parameters:

  • pluginName String

    the name of the tool

  • setOptions Object

    the options to set

Returns:

Object:

the resulting pending options for the tool

parent

() Q.Tool | Null

Defined in platform/plugins/Q/web/js/Q.js:4193

Returns the immediate parent tool, if any, by using parentIds(). If more than one tool is activated with the same parent id, returns the first one.

Returns:

Q.Tool | Null:

parentIds

() Array | Null

Defined in platform/plugins/Q/web/js/Q.js:4151

Gets the ids of the parent, grandparent, etc. tools (in that order) of the given tool

Returns:

Array | Null:

parents

() Object

Defined in platform/plugins/Q/web/js/Q.js:4173

Gets parent tools, as determined by parentIds() Note that several sibling tools may be activated on the same tool id.

Returns:

Object:

A two-level hash of pairs like {id: {name: Q.Tool}}

remove

(
  • elem
  • removeCached
)
static

Defined in platform/plugins/Q/web/js/Q.js:3750

Traverses elements in a particular container, including the container itself, and removes + destroys all tools. Should be called before removing elements.

Parameters:

  • elem HTMLElement

    The container to traverse

  • removeCached Boolean

    Defaults to false. Whether the tools whose containing elements have the "data-Q-retain" attribute should be removed.

remove

(
  • removeCached
)
Boolean

Defined in platform/plugins/Q/web/js/Q.js:4246

Called when a tool instance is removed, possibly being replaced by another. Typically happens after an AJAX call which returns markup for the new instance tool. You should call Q.Tool.remove unless, for some reason, you plan to remove this exact tool instance, and not its children or siblings.

Parameters:

  • removeCached Boolean

    Defaults to false. Whether or not to remove the actual tool if its containing element has a "data-Q-retain" attribute.

Returns:

Boolean:

Returns whether the tool was removed.

rendering

(
  • fields
  • callback
  • [key=""]
  • [dontWaitForAnimationFrame=false]
)

Defined in platform/plugins/Q/web/js/Q.js:4046

When implementing tools, use this to implement rendering markup that can vary as a function of the tool's state (with no additional side effects).

Parameters:

  • fields Array | String

    The names of fields to watch for, either as an array or comma-separated string. When stateChanged is called, if one of the fields named here really changed, the callback will be called.

  • callback Function

    The callback, which receives (changed, previous, timestamp). By default, Qbix defers the execution of your rendering handler until the next animation frame. If several calls to tool.stateChanged occurred in the meantime, Qbix aggregates all the changes and reports them to the rendering handler. If a field in the state was changed several times in the meantime, those intermediate values aren't given to the rendering handler, since the assumption is that the view depends on the state without any side effects. However, if the field was changed, even if it later went back to its original value, it will show up in the list of changed fields.

  • [key=""] String optional

    Optional key used when attaching event handlers to tool.Q.onStateChanged events.

  • [dontWaitForAnimationFrame=false] Boolean optional

    Pass true here if you really don't want to wait for the next animation frame to do rendering (for example, if you insist on reading the DOM and will use a library like FastDOM to manage DOM thrashing)

setUpElement

(
  • element
  • toolName
  • toolOptions
  • id
)
HTMLElement

Defined in platform/plugins/Q/web/js/Q.js:4494

Sets up element so that it can be used to activate a tool For example: $('container').append(Q.Tool.setUpElement('div', 'Streams/chat')).activate(options); The prefix and id of the element are derived from the tool on which this method is called.

Parameters:

  • element String | Element

    The tag of the element, such as "div", or a reference to an existing Element

  • toolName String

    The type of the tool, such as "Q/tabs"

  • toolOptions Object

    The options for the tool

  • id String

    Optional id of the tool, such as "_2_Q_tabs"

Returns:

HTMLElement:

Returns an element you can append to things

setUpElement

(
  • element
  • toolName
  • [toolOptions]
  • [id=null]
  • [prefix]
)
HTMLElement static

Defined in platform/plugins/Q/web/js/Q.js:4401

Sets up element so that it can be used to activate a tool For example: $('container').append(Q.Tool.setUpElement('div', 'Streams/chat')).activate(options);

Parameters:

  • element String | Element

    The tag of the element, such as "div", or a reference to an existing Element

  • toolName String | Array

    The type of the tool, such as "Q/tabs", or an array of types

  • [toolOptions] Object | Array optional

    The options for the tool. If toolName is an array, this is the array of corresponding objects to use for options.

  • [id=null] String | Function optional

    Optional id of the tool, such as "Q_tabs_2", used if element doesn't have an "id" attribute. If null, calculates an automatically unique id beginning with the tool's name

  • [prefix] String optional

    Optional prefix to prepend to the tool's id

Returns:

HTMLElement:

Returns an element you can append to things

setUpElementHTML

(
  • element
  • toolName
  • toolOptions
  • id
)
String

Defined in platform/plugins/Q/web/js/Q.js:4514

Returns HTML for an element that it can be used to activate a tool. The prefix and id of the element are derived from the tool on which this method is called. For example: $('container').append(Q.Tool.make('Streams/chat')).activate(options);

Parameters:

  • element String | Element

    The tag of the element, such as "div", or a reference to an existing Element

  • toolName String

    The type of the tool, such as "Q/tabs"

  • toolOptions Object

    The options for the tool

  • id String

    Optional id of the tool, such as "_2_Q_tabs"

Returns:

String:

Returns HTML that you can include in templates, etc.

setUpElementHTML

(
  • element
  • toolName
  • toolOptions
  • [id]
  • [prefix]
)
String static

Defined in platform/plugins/Q/web/js/Q.js:4468

Returns HTML for an element that it can be used to activate a tool

Parameters:

  • element String | Element

    The tag of the element, such as "div", or a reference to an existing Element

  • toolName String

    The type of the tool, such as "Q/tabs"

  • toolOptions Object

    The options for the tool

  • [id] String | Function optional

    Optional id of the tool, such as "Q_tabs_2"

  • [prefix] String optional

    Optional prefix to prepend to the tool's id

Returns:

String:

Returns HTML that you can include in templates, etc.

sibling

() Q.Tool | Null

Defined in platform/plugins/Q/web/js/Q.js:4225

Returns a tool on the same element

Returns:

Q.Tool | Null:

stateChanged

(
  • names
)

Defined in platform/plugins/Q/web/js/Q.js:4021

Call this after changing one more values in the state. Unlike Angular and Ember, Q provides a more explicit mechanism for signaling that a tool's state has changed. Other parts of code can use the Tool.prototype.onState event factory to attach handlers to be run when the state changes.

Parameters:

  • names String | Array

    Name(s) of properties that may have changed, either an array or comma-separated string.

toString

() String

Defined in platform/plugins/Q/web/js/Q.js:4639

For debugging purposes only, allows to log tool names conveniently

Returns:

String:

Events

beforeRemove

Defined in platform/plugins/Q/web/js/Q.js:3742

Returns Q.Event which occurs when a tool is about to be removed Generic callbacks can be assigned by setting toolName to ""

Event Payload:

  • nameOrId String

    the name of the tool, such as "Q/inplace", or "id:" followed by tool's id

onConstruct

Defined in platform/plugins/Q/web/js/Q.js:3661

Q.Event which occurs when the tool was constructed

onInit

Defined in platform/plugins/Q/web/js/Q.js:3666

Q.Event which occurs when the tool was initialized

onInit

Defined in platform/plugins/Q/web/js/Q.js:3734

Returns Q.Event which occurs when a tool has been initialized Generic callbacks can be assigned by setting toolName to ""

Event Payload:

  • nameOrId String

    the name of the tool, such as "Q/inplace", or "id:" followed by tool's id

onRemove

Defined in platform/plugins/Q/web/js/Q.js:3671

Q.Event which occurs when the tool was removed

onRetain

Defined in platform/plugins/Q/web/js/Q.js:3676

Q.Event which occurs when the tool was retained while replacing some HTML

onStateChanged

Defined in platform/plugins/Q/web/js/Q.js:3681

Returns Q.Event which occurs when some fields in the tool's state changed

Event Payload:

  • name String

    The name of the field. Can be "" to listen on all fields.