From ca438a718a27eedc25572cafb3fb22780cf9fbb7 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=B6rn=20Zaefferer?= Date: Tue, 2 Jan 2007 19:03:12 +0000 Subject: [PATCH] Improved docs for append, prepend, before and after, merging the three pairs into one --- newandnoteworthy.txt | 1 + src/jquery/coreTest.js | 36 ++++++++++---- src/jquery/jquery.js | 124 +++++++++++------------------------------------- 3 files changed, 57 insertions(+), 104 deletions(-) diff --git a/newandnoteworthy.txt b/newandnoteworthy.txt index cf8dcd5..89f757a 100644 --- a/newandnoteworthy.txt +++ b/newandnoteworthy.txt @@ -19,6 +19,7 @@ New and Noteworthy - You can now unbind event handlers from within themselves - Documented filter(Function) - Improved docs for FX module, merging method descriptions and marking optional arguments + - Improved docs for append, prepend, before and after, merging the three pairs into one 1.0.4 ----- diff --git a/src/jquery/coreTest.js b/src/jquery/coreTest.js index d1035cf..c24bda0 100644 --- a/src/jquery/coreTest.js +++ b/src/jquery/coreTest.js @@ -170,8 +170,8 @@ test("wrap(String|Element)", function() { ok( result.text() == defaultText, 'Check for element wrapping' ); }); -test("append(String|Element|Array<Element>)", function() { - expect(4); +test("append(String|Element|Array<Element>|jQuery)", function() { + expect(5); var defaultText = 'Try them out:' var result = $('#first').append('buga'); ok( result.text() == defaultText + 'buga', 'Check if text appending works' ); @@ -186,10 +186,15 @@ test("append(String|Element|Array<Element>)", function() { expected = "This link has class=\"blog\": Simon Willison's WeblogTry them out:Yahoo"; $('#sap').append([document.getElementById('first'), document.getElementById('yahoo')]); ok( expected == $('#sap').text(), "Check for appending of array of elements" ); + + reset(); + expected = "This link has class=\"blog\": Simon Willison's WeblogTry them out:Yahoo"; + $('#sap').append($("#first, #yahoo")); + ok( expected == $('#sap').text(), "Check for appending of jQuery object" ); }); -test("prepend(String|Element|Array<Element>)", function() { - expect(4); +test("prepend(String|Element|Array<Element>|jQuery)", function() { + expect(5); var defaultText = 'Try them out:' var result = $('#first').prepend('buga'); ok( result.text() == 'buga' + defaultText, 'Check if text prepending works' ); @@ -204,10 +209,15 @@ test("prepend(String|Element|Array<Element>)", function() { expected = "Try them out:YahooThis link has class=\"blog\": Simon Willison's Weblog"; $('#sap').prepend([document.getElementById('first'), document.getElementById('yahoo')]); ok( expected == $('#sap').text(), "Check for prepending of array of elements" ); + + reset(); + expected = "Try them out:YahooThis link has class=\"blog\": Simon Willison's Weblog"; + $('#sap').prepend($("#first, #yahoo")); + ok( expected == $('#sap').text(), "Check for prepending of jQuery object" ); }); -test("before(String|Element|Array<Element>)", function() { - expect(3); +test("before(String|Element|Array<Element>|jQuery)", function() { + expect(4); var expected = 'This is a normal link: bugaYahoo'; $('#yahoo').before('buga'); ok( expected == $('#en').text(), 'Insert String before' ); @@ -221,10 +231,15 @@ test("before(String|Element|Array<Element>)", function() { expected = "This is a normal link: Try them out:diveintomarkYahoo"; $('#yahoo').before([document.getElementById('first'), document.getElementById('mark')]); ok( expected == $('#en').text(), "Insert array of elements before" ); + + reset(); + expected = "This is a normal link: Try them out:diveintomarkYahoo"; + $('#yahoo').before($("#first, #mark")); + ok( expected == $('#en').text(), "Insert jQuery before" ); }); -test("after(String|Element|Array<Element>)", function() { - expect(3); +test("after(String|Element|Array<Element>|jQuery)", function() { + expect(4); var expected = 'This is a normal link: Yahoobuga'; $('#yahoo').after('buga'); ok( expected == $('#en').text(), 'Insert String after' ); @@ -238,6 +253,11 @@ test("after(String|Element|Array<Element>)", function() { expected = "This is a normal link: YahooTry them out:diveintomark"; $('#yahoo').after([document.getElementById('first'), document.getElementById('mark')]); ok( expected == $('#en').text(), "Insert array of elements after" ); + + reset(); + expected = "This is a normal link: YahooTry them out:diveintomark"; + $('#yahoo').after($("#first, #mark")); + ok( expected == $('#en').text(), "Insert jQuery after" ); }); test("end()", function() { diff --git a/src/jquery/jquery.js b/src/jquery/jquery.js index 9840418..ebf9828 100644 --- a/src/jquery/jquery.js +++ b/src/jquery/jquery.js @@ -600,8 +600,8 @@ jQuery.fn = jQuery.prototype = { }, /** - * Append any number of elements to the inside of every matched elements, - * generated from the provided HTML. + * Append content to the inside of every matched element. + * * This operation is similar to doing an appendChild to all the * specified elements, adding them into the document. * @@ -609,40 +609,21 @@ jQuery.fn = jQuery.prototype = { * @before

I would like to say:

* @result

I would like to say: Hello

* - * @name append - * @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 similar to doing an appendChild to all the - * specified elements, adding them into the document. - * * @example $("p").append( $("#foo")[0] ); * @before

I would like to say:

Hello * @result

I would like to say: Hello

* - * @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

I would like to say:

Hello * @result

I would like to say: Hello

* * @name append * @type jQuery - * @param Array elems An array of elements, all of which will be appended. + * @param content Content to append to the target * @cat DOM/Manipulation + * @see prepend() + * @see before() + * @see after() */ append: function() { return this.domManip(arguments, true, 1, function(a){ @@ -651,94 +632,59 @@ jQuery.fn = jQuery.prototype = { }, /** - * 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. + * Prepend content to the inside of every matched element. + * + * This operation is the best way to insert elements + * inside, at the beginning, of all matched elements. * * @example $("p").prepend("Hello"); * @before

I would like to say:

* @result

HelloI would like to say:

* - * @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 - */ - - /** - * Prepend 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

I would like to say:

Hello * @result

HelloI would like to say:

- * - * @name prepend - * @type jQuery - * @param Element elem A DOM element that will be appended. - * @cat DOM/Manipulation - */ - - /** - * Prepend 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") ); * @before

I would like to say:

Hello * @result

HelloI would like to say:

* * @name prepend * @type jQuery - * @param Array elems An array of elements, all of which will be appended. + * @param content Content to prepend to the target. * @cat DOM/Manipulation + * @see append() + * @see before() + * @see after() */ prepend: function() { return this.domManip(arguments, true, -1, function(a){ this.insertBefore( a, this.firstChild ); }); }, - + /** - * Insert any number of dynamically generated elements before each of the - * matched elements. + * Insert content before each of the matched elements. * * @example $("p").before("Hello"); * @before

I would like to say:

* @result Hello

I would like to say:

* - * @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

I would like to say:

Hello * @result Hello

I would like to say:

* - * @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

I would like to say:

Hello * @result Hello

I would like to say:

* * @name before * @type jQuery - * @param Array elems An array of elements, all of which will be appended. + * @param content Content to insert before each target. * @cat DOM/Manipulation + * @see append() + * @see prepend() + * @see after() */ before: function() { return this.domManip(arguments, false, 1, function(a){ @@ -747,43 +693,27 @@ jQuery.fn = jQuery.prototype = { }, /** - * Insert any number of dynamically generated elements after each of the - * matched elements. + * Insert content after each of the matched elements. * * @example $("p").after("Hello"); * @before

I would like to say:

* @result

I would like to say:

Hello * - * @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 Hello

I would like to say:

* @result

I would like to say:

Hello * - * @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( $("b") ); * @before Hello

I would like to say:

* @result

I would like to say:

Hello * * @name after * @type jQuery - * @param Array elems An array of elements, all of which will be appended. + * @param content Content to insert after each target. * @cat DOM/Manipulation + * @see append() + * @see prepend() + * @see before() */ after: function() { return this.domManip(arguments, false, -1, function(a){ @@ -796,6 +726,8 @@ jQuery.fn = jQuery.prototype = { * back to its previous state. After an end operation, the list of matched elements will * revert to the last state of matched elements. * + * If there was no destructive operation before, an empty set is returned. + * * @example $("p").find("span").end(); * @before

Hello, how are you?

* @result $("p").find("span").end() == [

...

] -- 1.7.10.4