Repository files navigation

Version :  ${VERSION}URL     :  http://github.com/sebastien/select.jsUpdated :  2016-08-05

Select is a subset of jQuery's functions implemented for DOM and SVGnodes, and targeting modern browsers. It is a thin wrapper around HTML5DOM & SVG APIs. It uses strict CSS3 selector query, and as such won't workas a drop-in replacement to jQuery, but will make the transition easier.

Select is recommended if you want to use the same API for DOM & SVG nodesand it is not critical to support a wide range of browser [quirks].

We use it internally atFFunction as most of the extra features presentin jQuery (events, promises, requests, animations) are already handledby our specialized modules, and that jQuery does not work well for SVGnodes, which we manipulate a lot.

That being said, jQuery dramaticallyimproved the quality of the Web as an environment, and it definitelyenabled us to focus on creating great applications.Things have changedfor the better now, and we don't need so much of a compatibility layeranymore. You should note, however, thatjQuery still fixes many modern-browser problemsso if you need to have a wide support and more features, jQuery is definitelythe better option.

The functions currently implemented are the following, available withingtheselect object (which you should alias to$).

Selection:

• find(selector)
• filter(selector)
• is|like(selector)
• forEach(callback)

Traversal:

• first()
• last()
• eq(index)|get(index)
• next(selector?)
• prev[ious](selector?)
• parent(selector?)
• parents(selector?)
• ancestors(selector?)
• children(selector?)

Manipulation::

