* @constructor
* @private
* @name jQuery
+ * @cat Core
*/
function jQuery(a,c) {
// Watch for when a jQuery object is passed as the selector
if ( a.jquery )
- return $( jQuery.merge( a, [] ) );
+ return jQuery( jQuery.merge( a, [] ) );
// Watch for when a jQuery object is passed at the context
if ( c && c.jquery )
- return $( c ).find(a);
+ return jQuery( c ).find(a);
// If the context is global, return a new object
if ( window == this )
// Map over the $ in case of overwrite
if ( typeof $ != "undefined" )
jQuery._$ = $;
+
+/**
+ * This function accepts a string containing a CSS selector,
+ * basic XPath, or raw HTML, which is then used to match a set of elements.
+ * The HTML string is different from the traditional selectors in that
+ * it creates the DOM elements representing that HTML string, on the fly,
+ * to be (assumedly) inserted into the document later.
+ *
+ * The core functionality of jQuery centers around this function.
+ * Everything in jQuery is based upon this, or uses this in some way.
+ * The most basic use of this function is to pass in an expression
+ * (usually consisting of CSS or XPath), which then finds all matching
+ * elements and remembers them for later use.
+ *
+ * By default, $() looks for DOM elements within the context of the
+ * current HTML document.
+ *
+ * @example $("div > p")
+ * @desc This finds all p elements that are children of a div element.
+ * @before <p>one</p> <div><p>two</p></div> <p>three</p>
+ * @result [ <p>two</p> ]
+ *
+ * @example $("<div><p>Hello</p></div>").appendTo("#body")
+ * @desc Creates a div element (and all of its contents) dynamically, and appends it to the element with the ID of body.
+ *
+ * @name $
+ * @param String expr An expression to search with, or a string of HTML to create on the fly.
+ * @cat Core
+ * @type jQuery
+ */
+
+/**
+ * This function accepts a string containing a CSS selector, or
+ * basic XPath, which is then used to match a set of elements with the
+ * context of the specified DOM element, or document
+ *
+ * @example $("div", xml.responseXML)
+ * @desc This finds all div elements within the specified XML document.
+ *
+ * @name $
+ * @param String expr An expression to search with.
+ * @param Element context A DOM Element, or Document, representing the base context.
+ * @cat Core
+ * @type jQuery
+ */
+
+/**
+ * Wrap jQuery functionality around a specific DOM Element.
+ * This function also accepts XML Documents and Window objects
+ * as valid arguments (even though they are not DOM Elements).
+ *
+ * @example $(document).find("div > p")
+ * @before <p>one</p> <div><p>two</p></div> <p>three</p>
+ * @result [ <p>two</p> ]
+ *
+ * @example $(document).ready( loaded );
+ * @desc Executes the "loaded" function when the DOM is ready to
+ * be manipulated.
+ *
+ * @name $
+ * @param Element elem A DOM element to be encapsulated by a jQuery object.
+ * @cat Core
+ * @type jQuery
+ */
+
+/**
+ * Wrap jQuery functionality around a set of DOM Elements.
+ *
+ * @example $( myForm.elements ).hide()
+ * @desc Hides all the input elements within a form
+ *
+ * @name $
+ * @param Array<Element> elems An array of DOM elements to be encapsulated by a jQuery object.
+ * @cat Core
+ * @type jQuery
+ */
+
+/**
+ * A shorthand for $(document).ready(), allowing you to bind a function
+ * to be executed when the DOM document has finished loading.
+ *
+ * @example $( loaded )
+ * @desc Executes the function "loaded" when the DOM is ready to be used.
+ *
+ * @name $
+ * @param Function fn The function to execute when the DOM is ready.
+ * @cat Core
+ * @type jQuery
+ */
+
+/**
+ * A means of creating a duplicate copy of a jQuery object.
+ *
+ * @example var div = $("div");
+ * $( div ).find("p")
+ * @desc Locates all p elements with all div elements, without disrupting the original jQuery object contained in 'div'.
+ *
+ * @name $
+ * @param jQuery obj The jQuery object to be cloned.
+ * @cat Core
+ * @type jQuery
+ */
// Map the jQuery namespace to the '$' one
var $ = jQuery;
* stucture into a document, without ruining the original semantic
* qualities of a document.
*
- * The way that is works is that it goes through the first element argument
- * provided and finds the deepest element within the structure - it is that
- * element that will en-wrap everything else.
+ * This works by going through the first element
+ * provided (which is generated, on the fly, from the provided HTML)
+ * and finds the deepest ancestor element within its
+ * structure - it is that element that will en-wrap everything else.
*
* @example $("p").wrap("<div class='wrap'></div>");
* @before <p>Test Paragraph.</p>
*
* @name wrap
* @type jQuery
- * @any String html A string of HTML, that will be created on the fly and wrapped around the target.
- * @any Element elem A DOM element that will be wrapped.
- * @any Array<Element> elems An array of elements, the first of which will be wrapped.
- * @any Object obj Any object, converted to a string, then a text node.
+ * @param String html A string of HTML, that will be created on the fly and wrapped around the target.
+ * @cat DOM/Manipulation
+ */
+
+ /**
+ * Wrap all matched elements with a structure of other elements.
+ * This wrapping process is most useful for injecting additional
+ * stucture into a document, without ruining the original semantic
+ * qualities of a document.
+ *
+ * This works by going through the first element
+ * provided and finding the deepest ancestor element within its
+ * structure - it is that element that will en-wrap everything else.
+ *
+ * @example $("p").wrap("<div class='wrap'></div>");
+ * @before <p>Test Paragraph.</p>
+ * @result <div class='wrap'><p>Test Paragraph.</p></div>
+ *
+ * @name wrap
+ * @type jQuery
+ * @param Element elem A DOM element that will be wrapped.
* @cat DOM/Manipulation
*/
wrap: function() {
},
/**
- * Append any number of elements to the inside of all matched elements.
+ * Append any number of elements to the inside of every matched elements,
+ * generated from the provided HTML.
* This operation is similar to doing an appendChild to all the
* specified elements, adding them into the document.
*
*
* @name append
* @type jQuery
- * @any String html A string of HTML, that will be created on the fly and appended to the target.
- * @any Element elem A DOM element that will be appended.
- * @any Array<Element> elems An array of elements, all of which will be appended.
- * @any Object obj Any object, converted to a string, then a text node.
+ * @param String html A string of HTML, that will be created on the fly and appended to the target.
+ * @cat DOM/Manipulation
+ */
+
+ /**
+ * Append an element to the inside of all matched elements.
+ * This operation is similar to doing an appendChild to all the
+ * specified elements, adding them into the document.
+ *
+ * @example $("p").append( $("#foo")[0] );
+ * @before <p>I would like to say: </p><b id="foo">Hello</b>
+ * @result <p>I would like to say: <b id="foo">Hello</b></p>
+ *
+ * @name append
+ * @type jQuery
+ * @param Element elem A DOM element that will be appended.
+ * @cat DOM/Manipulation
+ */
+
+ /**
+ * Append any number of elements to the inside of all matched elements.
+ * This operation is similar to doing an appendChild to all the
+ * specified elements, adding them into the document.
+ *
+ * @example $("p").append( $("b") );
+ * @before <p>I would like to say: </p><b>Hello</b>
+ * @result <p>I would like to say: <b>Hello</b></p>
+ *
+ * @name append
+ * @type jQuery
+ * @param Array<Element> elems An array of elements, all of which will be appended.
* @cat DOM/Manipulation
*/
append: function() {
},
/**
- * Prepend any number of elements to the inside of all matched elements.
+ * Prepend any number of elements to the inside of every matched elements,
+ * generated from the provided HTML.
+ * This operation is the best way to insert dynamically created elements
+ * inside, at the beginning, of all the matched element.
+ *
+ * @example $("p").prepend("<b>Hello</b>");
+ * @before <p>I would like to say: </p>
+ * @result <p><b>Hello</b>I would like to say: </p>
+ *
+ * @name prepend
+ * @type jQuery
+ * @param String html A string of HTML, that will be created on the fly and appended to the target.
+ * @cat DOM/Manipulation
+ */
+
+ /**
+ * Append an element to the inside of all matched elements.
+ * This operation is the best way to insert an element inside, at the
+ * beginning, of all the matched element.
+ *
+ * @example $("p").prepend( $("#foo")[0] );
+ * @before <p>I would like to say: </p><b id="foo">Hello</b>
+ * @result <p><b id="foo">Hello</b>I would like to say: </p>
+ *
+ * @name prepend
+ * @type jQuery
+ * @param Element elem A DOM element that will be appended.
+ * @cat DOM/Manipulation
+ */
+
+ /**
+ * Append any number of elements to the inside of all matched elements.
* This operation is the best way to insert a set of elements inside, at the
* beginning, of all the matched element.
*
- * @example $("p").prepend("<b>Hello</b>");
- * @before <p>, how are you?</p>
- * @result <p><b>Hello</b>, how are you?</p>
+ * @example $("p").prepend( $("b") );
+ * @before <p>I would like to say: </p><b>Hello</b>
+ * @result <p><b>Hello</b>I would like to say: </p>
*
* @name prepend
* @type jQuery
- * @any String html A string of HTML, that will be created on the fly and prepended to the target.
- * @any Element elem A DOM element that will be prepended.
- * @any Array<Element> elems An array of elements, all of which will be prepended.
- * @any Object obj Any object, converted to a string, then a text node.
+ * @param Array<Element> elems An array of elements, all of which will be appended.
* @cat DOM/Manipulation
*/
prepend: function() {
},
/**
- * Insert any number of elements before each of the matched elements.
+ * Insert any number of dynamically generated elements before each of the
+ * matched elements.
*
* @example $("p").before("<b>Hello</b>");
- * @before <p>how are you?</p>
- * @result <b>Hello</b><p>how are you?</p>
+ * @before <p>I would like to say: </p>
+ * @result <b>Hello</b><p>I would like to say: </p>
+ *
+ * @name before
+ * @type jQuery
+ * @param String html A string of HTML, that will be created on the fly and appended to the target.
+ * @cat DOM/Manipulation
+ */
+
+ /**
+ * Insert an element before each of the matched elements.
+ *
+ * @example $("p").before( $("#foo")[0] );
+ * @before <p>I would like to say: </p><b id="foo">Hello</b>
+ * @result <b id="foo">Hello</b><p>I would like to say: </p>
+ *
+ * @name before
+ * @type jQuery
+ * @param Element elem A DOM element that will be appended.
+ * @cat DOM/Manipulation
+ */
+
+ /**
+ * Insert any number of elements before each of the matched elements.
+ *
+ * @example $("p").before( $("b") );
+ * @before <p>I would like to say: </p><b>Hello</b>
+ * @result <b>Hello</b><p>I would like to say: </p>
*
* @name before
* @type jQuery
- * @any String html A string of HTML, that will be created on the fly and inserted.
- * @any Element elem A DOM element that will beinserted.
- * @any Array<Element> elems An array of elements, all of which will be inserted.
- * @any Object obj Any object, converted to a string, then a text node.
+ * @param Array<Element> elems An array of elements, all of which will be appended.
* @cat DOM/Manipulation
*/
before: function() {
},
/**
+ * Insert any number of dynamically generated elements after each of the
+ * matched elements.
+ *
+ * @example $("p").after("<b>Hello</b>");
+ * @before <p>I would like to say: </p>
+ * @result <p>I would like to say: </p><b>Hello</b>
+ *
+ * @name after
+ * @type jQuery
+ * @param String html A string of HTML, that will be created on the fly and appended to the target.
+ * @cat DOM/Manipulation
+ */
+
+ /**
+ * Insert an element after each of the matched elements.
+ *
+ * @example $("p").after( $("#foo")[0] );
+ * @before <b id="foo">Hello</b><p>I would like to say: </p>
+ * @result <p>I would like to say: </p><b id="foo">Hello</b>
+ *
+ * @name after
+ * @type jQuery
+ * @param Element elem A DOM element that will be appended.
+ * @cat DOM/Manipulation
+ */
+
+ /**
* Insert any number of elements after each of the matched elements.
*
- * @example $("p").after("<p>I'm doing fine.</p>");
- * @before <p>How are you?</p>
- * @result <p>How are you?</p><p>I'm doing fine.</p>
+ * @example $("p").after( $("b") );
+ * @before <b>Hello</b><p>I would like to say: </p>
+ * @result <p>I would like to say: </p><b>Hello</b>
*
* @name after
* @type jQuery
- * @any String html A string of HTML, that will be created on the fly and inserted.
- * @any Element elem A DOM element that will beinserted.
- * @any Array<Element> elems An array of elements, all of which will be inserted.
- * @any Object obj Any object, converted to a string, then a text node.
+ * @param Array<Element> elems An array of elements, all of which will be appended.
* @cat DOM/Manipulation
*/
after: function() {
}), arguments );
},
+ /**
+ * Create cloned copies of all matched DOM Elements. This does
+ * not create a cloned copy of this particular jQuery object,
+ * instead it creates duplicate copies of all DOM Elements.
+ * This is useful for moving copies of the elements to another
+ * location in the DOM.
+ *
+ * @example $("b").clone().prependTo("p");
+ * @before <b>Hello</b><p>, how are you?</p>
+ * @result <b>Hello</b><p><b>Hello</b>, how are you?</p>
+ *
+ * @name clone
+ * @type jQuery
+ * @cat DOM/Manipulation
+ */
clone: function(deep) {
return this.pushStack( jQuery.map( this, function(a){
return a.cloneNode( deep != undefined ? deep : true );
* @param Number int
* @param Function fn The function doing the DOM manipulation.
* @type jQuery
+ * @cat Core
*/
domManip: function(args, table, dir, fn){
var clone = this.size() > 1;
* @param Array a
* @param Array args
* @type jQuery
+ * @cat Core
*/
pushStack: function(a,args) {
var fn = args && args[args.length-1];
var old = this.get();
this.get( a );
if ( fn.constructor == Function )
- return this.each( fn );
+ this.each( fn );
this.get( old );
}
* @private
* @name extend
* @param Object obj
- * @param Object prop
* @type Object
+ * @cat Core
*/
/**
* Extend one object with another, returning the original,
* modified, object. This is a great utility for simple inheritance.
*
- * @name jQuery.extend
+ * @name $.extend
* @param Object obj The object to extend
* @param Object prop The object that will be merged into the first.
* @type Object
* @private
* @name init
* @type undefined
+ * @cat Core
*/
init: function(){
jQuery.initDone = true;
var a = arguments;
return this.each(function(){
for ( var j = 0; j < a.length; j++ )
- $(a[j])[n]( this );
+ jQuery(a[j])[n]( this );
});
};
});
* A generic iterator function, which can be used to seemlessly
* iterate over both objects and arrays.
*
- * @name jQuery.each
+ * @name $.each
* @param Object obj The object, or array, to iterate over.
* @param Object fn The function that will be executed on every object.
* @type Object
oHeight = e.offsetHeight;
oWidth = e.offsetWidth;
} else {
- e = $(e.cloneNode(true)).css({
- visibility: "hidden", position: "absolute", display: "block"
- }).prependTo("body")[0];
+ e = jQuery(e.cloneNode(true)).css({
+ visibility: "hidden", position: "absolute", display: "block", right: "0", left: "0"
+ }).appendTo(e.parentNode)[0];
+
+ var parPos = jQuery.css(e.parentNode,"position");
+ if ( parPos == "" || parPos == "static" )
+ e.parentNode.style.position = "relative";
oHeight = e.clientHeight;
oWidth = e.clientWidth;
+ if ( parPos == "" || parPos == "static" )
+ e.parentNode.style.position = "static";
+
e.parentNode.removeChild(e);
}
});
* @test t( "Is Visible", "input:visible", ["text1","text2","radio1","radio2","check1","check2"] );
* @test t( "Is Hidden", "input:hidden", ["hidden1","hidden2"] );
*
- * @name jQuery.find
+ * @name $.find
+ * @type Array<Element>
* @private
+ * @cat Core
*/
find: function( t, context ) {
// Make sure that the context is a DOM Element
innerHTML: "innerHTML",
className: "className",
value: "value",
- disabled: "disabled"
+ disabled: "disabled",
+ checked: "checked"
};
if ( fix[name] ) {
/**
* Remove the whitespace from the beginning and end of a string.
*
- * @private
- * @name jQuery.trim
+ * @name $.trim
* @type String
* @param String str The string to trim.
+ * @cat Javascript
*/
trim: function(t){
return t.replace(/^\s+|\s+$/g, "");
* All ancestors of a given element.
*
* @private
- * @name jQuery.parents
+ * @name $.parents
* @type Array<Element>
* @param Element elem The element to find the ancestors of.
+ * @cat DOM/Traversing
*/
parents: function( elem ){
var matched = [];
* All elements on a specified axis.
*
* @private
- * @name jQuery.sibling
+ * @name $.sibling
* @type Array
* @param Element elem The element to find all the siblings of (including itself).
+ * @cat DOM/Traversing
*/
sibling: function(elem, pos, not) {
var elems = [];
/**
* Merge two arrays together, removing all duplicates.
*
- * @private
- * @name jQuery.merge
+ * @name $.merge
* @type Array
* @param Array a The first array to merge.
* @param Array b The second array to merge.
+ * @cat Javascript
*/
merge: function(first, second) {
var result = [];
* in to this method will be passed two arguments: 'a' (which is the
* array item) and 'i' (which is the index of the item in the array).
*
- * @private
- * @name jQuery.grep
+ * @name $.grep
* @type Array
* @param Array array The Array to find items in.
* @param Function fn The function to process each item against.
* @param Boolean inv Invert the selection - select the opposite of the function.
+ * @cat Javascript
*/
grep: function(elems, fn, inv) {
// If a string is passed in for the function, make a function
* from the array. Both of these changes imply that the size of the array may not
* be the same size upon completion, as it was when it started.
*
- * @private
- * @name jQuery.map
+ * @name $.map
* @type Array
* @param Array array The Array to translate.
* @param Function fn The function to process each item against.
+ * @cat Javascript
*/
map: function(elems, fn) {
// If a string is passed in for the function, make a function
safari: /webkit/.test(b),
opera: /opera/.test(b),
msie: /msie/.test(b) && !/opera/.test(b),
- mozilla: /mozilla/.test(b) && !/compatible/.test(b)
+ mozilla: /mozilla/.test(b) && !/(compatible|webkit)/.test(b)
};
// Check to see if the W3C box model is being used
* Get the current CSS background of the first matched element.
*
* @example $("p").background();
- * @before <p>This is just a test.</p>
- * @result ""
+ * @before <p style="background:blue;">This is just a test.</p>
+ * @result "blue"
*
* @name background
* @type String
*/
css: "width,height,top,left,position,float,overflow,color,background".split(","),
+
+ /**
+ * Reduce the set of matched elements to a single element.
+ * The position of the element in the set of matched elements
+ * starts at 0 and goes to length - 1.
+ *
+ * @example $("p").eq(1)
+ * @before <p>This is just a test.</p><p>So is this</p>
+ * @result [ <p>So is this</p> ]
+ *
+ * @name eq
+ * @type jQuery
+ * @param Number pos The index of the element that you wish to limit to.
+ * @cat Core
+ */
+
+ /**
+ * Reduce the set of matched elements to all elements before a given position.
+ * The position of the element in the set of matched elements
+ * starts at 0 and goes to length - 1.
+ *
+ * @example $("p").lt(1)
+ * @before <p>This is just a test.</p><p>So is this</p>
+ * @result [ <p>This is just a test.</p> ]
+ *
+ * @name lt
+ * @type jQuery
+ * @param Number pos Reduce the set to all elements below this position.
+ * @cat Core
+ */
+
+ /**
+ * Reduce the set of matched elements to all elements after a given position.
+ * The position of the element in the set of matched elements
+ * starts at 0 and goes to length - 1.
+ *
+ * @example $("p").gt(0)
+ * @before <p>This is just a test.</p><p>So is this</p>
+ * @result [ <p>So is this</p> ]
+ *
+ * @name gt
+ * @type jQuery
+ * @param Number pos Reduce the set to all elements after this position.
+ * @cat Core
+ */
+
+ /**
+ * Filter the set of elements to those that contain the specified text.
+ *
+ * @example $("p").contains("test")
+ * @before <p>This is just a test.</p><p>So is this</p>
+ * @result [ <p>This is just a test.</p> ]
+ *
+ * @name contains
+ * @type jQuery
+ * @param String str The string that will be contained within the text of an element.
+ * @cat DOM/Traversing
+ */
filter: [ "eq", "lt", "gt", "contains" ],
each: {
+ /**
+ * Remove an attribute from each of the matched elements.
+ *
+ * @example $("input").removeAttr("disabled")
+ * @before <input disabled="disabled"/>
+ * @result <input/>
+ *
+ * @name removeAttr
+ * @type jQuery
+ * @param String name The name of the attribute to remove.
+ * @cat DOM
+ */
removeAttr: function( key ) {
this.removeAttribute( key );
},
* @cat Effects
*/
toggle: function(){
- $(this)[ $(this).is(":hidden") ? "show" : "hide" ].apply( $(this), arguments );
+ jQuery(this)[ jQuery(this).is(":hidden") ? "show" : "hide" ].apply( jQuery(this), arguments );
},
/**
*/
bind: function( type, fn ) {
if ( fn.constructor == String )
- fn = new Function("e", ( !fn.indexOf(".") ? "$(this)" : "return " ) + fn);
+ fn = new Function("e", ( !fn.indexOf(".") ? "jQuery(this)" : "return " ) + fn);
jQuery.event.add( this, type, fn );
},
git.asbjorn.biz / jquery.git / blobdiff