ZxQuery class
Constructor
new ZxQuery(element) → {ZxQuery}
The constructor takes one optional argument that can be a DOM element, a node list or a valid DOM query selector string expression. If no parameter is given, the resulting ZxQuery object will wrap the root document element.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
element | Object | ZxQuery | Array.<Node> | Node | NodeList | string | undefined | optional | Element or list of elements to include in the ZxQuery object or any valid DOM query selector string |
Returns
ZxQuery ‐ The ZxQuery object containing the given element(s).
Methods
addClass(className) → {ZxQuery}
Adds the given CSS class to the class list of all elements in the ZxQuery object.
Parameters
| Name | Type | Description |
|---|---|---|
className | string | The CSS class name. |
Returns
ZxQuery ‐ The ZxQuery object itself.
append(el) → {ZxQuery}
Appends the given element or HTML string to the first element in the ZxQuery object.
Parameters
| Name | Type | Description |
|---|---|---|
el | Object | ZxQuery | Array.<Node> | Node | NodeList | string | Element or HTML to append. |
Returns
ZxQuery ‐ The ZxQuery object itself.
attach() → {ZxQuery}
Re-attaches to its parent the first element in the ZxQuery object.
Returns
attr(attr, val) → {string|ZxQuery}
Gets the value of an attribute for the first element in the ZxQuery object, or sets one or more attributes for all elements in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
attr | string | JSON | The attribute name. | |
val | string | undefined | optional | The attribute value. |
Returns
string | ZxQuery ‐ The attr attribute value when no val specified, otherwise the ZxQuery object itself.
checked(check) → {ZxQuery|boolean}
Gets the checked attribute of the first element in the ZxQuery object, or sets the checked attribute value for all elements in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
check | boolean | undefined | optional | Value to assign to the 'checked' attribute. |
Returns
ZxQuery | boolean
children(filter) → {ZxQuery}
Gets the children matching the given selector filter. This only applies to the first element in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
filter | string | optional | A valid DOM query selector filter (default: all children). |
Returns
ZxQuery ‐ A new ZxQuery object containing the selected children.
css(prop, val) → {string|ZxQuery}
Gets the value of a CSS property for the first element in the ZxQuery object, or sets one or more CSS property for all elements in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
prop | string | JSON | The CSS property name or JSON list of property/value pairs. | |
val | string | undefined | optional | The CSS property value. |
Returns
string | ZxQuery ‐ The CSS property value when no val specified, otherwise the ZxQuery object itself.
detach() → {ZxQuery}
Detaches from its parent the first element in the ZxQuery object.
Returns
display(mode) → {string|ZxQuery}
Gets the CSS display property of the first element in the ZxQuery object, or sets the display property value for all elements in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
mode | string | undefined | optional | The display value. |
Returns
string | ZxQuery ‐ The display value when no mode specified, otherwise the ZxQuery object itself.
each(iterationCallback) → {ZxQuery}
Iterates through all DOM elements in the selection. The context object this, passed to the iterationCallback(index, item) function, will be the DOM element corresponding the current iteration. index will be the iteration count, and item the current Element. The function context this will be a {ZxQuery} instance containing the current item. To interrupt the iteration loop, return false in the callback function or return true to continue to the next iteration.
Parameters
| Name | Type | Description |
|---|---|---|
iterationCallback | ElementsIterationCallback | The callback function to call for each element in the ZxQuery object. |
Returns
ZxQuery ‐ The ZxQuery object itself.
eq(i) → {ZxQuery}
Gets a new ZxQuery object containing the element located at the given position in the current ZxQuery object.
Parameters
| Name | Type | Description |
|---|---|---|
i | number | Position of element. |
Returns
ZxQuery ‐ A new ZxQuery object containing the selected element.
find(selector) → {ZxQuery}
Selects all descendants matching the given DOM query selector filter. This only applies to the first element in the ZxQuery object.
Parameters
| Name | Type | Description |
|---|---|---|
selector | string | A valid DOM query selector. |
Returns
ZxQuery ‐ A new ZxQuery object containing the selected elements.
get(i) → {Node|Element|HTMLElement}
Gets the DOM Element located at the given position in the ZxQuery object. If no index is provided, the default element will be returned.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
i | number | optional | Position of element (default: 0). |
Returns
Node | Element | HTMLElement ‐ The DOM element.
hasClass(className) → {boolean}
Returns true if the first element in the ZxQuery object contains the given CSS class.
Parameters
| Name | Type | Description |
|---|---|---|
className | string | The CSS class name. |
Returns
boolean ‐ true if the element contains the given CSS class, false otherwise.
hide() → {ZxQuery}
Sets the CSS display property to 'none'.
Returns
ZxQuery ‐ The ZxQuery object itself.
html(htmlText) → {ZxQuery|string}
Gets the HTML string of the first element in the ZxQuery object, or sets the HTML string for all elements in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
htmlText | string | undefined | optional | HTML text. |
Returns
ZxQuery | string
index(el) → {number}
If no el is given, returns the position of the first element in the ZxQuery object relative to its parent's children list, otherwise the position of the given el in the ZxQuery object selection.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
el | ZxQuery | optional |
Returns
number
insert(index, el) → {ZxQuery}
Inserts the given child element before the one located at the specified index to the first element in the ZxQuery object.
Parameters
| Name | Type | Description |
|---|---|---|
index | number | Position where to insert el Element. |
el | Object | ZxQuery | Array.<Node> | Node | NodeList | Element to insert. |
Returns
ZxQuery ‐ The ZxQuery object itself.
isEmpty() → {boolean}
Returns true if the first element markup code is empty.
Returns
boolean ‐ true if the element is empty, false otherwise.
isPlaying() → {boolean|*}
Returns true if a transition or animation is running.
Returns
boolean | ***
length() → {Number}
Gets the number of elements in the ZxQuery object.
Returns
Number ‐ Number of DOM elements.
next() → {ZxQuery}
Moves to the next sibling in the DOM. This only applies to the first element in the ZxQuery object.
Returns
ZxQuery ‐ A new ZxQuery object containing the next sibling element.
off(eventPath, eventHandler) → {ZxQuery}
Stops listening for the given event.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
eventPath | string | Array.<Object> | JSON | Event path or object with event/handler pairs. | |
eventHandler | function | optional | Event handler. Not used if eventPath is an object with event/handler pairs. |
Returns
ZxQuery ‐ The ZxQuery object itself.
on(eventPath, eventHandler) → {ZxQuery}
Listens to the given event for all elements in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
eventPath | string | Array.<Object> | JSON | Event path or object with event/handler pairs. | |
eventHandler | function | optional | Event handler. Not used if eventPath is an object with event/handler pairs. |
Returns
ZxQuery ‐ The ZxQuery object itself.
one(eventPath, eventHandler) → {ZxQuery}
Listens once to the given event for all elements in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
eventPath | string | Array.<Object> | JSON | Event path or object with event/handler pairs. | |
eventHandler | function | optional | Event handler. Not used if eventPath is an object with event/handler pairs. |
Returns
ZxQuery ‐ The ZxQuery object itself.
parent(filter) → {ZxQuery}
Gets the closest parent matching the given selector filter. This only applies to the first element in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
filter | string | optional | A valid DOM query selector filter (default: first parent). |
Returns
ZxQuery ‐ A new ZxQuery object containing the matching parent element.
playAnimation(options) → {ZxQuery}
Plays the animation specified by the given animation class list. If no class list is provided, the callback function can be used to wait for the end of any currently running animation.
Parameters
| Name | Type | Description |
|---|---|---|
options | Array.<string> | string | PlayFxConfig | This parameter can be either: a list of classes (Array |
Returns
playTransition(options) → {ZxQuery}
Plays the transition effect specified by the given transition class list. If no class list is provided, the callback function can be used to wait for the end of any currently running animation.
Parameters
| Name | Type | Description |
|---|---|---|
options | Array.<string> | string | PlayFxConfig | This parameter can be either: a list of classes (Array |
Returns
position() → {ElementPosition}
Gets coordinates and visibility status of the first element.
Returns
prepend(el) → {ZxQuery}
Prepends the given element or HTML string to the first element in the ZxQuery object.
Parameters
| Name | Type | Description |
|---|---|---|
el | Object | ZxQuery | Array.<Node> | Node | NodeList | string | Element to append. |
Returns
ZxQuery ‐ The ZxQuery object itself.
prev() → {ZxQuery}
Moves to the previous sibling in the DOM. This only applies to the first element in the ZxQuery object.
Returns
ZxQuery ‐ A new ZxQuery object containing the previous sibling element.
removeClass(className) → {ZxQuery}
Removes the given CSS class from all elements in the ZxQuery object.
Parameters
| Name | Type | Description |
|---|---|---|
className | string | The CSS class name. |
Returns
ZxQuery ‐ The ZxQuery object itself.
reset() → {ZxQuery}
De-registers all event handlers of all elements in the ZxQuery object.
Returns
ZxQuery ‐ The ZxQuery object itself.
reverse() → {ZxQuery}
Reverses order of the elements in the current set.
Returns
ZxQuery ‐ The ZxQuery object itself.
show(mode) → {ZxQuery}
Sets the CSS display property to '' if no argument value is provided, otherwise set it to the given value.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
mode | string | optional | Set the display mode to be used to show element (eg. block, inline, etc..). |
Returns
ZxQuery ‐ The ZxQuery object itself.
trigger(eventPath, eventData) → {ZxQuery}
Triggers the given event for all elements in the ZxQuery object.
Parameters
| Name | Type | Description |
|---|---|---|
eventPath | string | Path of the event to trigger. |
eventData | object | Value of the event. |
Returns
ZxQuery ‐ The ZxQuery object itself.
value(value) → {ZxQuery|string}
Gets the value attribute of the first element in the ZxQuery object, or sets the value attribute value for all elements in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
value | string | undefined | optional | Value to assign to the 'value' attribute. |
Returns
ZxQuery | string
visibility(mode) → {string|ZxQuery}
Gets the CSS visibility property of the first element in the ZxQuery object, or sets the visibility property value for all elements in the ZxQuery object.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
mode | string | undefined | optional | The visibility value. |
Returns
string | ZxQuery ‐ The visibility value when no mode specified, otherwise the ZxQuery object itself.
Type Definitions
ActiveRefreshCallback(data, refreshMs, forceActive)
The callback for setting data and delay of next refresh request.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
data | object | optional | Data to be passed to next refresh call |
refreshMs | number | optional | Delay in milliseconds before the next refresh call |
forceActive | boolean | undefined | optional | Ignore visibility, schedule anyway |
ActiveRefreshHandler($view, $element, data, nextCallback, attributeName)
The Active-Refresh function that will be called for each refresh request.
This
- {HTMLElement}
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
$view | ZxQuery | The component's view | |
$element | ZxQuery | The target element as ZxQuery object | |
data | object | Custom data that ca be passed from call to call | |
nextCallback | ActiveRefreshCallback | Callback for scheduling the next refresh call | |
attributeName | string | optional | Source attribute name if it's a '@' handler |
BindingAdapterCallback($element, fieldName, $view, refreshCallback)
Binding adapter callback.
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
$element | ZxQuery | The view's element bound to the data model's fieldName | |
fieldName | string | The element's bound field name | |
$view | ZxQuery | The view | |
refreshCallback | BindingAdapterRefreshCallback | optional | Refresh loop callback |
BindingAdapterRefreshCallback(refreshMs)
Binding adapter refresh callback
Parameters
| Name | Type | Argument | Description |
|---|---|---|---|
refreshMs | number | optional | Milliseconds to wait before refresh (default: 500ms) |
BundleItem
Bundle item object.
Properties
| Name | Type | Description |
|---|---|---|
view | Element | |
css | string | |
controller | ContextControllerHandler |
ComponentCache
Component cache object.
Properties
| Name | Type | Description |
|---|---|---|
componentId | string | The id of the cached component. |
view | Element | The view element. |
css | string | The CSS style text. |
css_applied | boolean | Whether the CSS style has been applied to the view or not. |
controller | ContextControllerHandler | The controller handler function. |
using | string | The url/path if this is a resource loaded with zuix.using(..) method. |
ContextControllerCreateCallback()
Function that gets called after loading, when the component is actually created and ready.
ContextControllerDisposeCallback()
Function called when the component is about to be disposed.
ContextControllerHandler(cp)
This function is called after the component is loaded and it is used to initialize its controller.
This
Parameters
| Name | Type | Description |
|---|---|---|
cp | ContextController | The component controller object |
ContextControllerInitCallback()
Function that gets called after loading and before the component is created.
ContextControllerUpdateCallback(target, key, value, path, old)
Function called when the data model of the component is updated
Parameters
| Name | Type | Description |
|---|---|---|
target | Object | The target object. |
key | string | The name of the property. |
value | Object | The value of the property. |
path | string | The full property path (dotted notation). |
old | Object | The target object before the update. |
Returns
‐ undefined
ContextErrorCallback(error, ctx)
Callback function triggered if an error occurs when loading a component.
This
Parameters
| Name | Type | Description |
|---|---|---|
error | Object | |
ctx | ComponentContext | The component context object (same as this). |
ContextLoadedCallback(ctx)
Callback function triggered when a component is created, after all of its dependencies have been loaded.
This
Parameters
| Name | Type | Description |
|---|---|---|
ctx | ComponentContext | The component context (same as this). |
ContextOptions
This object can be supplied when loading a component. It can be either passed as argument for the zuix.load(...) / zuix.loadComponent(...) methods, in the javascript code, or with the z-options attribute in the HTML code of the component's host element.
Properties
| Name | Type | Description |
|---|---|---|
contextId | Object | undefined | The context id. HTML attribute equivalent: z-context. If not specified it will be randomly generated. HTML attribute equivalent: z-context. |
container | Element | undefined | The container element. |
model | JSON | undefined | The data model. HTML attribute equivalent: z-model. |
view | Element | undefined | The view element. |
controller | ContextControllerHandler | undefined | The controller handler. |
controllerMembers | Object | Additional methods/properties to add to the context controller. |
on | Object.<string, EventCallback> | Object.<string, string> | undefined | The map of event handlers for standard and component's events. An event can also be simply routed to another component's event by specifying the mapped event name string. HTML attribute equivalent: z-on. |
behavior | Object.<string, EventCallback> | Object.<string, string> | undefined | The map of event handlers for behaviors. An event can also be simply routed to another component's event by specifying the mapped event name string. HTML attribute equivalent: z-behavior. |
css | HTMLStyleElement | string | boolean | undefined | Custom stylesheet to apply to the component's view. |
encapsulation | boolean | undefined | Whether to use style encapsulation or not (default: false). |
resetCss | boolean | undefined | Whether to reset view style to prevent inheriting from parent containers (default: false). |
cext | string | undefined | When loading content of the view, appends the specified extension instead of .html. |
html | boolean | string | undefined | It can be set to false, to disable HTML template loading, or it can be set to a string containing the inline HTML template code. |
lazyLoad | boolean | undefined | Enables or disables lazy-loading (default: false). HTML attribute equivalent: z-lazy. |
priority | number | undefined | Loading priority (default: 0). HTML attribute equivalent: z-priority. |
fetchOptions | Object | undefined | Options to be used when fetching this component resources. |
using | string | undefined | Comma separated contexts' id list of components used in this context. A variable with camel-case converted name for each referenced context, will be available in the local scripting scope. |
loaded | ContextLoadedCallback | undefined | The loaded callback, triggered once the component is successfully loaded. |
ready | ContextReadyCallback | undefined | The ready callback, triggered once all component's dependencies have been loaded. |
error | ContextErrorCallback | undefined | The error callback, triggered when an error occurs. |
ContextReadyCallback(ctx)
Callback function triggered when a component has been successfully loaded.
This
Parameters
| Name | Type | Description |
|---|---|---|
ctx | ComponentContext | The component context (same as this). |
ElementPosition
The ElementPosition object returned by the position() method.
Properties
| Name | Type | Description |
|---|---|---|
x | number | X coordinate of the element in the viewport |
y | number | Y coordinate of the element in the viewport |
frame | Position | Position of the element relative to the viewport |
event | string | Current state change event description (enter, exit, scroll, off-scroll) |
visible | boolean | Boolean value indicating whether the element is visible in the viewport |
ElementsIterationCallback(count, item, $item)
Callback function used with the each(..) method.
This
- {ZxQuery}
Parameters
| Name | Type | Description |
|---|---|---|
count | number | Iteration count. |
item | Element | Current element. |
$item | ZxQuery | ZxQuery wrapped element (same as 'this'). |
EventCallback(event, data, $el)
Callback function triggered when an event registered with the on method occurs.
This
- {ZxQuery}
Parameters
| Name | Type | Description |
|---|---|---|
event | string | Event name |
data | Object | Event data |
$el | ZxQuery | ZxQuery wrapped element that sourced the event (same as this) |
IterationCallback(k, item)
The IterationCallback function.
This
- {object}
Parameters
| Name | Type | Description |
|---|---|---|
k | number | object | Iteration count / item key. |
item | object | Current element (same as this). |
LoggerMonitorCallback(ctx, level)
Callback function for monitoring all log messages.
This
- {object}
Parameters
| Name | Type | Description |
|---|---|---|
ctx | Object | |
level | string | |
...args | Array.<Object> |
PlayFxCallback($element, classQueue)
Callback function used with the each(..) method.
This
- {ZxQuery}
Parameters
| Name | Type | Description |
|---|---|---|
$element | ZxQuery | Target element (same as 'this'). |
classQueue | Array.<string> | Transition/animation class queue left to play, null if the animation ended. |
PlayFxConfig
Configuration object for playFx, playTransition, playAnimation utility methods.
Properties
| Name | Type | Argument | Description |
|---|---|---|---|
type | 'transition' | 'animation' | The type of effect to play. | |
target | Element | ZxQuery | Target element. | |
classes | Array.<string> | string | List of transition or animation classes to play. | |
options | object | optional | Transition/animation options ('delay', 'duration', etc..). |
holdState | boolean | optional | Hold last transition/animation class. |
onStep | PlayFxCallback | optional | Since class list can contain more than just two classes, this callback will be called after each pair of transition/animation ended. |
onEnd | PlayFxCallback | optional | Called when all transitions/animations ended. |
Position
Relative position.
Properties
| Name | Type | Description |
|---|---|---|
dx | number | |
dy | number |
ResourceUsingCallback(resourcePath, hashIdOrContext)
Callback in response to a zuix.using request.
Parameters
| Name | Type | Description |
|---|---|---|
resourcePath | string | |
hashIdOrContext | string | object |
ZxQueryHttpBeforeSendCallback(xhr)
The ZxQueryHttpBeforeSendCallback function.
This
- {undefined}
Parameters
| Name | Type | Description |
|---|---|---|
xhr | XMLHttpRequest |
ZxQueryHttpErrorCallback(xhr, statusText, statusCode)
The ZxQueryHttpErrorCallback function.
This
- {undefined}
Parameters
| Name | Type | Description |
|---|---|---|
xhr | XMLHttpRequest | |
statusText | string | |
statusCode | number |
ZxQueryHttpOptions
zuix.$.http options object.
Properties
| Name | Type | Description |
|---|---|---|
url | string | |
beforeSend | ZxQueryHttpBeforeSendCallback | undefined | |
success | ZxQueryHttpSuccessCallback | undefined | |
error | ZxQueryHttpErrorCallback | undefined | |
then | ZxQueryHttpThenCallback | undefined |
ZxQueryHttpSuccessCallback(responseText)
The ZxQueryHttpSuccessCallback function.
This
- {undefined}
Parameters
| Name | Type | Description |
|---|---|---|
responseText | string |
ZxQueryHttpThenCallback(xhr)
The ZxQueryHttpThenCallback function.
This
- {undefined}
Parameters
| Name | Type | Description |
|---|---|---|
xhr | XMLHttpRequest |
