VeamsQuery
Represents a very simple DOM API for Veams-JS (incl. ajax support)
Getting started
Installation
yarn
yarn add @veams/query
npm
npm install @veams/query --save
Usage
Documentation of all functions (Selector, support and DOM)
Selector function
VeamsQuery( selector: string | VeamsQueryObject | HTMLElement, context: VeamsQueryObject | HTMLElement = null )
/**
* VeamsQuery selector function
*
* @param {string | VeamsQueryObject | HTMLElement} selector - selector (string, VeamsQueryObject, HTMLElement)
* @param {VeamsQueryObject | HTMLElement} [context = null] - context (VeamsQueryObject, HTMLElement)
* @return {VeamsQueryObject}
*/
Properties
VeamsQuery.version
/**
* Current VeamsQuery version
*/
Support functions
VeamsQuery.parseHTML( htmlString:string )
/**
* Return DOM element created from given HTML string
*
* @param {string} htmlString - HTML string to parse
* @return {Node} - DOM node
*/
VeamsQuery.ajax( opts: AjaxOpts )
/**
* Send XMLHttpRequest
*
* @param {AjaxOpts} opts - Ajax options
* @param {string} [opts.type='GET'] - an alias for method
* @param {string} opts.url - a string containing the URL to which the request is sent
* @param {string} [opts.dataType='json'] - data type of response ('json' || 'html' || 'text')
* @param {string} [opts.contentType='application/x-www-form-urlencoded'] - content type for post request
* @param {Object|String|Array} [opts.data] - data to be sent to the server
* @return {Promise<void>}
*/
DOM functions
.find( selector: string | VeamsQueryObject | HTMLElement )
/**
* Get the descendants of each element in the current set of matched elements, filtered by a selector,
* VeamsQueryObject, or element
*
* @param {string|VeamsQueryObject|HTMLElement} selector - Selector (string, VeamsQueryObject, HTMLElement)
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.closest( selector:string )
/**
* For each element in the set, get the first element that matches the selector by testing
* the element itself and traversing up through its ancestors in the DOM tree
*
* @param {string} selector - Selector
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.add( selector: string | HTMLElement | VeamsQueryObject )
/**
* Create a new VeamsQueryObject with elements added to the set of matched elements.
*
* @param {string | HTMLElement | VeamsQueryObject} selector - Selector, HTMLElement or VeamsQueryObject
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.eq( index:number )
/**
* Reduce the set of matched elements to the one at the specified index
*
* @param {number} index - Index of element in node list
* @return {VeamsQueryObject} - VeamsQueryObject containing node at given index of original node list
*/
.hasClass( className:string )
/**
* Check if element has given class
*
* @param {string} className - Name of class to check
* @return {boolean} - Element has class (true/false)
*/
.is( selector:string )
/**
* Check the current matched set of elements against a selector, element, or VeamsQueryObject and return true if
* at least one of these elements matches the given arguments
*
* @param {string} selector - A string containing a selector expression to match elements against
* @return {boolean} - At least one element matches selector (true/false)
*/
.addClass( classNames:string )
/**
* Add the specified class(es) to each element in the set of matched elements.
*
* @param {string} classNames - Name(s) of class(es) to add
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.removeClass( [classNames:string] )
/**
* Remove a single class, multiple classes, or all classes from each element in the set of matched elements
*
* @param {string} classNames - Name(s) of class(es) to remove
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.attr( attrName:string )
/**
* Get the value of an attribute for the first element in the set of matched elements
*
* @param {String} attrName - attribute name
* @return {String|Number|Boolean} - attribute value
*/
.attr( attrName:string, attrVal:string|number|boolean )
/**
* Set value of an attribute for the set of matched elements
*
* @param {String} attrName - attribute name
* @param {String|Number|Boolean} attrVal - attribute value
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.removeAttr( attrName:string )
/**
* Remove an attribute from each element in the set of matched elements
*
* @param {String} attrName - attribute name
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.css( cssProp:string )
/**
* Get the computed style properties for the first element in the set of matched elements
*
* @param {String} cssProp - css property
* @return {String} - css value
*/
.css( cssProp:string|object, cssVal:string)
/**
* Set the content of each element in the set of matched elements to the specified text
*
* @param {String|Object} cssProp - css property
* @param {String} cssVal - css value
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.outerHeight( includeMargin:boolean)
/**
* Get the current computed height for the first element in the set of matched elements,
* including padding, border and optionally margin
*
* @param {Boolean} [includeMargin=false] - include element's margin in calculation (true/false)
* @return {Number} - height
*/
.outerWidth( includeMargin:boolean)
/**
* Get the current computed width for the first element in the set of matched elements,
* including padding,border and optionally margin
*
* @param {Boolean} [includeMargin=false] - include element's margin in calculation (true/false)
* @return {Number} - width
*/
.offset()
/**
* Get the current coordinates of the first element in the set of matched elements,
* relative to the document
*
* @return {Object} - offset (offset.top, offset.left)
*/
.html()
/**
* Get the HTML contents of the first element in the set of matched elements
*
* @return {String} - html contents
*/
.html( htmlStr:string )
/**
* Set the HTML contents of each element in the set of matched elements
*
* @param {String} htmlStr - html string
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.text()
/**
* Get the combined text contents of each element in the set of matched elements
*
* @return {String} - text
*/
.text( text:string )
/**
* Set the content of each element in the set of matched elements to the specified text
*
* @param {String} text - text
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.prepend( element: string | VeamsQueryObject | HTMLElement )
/**
* Insert content, specified by the parameter, to the beginning of each element in the set
* of matched elements
*
* @param {string|VeamsQueryObject|HTMLElement} element - HTML string | VeamsQueryObject | element
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.append( element: string | VeamsQueryObject | HTMLElement )
/**
* Insert content, specified by the parameter, to the end of each element in the set of matched elements
*
* @param {string|VeamsQueryObject|HTMLElement} element - HTML string | VeamsQueryObject | element
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.before( element: string | VeamsQueryObject | HTMLElement )
/**
* Insert content, specified by the parameter, before each element in the set of matched elements
*
* @param {string|VeamsQueryObject|HTMLElement} element - HTML string | VeamsQueryObject | element
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.after( element: string | VeamsQueryObject | HTMLElement )
/**
* Insert content, specified by the parameter, after each element in the set of matched elements
*
* @param {string|VeamsQueryObject|HTMLElement} element - HTML string | VeamsQueryObject | element
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.remove()
/**
* Remove the set of matched elements from the DOM
*
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.empty()
/**
* Remove all child nodes of the set of matched elements from the DOM
*
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.clone( [withChildren:boolean] )
/**
* Create a deep copy of the first element in the set of matched elements (without data and events)
*
* @param {Boolean} [withChildren=false] - clone with children (true/false)
* @return {HTMLElement} - clone of dom node
*/
.index()
/**
* Return an integer indicating the position of the first element in the set of matched elements relative
* to its sibling elements
*
* @return {Number} - index of element among its siblings
*/
.prop( propName:string )
/**
* Get the value of a property for the first element in the set of matched elements
*
* @param {String} propName - property name
* @return {String|Number|Boolean|Object} - property value
*/
.prop( propName:string, propVal:string|number|boolean|object )
/**
* Set value of a property for the set of matched elements
*
* @param {String} propName - property name
* @param {String|Number|Boolean|Object} propVal - property value
* @return {Object} - VeamsQueryObject
*/
.val()
/**
* Get the current value of the first element in the set of matched elements.
*
* @return {String|Number|Array} - value
*/
.val( val:string )
/**
* Set the value of each element in the set of matched elements
*
* @param {String} val - value
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.serialize()
/**
* Encode a set of form elements as a string for submission.
*
* @return {String} - serialized form data
*/
.each( fn: function)
/**
* Iterate over a VeamsQueryObject, executing a function for each matched element.
*
* @param {Function} fn - Callback function
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.on( eventNames:string[, selector:string] ,handler:function[, useCapture:boolean])
/**
* Attach an event handler function for one or more events to the selected elements
*
* @param {String} eventNames - name(s) of event(s) to be registered for matched set of elements
* @param {String} [selector] - selector string to filter descendants of selected elements triggering the event
* @param {Function} handler - event handler function
* @param {Boolean} [useCapture] - dispatch event to registered listeners before dispatching it to event target
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.off( eventNames:string[, selector:string])
/**
* Detach all event handlers for one or more event types from the selected elements
*
* @param {String} eventNames - name(s) of event(s) to be unregistered for matched set of elements
* @param {String} [selector] - selector string to filter descendants of selected elements triggering the event
* @param {Function} [handler] - event handler
* @return {VeamsQueryObject} - VeamsQueryObject
*/
.trigger( eventNames:string[, customData:object])
/**
* Execute all handlers and behaviors attached to the matched elements for the given event type
*
* @param {String} eventNames - name(s) of event(s) which will be trigger on the set of matched elements
* @param {Object} [customData] - custom data to pass with the event (accessible via event.detail)
* @return {VeamsQueryObject} - VeamsQueryObject
*/