• append(value)
• prepend(value)
• remove()
• after(value)
• before(value)
• replaceWith(value)
• clone()
• attr(attribute, value)/attr(attributes)
• css(attribute, value)/css(attributes)
• html(value?)/contents(value?)
• text(value?)
• val(value?)/value()`
• empty()
• [has|add|remove|toggle]Class(name)

Display::

• scrollTop(value?)
• scrollLeft(value?)
• width()
• height()
• position()
• offset()

Selection::

• select()

Events::

• bind(event, callback)
• change(event, callback)
• submit(event, callback)
• click(event, callback)
• keyup(event, callback)
• keydown(event, callback)
• keypress(event, callback)
• trigger(event)

New (not in jQuery)::

• n[ode]()
• set(value)
• contents(value?)
• redo(node)
• clear(length)
• expand(element|[element])
• like(selector)
• list()
• nodes(callback?)
• walk(callback?)
• wrap(node)
• equals(node|selection)
• contains(node|selection)

• SVG nodes are supported
• Only modern browsers are supported (IE10+)
• Only a subset of jQuery's functions are implemented (see above)
• OnlynodeType===ELEMENT_NODEs are supported (meaning nodocument orwindow supported)
• As a result, select filters out any node that is not an element node (in particular, the document node)
• Selectors are only CSS3 (ie. no Sizzle/jQuery extended syntax)
• No name/key/selector normalization (for performance)
• Distributed as an UMD module

You can include thescript directly from Github (although GitHub is not a CDN):

<script src="https://raw.githubusercontent.com/sebastien/select.js/master/build/select.js" />

The library can be used pretty much like you would use jQuery.

// Query the elements, and apply the operations$("ul li:even").text("Hello!");// It is also available at different locations$ == S == window.select

Select can be extended by "monkey-patched" the prototype:

select.Selection.prototype.<YOUR NEW METHOD> = function(...) {   // `this` will reference your `Selection` object}

If you'd like to look at the source code or contribute, Select's home pageis athttp://github.com/sebastien/select.js, feel free to post issues orpull requests. The goal is to keep this pretty minimal, so my preferencewould go to bug reports or performance improvements request as opposedto new features.

Also, a quick note about the implementation style:select's sourcecode is fairly repetitive, and would actually benefit from C-style macros.The reason is that I wanted to limit the use of lambdas and stay as closeto possible as C-style programming based onfor/while loops, minimizingconditional branching. This results in a more verbose, old-school style, butthat (hopefully) translates into better performance.

Onceselect stabilizes, I will probably factor out the common partsand measure the performance impact.

Once loaded,select.jswill be available as an object/modulenamedselect in the global scope. The module can be invoked asfollows to create a selection:

select(selector, scope)

:The main function used to create a selection.

Theselect object (module) also has the following properties

• VERSION asM.m.R (Major,minor,Revision)
• NAME (select)
• LICENSE, the URL to the license file
• STATUS asLOADING orLOADED

The module will also be registered at the following locations:

• window.select
• window.$ andwindow.S if these values are not defined
• extend.modules.select if the Extend library is loaded.

Select is based on a couple of basic functions to query, filter and matchnodes against CSS-3 selectors. These work in modern browsers, includingour beloved IE10+.

select.match(selector:String, node:Node):Boolean

: Tells if the givennode matches the given selector. Thisfunction usesNode.{matches|mozMatchesSelector|webkitMatchesSelector}or falls back to a default (obviously slower) implementation.

The function returns `true` or `false`

select.query(selector:String, node:Node?):[Element]

:Queries all the descendants of node that match the given selector. Thisis a wrapper aroundElement.querySelectorAll.

  function returns an array of the matching element nodes.

//select.xpath(selector:String, node:Node?):[Element]////:Queries all the descendants of node that match the given XPath expression. This//is a wrapper arounddocument.evaluate.//Seehttps://developer.mozilla.org/en-US/docs/Introduction_to_using_XPath_in_JavaScript//// function returns an array of the matching element nodes.//

select.filter(selector:String, node:Node?):[Node]

:Filters all the nodes that match the given selector. This is a wrapperaroundselect.filter.

 This function returns the subset of the array with matching nodes.

The following predicates allow to discriminate values and identify theirtypes.

Selection.Is(value)

:Tells if the given value is aSelection instance

 select.Selection.Is(new Selection ());

Selection.IsList(value)

:Tells if the given value is aSelection,Array orNodeList

Selection.IsElement(node)

:Tells if the given value is a DOM or SVG element

select.Selection.IsElement(document.createElement("div"));select.Selection.IsElement(document) == false

Selection.IsText(node)

:Tells if the given value is Text node or not

Selection.IsNode(node)

:Tells if the given value is a DOM or SVG node

select.Selection.IsNode(document.createElement("div")) == trueselect.Selection.IsNode(document) == true

Selection.IsDOM(node)

:Tells wether the node is a DOM node or not

select.Selection.IsDOM(document.createElement("div")) == true;select.Selection.IsDOM(document.createElementNS("http://www.w3.org/2000/svg", "svg")) == false;

Selection.IsSVG(node)

:Tells wether the node is an SVG node or not

select.Selection.IsSVG(document.createElement("div")) == false;select.Selection.IsSVG(document.createElementNS("http://www.w3.org/2000/svg", "svg")) == true;

Selection.IsSelection(value)

:Tells wether the node a selection instance or not

Selection.AsElementList(value:Any)

:Ensures that the given value expands to a node list. This willonly match node types and won't do any kind of querying. It justmakes sure that only element nodes are returned.

These functions allow to query the DOM/SVG tree, find & filter nodes.

Selection.find(selector)

:Finds all the nodes that match the given selector amongst the descendantsof the currently selected nodes. The resulting selector will havethis selection as scope only if this selection is not empty.If the selection is empty, the the empty selection will be returned.

 - `selector` is expected to be a string - the resulting selection will be flat (ie. an array of node)

Selection.filter(selector)

:Filters all the nodes within the current selection that matchthe give selector. The resulting selection will havethis selection as scope only if this selection is not empty.

 - `selector` is expected to be a string - the resulting selection will be flat (ie. an array of node)

Selection.iterate(callback:Function(element, index)

:Invokes the given callback for each element of the selection wrappedin a selection object. Breaks if the callback returnsfalse.

Selection.is(selector)

:Tells if all the selected nodes match the given selector

Selection.list()

:Returns an array of properly wrapped nodes.

Selection.first()

:Returns a new selection made of thefirst nodeof this selection. If theselection is empty or made of 1 node, this function is transparent.

Selection.last()

:Returns a new selection made of thelast nodeof this selection. If theselection is empty or made of 1 node, this function is transparent.

Selection.eq(index:Integer) /Selection.get(index:Integer)

:Returns a new selection made of thenode at the givenindex.ifindex is negative, then the index will be relative to the endof the nodes array. If the index is out of the node array bounds,theEmpty selection is returned.

Selection.next(selector:String?)

:Selects each next sibling element of the current selection. Ifselector is given, only the matching elements will be added.

Selection.previous(selector:String?)

:Selects each previous sibling element of the current selection. Ifselector is given, only the matching elements will be added.

Selection.parent(selector:String?)

:Returns a selection of the direct parents of the current selectednodes. If a selector is given, only the matching parentswill be returned.

Selection.ancestors(selector:(String|Callback)?,limit:Number|Selection?)

:Returns a selection of the ancestors of the current selectednodes. If a selector is given, only the matching parentswill be returned.

The `limit` argument can be either a number, in which caseit will limit the number of ancestors to the given number,or it can be a node/selection, in which case it will notgo beyond the given node.

Selection.children(selector:String?)

:Returns a selection of the children of the current selectednodes. If a selector is given, only the matching childrenwill be returned.

Selection.nodes(callback?):[Node]

:Returns a list of all the child nodes within this element, optionallyinvoking the given callback.will be returned. Note that we're talking aboutNode here,not elements, returned as an array.

The iteration will exit whenever `callback` returns `false`.

Selection.walk(callback?):this

:Invokes the given callback by making depth-first traversal ofall the elements in this selection, passing (node, count) asargument. Note that unlike most other functions, the callbackwill be given any node, not only element nodes, and theywill be given without any selection wrapping.

The iteration will exit whenever `callback` returns `false`.

Selection.append(value:Number|String|Node|[Node]|Selection):this

:Appends the given nodes to the first node in the selection. Whena string or number is given, then it is wrapped in a text node.

Selection.prepend(value:Number|String|Node|[Node]|Selection):this

:Prepends the given nodes to the first node in the selection. Whena string or number is given, then it is wrapped in a text node.

Selection.remove():Selection

:Removes all the nodes from this selection from their parent

Selection.extend(value:Number|String|Node|[Node]|Selection):this

:Appends the given nodes to the first node in the selection. Whena string or number is given, then it is wrapped in a text node.

Selection.after(value:Node|[Node]|Selection):this

:Appends the given nodes after first node in the selection

Selection.before(value:Node|[Node]|Selection):this

:Appends the given nodes before the first node in the selection

Selection.replaceWith(node:Node|[Node]|Selection):this

:Replaces nodes in the given selection with the given nodes. The nodesin the current selection will be removed, while the given node listor selection will not be changed (but the nodes parent will change,obviously).

Selection.equals(node:Node|Selection):bool

:Tells if this selection equals the given node or selection.

Selection.contains(node:Node|Selection?)

:Tells if the current selection contains all of the given nodes/selections.

//Selection.redo(node:Node|Selection):Selection////:Redo the selection in the given context, returning a new//selection.//

Selection.wrap(node:Node):this

:Wraps all the nodes in the give node and returns a new selection with the given node.it is equivalent to$(node).add(this)

Selection.clone():Selection

:Clones the first node of this selection

Selection.empty():this

:Removes all the children from all the nodes in the selection

Selection.isEmpty():Boolean

:Tells if the given selection is empty or not.

Selection.val(value?):Any|Selection /Selection.value

:Whenvalue is not specified ,retrieves the first non-nullvalue for the given input fields. If value is specified, thenthe value will be set in all fields.

Selection.text(value:String?):String|Selection

:Whenvalue is not specified, retrieves the first non-nulltext value for the nodes in the selection, otherwise sets thetext for all nodes as the given string.

 Note that if `value` is not a string, it will be JSONified. This uses [`Node.textContent`](http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#Node3-textContent)

Selection.html(value:Number|String|Selection|Node|[Node]?):thisSelection.contents(value:Number|String|Selection|Node|[Node]?):this

:Whenvalue is not specified, retrieves the first non-nullHTML value for the nodes in the selection, otherwise sets theHTML for all nodes as the given string.

This uses [`Node.innerHTML`](https://dvcs.w3.org/hg/innerhtml/raw-file/tip/index.html#innerhtml)when the given content is a string or a number. If a selection ora node is given, then only the first node in the selection willbe modified.FIXME: Not sure if that's the best behaviour... should be clone theother nodes, or warn?

Selection.attr(name:String):Any

:Retrieves the given attribue value

Selection.attr(name:String, value:Any)

:Sets the given attribute with the given value

Selection.attr(values:{String:Any})

:Sets the given attributes based on the given map, JSONified ifnot a string.

These function will JSONify non-string values.

Selection.data():undefined|{String:Any}

:Retrieves all the data attributesof the first nodewithinthe selection, as a map, orundefined if none.

Selection.data(name:String):Any

:Retrieves the given data attribute,undefined if not found.

Selection.data(name:String, value:Any)

:Sets the given data attribute with the given value in all the nodeswithin the selection, JSONified if not a string (non-DOM only)

Selection.data(values:{String:Any})

:Sets the given data attributes based on the given map for all the nodes,in the selection JSONified if not a string (non-DOM only)

These work both for HTML and SVG nodes. In case of SVG, thedata will be stored and retrieved from JSON-encoded data attributes.

The main difference with HTML will be that the attributes won'tbe converted back tolower-case fromcamelCase. For instance

select("svg").data("someProperty", "true")

will be stored asdata-someProperty and notdata-some-propertylike it would be the case in an original HTML document.

Selection.addClass(name:String|[String],‥)

:Adds the given class to all the nodes in the selection.

 This uses `Node.classList` with a custom fallback that works for DOM & SVG nodes.

Selection.removeClass(name:String?)

:Removes the given class from all the nodes in the selection.

 This uses `Node.classList` with a custom fallback that works for DOM & SVG nodes.

Selection.hasClass(name:String?)

:Tells if there is at least one node that has the given class

Selection.toggleClass(name:String, Value|Predicate?)

:Toggles the class with the given name if the value is true. Incase the value is a predicate, it will be invoked withthe node and index as arguments.

These function will convert any value to "px" if not given as a string. Alsonote that there is no CSS property normalization, they're passed as-is.

Selection.css(name:String):Any

:Retrieves the given CSS property

Selection.css(name:String, value:Any)

:Sets the given CSS property with the given value

Selection.css(values:{String:Any})

:Sets the given CSS properties based on the given map, JSONified ifnot a string.

Selection.width():Int

:Returns the width of the first node in the selection in pixels.

 This uses `getBoundingClientRect()`, returns `0` if the selection if empty.

Selection.height():Int

:Returns the height of the first node in the selection in pixels.

 This uses `getBoundingClientRect()`, returns `0` if the selection is empty.

Selection.offset():{left:Int, top:Int}

:Returns the{left,top} offset of this node, relative toits offset parent.

 This uses `offsetTop` for DOM nodes and `getBoundingClientRect` for SVG nodes.

Selection.scrollTop(value:Int?):Int

:TODO

Selection.scrollLeft(value:Int?):Int

:TODO

`Selection.focus():Selection

