back to Overview

$()

Creates a new Minified list, or register a DOMReady-handler.
Web module only.

Syntax Variants

$()
$(selector)
$(selector, context)
$(selector, context, childOnly)
$(list)
$(list, context)
$(list, context, childOnly)
$(object)
$(object, context)
$(object, context, childOnly)
$(domreadyFunction)

Parameters

selector
a simple, CSS-like selector for HTML elements. It supports '#id' (lookup by id), '.class' (lookup by class), 'element' (lookup by elements) and 'element.class' (combined class and element). Use commas to combine several selectors. You can also join two or more selectors by space to find elements which are descendants of the previous selectors. For example, use 'div' to find all div elements, '.header' to find all elements containing a class name called 'header', and 'a.popup' for all a elements with the class 'popup'. To find all elements with 'header' or 'footer' class names, write '.header, .footer'. To find all divs elements below the element with the id 'main', use '#main div'. The selector "*" will return all elements.
list
a list to copy. It can be an array, another Minified list, a DOM nodelist or anything else that has a length property and allows read access by index. A shallow copy of the list will be returned. Nulls will be automatically removed from the copy. Nested lists will be flattened, so the result only contains nodes.
object
an object to create a single-element list containing only the object. If the argument is null, an empty list will be returned.
domreadyFunction
a function to be registered using $.ready().
context (optional)
an optional selector, node or list of nodes which specifies one or more common ancestor nodes for the selection. The context can be specified as a selector, a list or using a single object, just like the first argument. The returned list will contain only descendants of the context nodes. All others will be filtered out.
childOnly (optional)
if set, only direct children of the context nodes are included in the list. Children of children will be filtered out. If omitted or not true, all descendants of the context will be included.
(return value)
the array-like Minified list object containing the content specified by the selector. Please note that if the first argument was a list, the existing order will be kept. If the first argument was a simple selector, the nodes are in document order. If you combined several selectors using commas, only the individual results of the selectors will keep the document order, but will then be joined to form a single list. This list will not be in document order anymore, unless you use a build without legacy IE support. Duplicate nodes will be removed from selectors, but not from lists.

Description

Creates a new Minified list, or register a DOMReady-handler. The most common usage is with a CSS-like selector. $() will then create a list containing all elements of the current HTML document that fulfill the filter conditions. Alternatively you can also specify a list of objects or a single object. Nested lists will automatically be flattened, and nulls will automatically be removed from the resulting list. If you call $() without any arguments, it will return an empty list.

Additionally, you can specify a second argument to provide a context. Contexts only make sense if you selected HTML nodes with the first parameter. Then the context limits the resulting list to include only those nodes that are descendants of the context nodes. The context can be either a selector, a list or a single HTML node, and will be processed like the first argument. A third arguments allows you to limit the list to only those elements that are direct children of the context nodes (so a child of a child would be filtered out).

The lists created by $() are the same type as the Minified lists created by Util's _() constructor and other Util methods. All Util methods work on lists created by $(). If you want to add your own methods to those lists, use MINI.M.

As a special shortcut, if you pass a function to $(), it will be registered using $.ready() to be executed when the DOM model is complete.

Example

A simple selector to find an element by id.

var l0 = $('#myElementId');

Example

You can pass an object reference to create a list containing only this element:

var l1 = $(document.getElementById('myElementId'));

Example

Lists and arrays will be copied:

var l2 = $([elementA, elementB, elementC]);

Example

Lists will be automatically flattened and nulls removed. So this list l3 has the same content as l2:

var l3 = $([elementA, [elementB, null, elementC], null]);

Example

This is a simple selector to find all elements with the given class.

var l4 = $('.myClass');

Example

A selector to find all elements of the given type.

var l5 = $('input'); // finds all input elements

Example

A selector to find all elements with the given type and class.

var l6 = $('input.myRadio'); // finds all input elements with class 'myRadio'

Example

A selector to find all elements that are descendants of the given element.

var l7 = $('#myForm input'); // finds all input elements contained in the element myForm

Example

A selector to find all elements that have either a CSS class 'a' or class 'b':

var l8 = $('.a, .b'); // finds all elements that have class a or class b

Example

A selector that finds all elements that are descendants of the element myDivision, are inside an element with the class .myForm and are input elements:

var l9 = $('#myDivision .myForm input');

Example

Contexts can make it easier to specify ancestors:

var l10 = $('.myRadio', '#formA, #formB, #formC');
The result is identical to:
var l10 = $('#formA .myRadio, #formB .myRadio, #formC .myRadio');

Example

Using one of the list functions, set(), on the list, and setting the element's text color. '$' at the beginning of the property name sets a CSS value.

$('#myElementId').set('$color', 'red');

Example

Most list methods return the list you invoked them on, allowing you to chain them:

$('#myForm .myRadio').addClass('uncheckedRadio')
                     .set('checked', true)
                     .on('click', function() {
                            $(this).set({@: 'uncheckedRadio');
                     });

Example

Using $() as a $.ready() shortcut:

$(function() {
  // in here you can safely work with the HTML document
});

See also..

  • _() is Util's alternative constructor for Minified lists
  • $$() works like $(), but returns the resulting list's first element.

Comments

comments powered by Disqus

back to Overview

Functions