:Sets the focus on the first node of this selection.

`Selection.focus(callback):Selection

:Binds the givencallback to the focus event. See Events section.

`Selection.select():Selection

:Selects all the elements in this selection

`Selection.select(callback):Selection

:Binds the givencallback to the select event. See Events section.

Selection.bind(event:String, callback:Function[event], capture:Bool?)

:Binds the givencallback to handle the givenevent in theselected elements.

Selection.unbind(event:String, callback:Function[event])

:Unbinds the givencallback to handle the givenevent in theselected elements.

Selection.trigger(event:Event|String)

:Dispatches the givenevent, given by name or value. Ifthe event is a string, then the event will be createdusingdocument.createEvent. In all cases, it will bedispatched using<node>.dispatchEvent.

See <https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events> for more details.

The following events are readily available as methods from the selectionobject:

Mouse:

• click
• dblclick
• mousedown
• mouseup
• mouseover
• mousemove
• mouseout
• mouseenter
• mouseleave

Drag:

• dragstart
• drag
• dragenter
• dragleave
• dragend
• dragover
• drop

Keyboard:

• keydown
• keypress
• keyup

Body:

• load
• unload

Window:

• resize
• scroll

Forms:

• select
• change
• submit
• reset
• blur
• focusin
• focusout

Selection.n[ode](index?):Node|undefined

:Returns node with the given index (or first one) directly as a node.This is similar toeq, except that it returns the node insteadof a selection.

Selection.set(value|[value])

:Sets this selection's content to be the given node, arrayof nodes or selection.

Selection.copy()

:Creates a copy fo the selection, but not a copy of the nodes.

Selection.clear(length)

:Clears the current selection until there are onlylength elementsavailable.

Selection.expand(element|elements)

:Expands the selection with the given element(s). Non-elementvalues will be filtered out.