Skip navigation

I think the prototype docs are too brief. Stupidly brief, in fact.

Don’t get me wrong. The docs are generally well formatted and pretty complete. But when it wastes more than a couple of minutes of my time to figure out how to use a specific function, its just a little too brief. Stupidly brief.

Its stupidly brief because someone who already knows how to use it won’t need to refer to it, and someone who doesn’t won’t be able to understand it very quickly without being confused. Stupidly brief.

Element.insert

Yes, yes they beat msdn hands down by using clever looking uri’s like http://prototypejs.org/api/element/insert. This is appreciated. BUT they LOSE to msdn in that this entry in particular is just not good enough.

An example please?

Sheesh.

How to use prototype insert

How to add to the dom using prototype.

The problem with the docs is they’re not mentioning that there’s two classes of functions. There’s the FUNCTIONAL/PROCEDURAL set of classes, then there’s the object oriented approach.

This brief example illustrates the difference.

// include prototype
<script type="text/javascript">

// oo way
// probably preferred way
function goOO()
{

  var newI = new Element( 'i' );
  newI.update('I am the new element');

  // We're inserting INTO the element that has id='paragraph1'
  $('paragraph1').insert ({
        
         'after'  :  // WHERE to insert it.  Can be:
// 'before', 'after', 'top' or 'bottom'
         newI      // this is the item TO insert.

  } ); // closing curly and round braces

// A bit more about 'before', 'after', 'top', 'bottom':
// 'before':  insert newI as the PREVIOUS SIBLING of paragraph1 in the DOM
// 'after':  insert newI as the NEXT SIBLING of paragraph1 in the DOM
// 'top':  insert newI as the FIRST CHILD of paragraph1
// 'bottom':  insert newI as the LAST CHILD of paragraph1


/*
so it goes kind of like this:

$(domref_element_to_insert_after).insert(
  {'INSTRUCTION' : DOMREF_of_stuff_to_insert}
)

Where 'INSTRUCTION' is 'before', 'after', 'top' or 'bottom'

its actually a brilliant api
and remarkably easy to use
with good results.

its a shame the docs SUCK!!

*/
}

// demonstrates how to insert into dom
// using prototype's Element.insert() function.
function goProcedural()
{
  var newI = new Element( 'i' );
  newI.update('I am the new element');

  Element.insert( $('paragraph2'), // element to insert after
   {'after':newI} ); // { 'instruction':__actual content to insert__ }
}
</script>

<body>
  <p id="paragraph1">this is the first paragraph</p>
  <p id="paragraph2">this is the second paragraph</p>

  <input type="button" onclick="goOO();"
  value="go OO insert after paragraph 1" />
  <input type="button" onclick="goProcedural();"
  value="go procedural insert after paragraph 2" />
</body>

Advertisements

56 Comments

    • Lee McMullen
    • Posted June 23, 2008 at 5:46 pm
    • Permalink

    Thanks for this, found it very useful!

    • rob
    • Posted July 9, 2008 at 12:09 pm
    • Permalink

    I totally agree and really appreciate for this clarification.

    In general the docs are ridiculous for the different JS frameworks compared to MSDN ;)

    • hal
    • Posted July 16, 2008 at 8:27 pm
    • Permalink

    Thanks for the blog post. You just saved me a ton of time!

    • johnarne
    • Posted July 18, 2008 at 12:36 pm
    • Permalink

    Thanks for your example. I see now that I’d misunderstood the API here, trying to do stuff like “$(‘el’).insert(”, {position: ‘after’});” which obviously did not work.

  1. Thanks. This post is useful for me.

    • Ace
    • Posted August 6, 2008 at 1:00 pm
    • Permalink

    THANK YOU! Can’t believe I spent just an hour trying to use it according to their specs, which I interpreted as:

    $(“targetElement”).insert(newContent, {position: “before”});

    • sistaA
    • Posted August 15, 2008 at 2:06 pm
    • Permalink

    Thanks a lot, I couldn’t agree with you more. I read the API and see tons of brilliant stuff I could use. But then I have to spend an enormous amount of time figuring out how, when one little example like your’s would clarify it in minute.

    • kaaposc
    • Posted August 20, 2008 at 7:48 am
    • Permalink

    well, thanks for this clarification, I misunderstood prototypejs docs, too. Maybe You could contribute a clear example to prototypejs docs?

    • Q
    • Posted August 28, 2008 at 8:57 pm
    • Permalink

    THANK YOU SO VERY MUCH! You saved me a lot of time.

  2. Thank’s a lot! I agree! The prototype docs really suck.

    • Shinta
    • Posted September 2, 2008 at 6:42 pm
    • Permalink

    I’m fairly new to Protoype. I am using Ajax.Request() to do a “live search” since Ajax.Updater() doesn’t play well with IE. I have two fields in my search page: first name and last name. The JSON response I get is an array of two users, {“Me”, “You”} (hardcoded at this time). So far so good.
    Then I parse the json response, and use Element.insert# to insert the result items into

    Here’s part of my js:
    jsonResponse.searchResult.each(function(item) { var newRow = ‘#{firstName}’;
    newRow = newRow.interpolate({firstName:item});
    $(‘resultSet’).insert({after:newRow});
    });

    When I ran my search the first time, it works. The page rendered the two users. But when I invoke the search again, it just rendered the two users, on top of the other users. So my page looks like:
    Me
    You
    Me
    You
    etc…

    I’m going crazy trying to figure this out. So any help is highly appreciated!

  3. Thanks for the clarification! I completely misinterpreted the docs to mean:

    parent_element.insert(child_element, {position: ‘after’});

    where parent_element is the element to insert into, and child_element is the element you are inserting.

    Thanks for clarifying, though I do think their syntax is a bit funky …

    parent_element.insert({‘after’: child_element});

    to read this, without reading the docs, I would think it means we are putting the parent element after the child element …

  4. Exactly what I needed to get running, thanks so much!!

    • Max
    • Posted September 17, 2008 at 11:21 pm
    • Permalink

    Need a post more? Here’s another THANK YOU for clarifying this method, much appreciated.

  5. Thanks so much for posting this. I was beating my head against the docs all morning.

  6. Just joining in the chorus. I have had more problems getting this miserable function to do what I want. If you want to add this to the official API, the world will be grateful. :-)

  7. i figured out how to move an object using this documentationless function and need to share, somewhere, so let it be here. this will move “Element1′ to after “element2”.

    element2.insert( {after:element1 } );

    cake… but not without good documentation >.<

    • Axel
    • Posted December 15, 2008 at 2:50 pm
    • Permalink

    God damn it…I was looking for a real example of how to use this function because the documentation is really useless for it !

    Thank you very much. You saved me time and also a screen because I was considering throwing it by the windows in a close future… =)

    This is really strange because usually, the prototype documentation is very good…

  8. I *REALLY* prefer the pre 1.6 methods of using prototype. The Insertion class was so much easier to use.

  9. Thanks a lot – saved me a couple of minutes at least…

    • Charles Buison
    • Posted January 27, 2009 at 9:26 am
    • Permalink

    Thanks Buddy

    • Erik Petersen
    • Posted January 31, 2009 at 7:48 pm
    • Permalink

    Holy cow!!

    Thanks a bunch!

    • Deepak Kaithwas
    • Posted February 10, 2009 at 12:59 pm
    • Permalink

    Thanks, this is such a very useful example to explain insert function.

  10. Thanks,
    I wasn’t sure about how to use this function either.

  11. Thanks a lot,

    introduction hit the nail a 100% :). Snippets are very helpful.

  12. Hello Guys,

    I´m from Brazil. Excuse me for my terrible english, but I was forced to thanks for this very useful post. And I agree… Why this must to be so dificult?

  13. $(‘You’}.thanks().for{
    doing => this;
    }

  14. Thanks a million. This is the only article I found clearly explaining the syntax for the insert() function.

    Cheers!

  15. Stupid Brief is right on point. The one thing that really bothers me about it. Thankfully, the code is fairly consistent about they format.. but still.
    This helped me a bunch. Thanks!

  16. thank you very much

    • Alexxandar
    • Posted May 17, 2009 at 1:39 pm
    • Permalink

    Thank you… I was bashing my head with this one.

    • sunil
    • Posted May 22, 2009 at 8:54 pm
    • Permalink

    awesome!

    • Larry
    • Posted June 4, 2009 at 7:01 pm
    • Permalink

    jeez, I never would have gotten that right from the documentation

  17. Thank you!! you saved me!

    • sam
    • Posted June 19, 2009 at 11:25 am
    • Permalink

    Totaly agree with you: stupidly, the official documentation should be insert( { top: ‘your comments’ } )
    ;)
    Anyway you’ve just save me a lot of time,
    Thank you

    • Rev2Red
    • Posted June 30, 2009 at 5:15 pm
    • Permalink

    I have a love hate relationship with prototype. If I can find a working example of what I want to do, I love it. If I can’t I hate it. Why? All because of their Stupidly brief documentation. Thanks for putting together a useful example.

    • RyanC
    • Posted June 30, 2009 at 9:49 pm
    • Permalink

    hallelujah!

    Any chance you have enough spare time to rewrite their documentation?

  18. Agreed with the rest, Prototype’s docs aren’t the best. Thanks for taking the time to do this.

    • J
    • Posted July 23, 2009 at 6:50 pm
    • Permalink

    Yeah I agree. I just spent 5 minutes trying to get this to work after looking at the docs. Then hit google and found this.

  19. You hit the nail on the head when it comes to the Prototype documentation… I think it would be useful if they created a wiki so that others could contribute. Thanks for this example though… it’s exactly what I have been trying to figure out all day.

  20. Me too, i was doing this;-

    $(”targetElement”).insert(newContent, {position: “before”});

    Perhaps since so many people think this it is more than brief, it is wrong and being consistently misunderstood.

  21. Weird, I understood it the way commenters had, also.

    The doc sucks. Very much. You’d think they would have at least fixed the doc for this very important method before today. Isn’t Prototype the grandpa of JavaScript libraries?

    Aggravating.

    • Mydde
    • Posted September 8, 2009 at 3:56 pm
    • Permalink

    Doing this in IE8 wont work :
    $(element).insert(top:’my comments’).
    For me, it will insert it at the top of the body.But this work in firefox, opera, ie7 … any ideas ?

    • Dan
    • Posted December 25, 2009 at 3:56 am
    • Permalink

    Thank you. Very clear example that explains functionality and terminology precisely and concisely … unlike the ones in the API docs

    • Sathesh
    • Posted December 31, 2009 at 5:20 am
    • Permalink

    thanks dude, I felt the same i.e. their docs are stupidly brief..

    • Hills
    • Posted January 17, 2010 at 1:12 am
    • Permalink

    Thanks mate! Exactly what I needed!

  22. Hello everybody !

    I always got the same problem …

    Doing this in IE8 wont work :
    $(element).insert(‘top’:’my comments’).
    For me, it will insert it at the top of the body.But this work in firefox, opera, ie7 … any ideas please ?

  23. Sorry,
    should have write :
    $(element).insert(‘before’:’my comments’).

    • tom
    • Posted March 7, 2010 at 9:32 pm
    • Permalink

    A-Freakin-Men!!

    It is unfortunate that the biggest problem in using Prototype is the crappy documentation, and worse, that it seems to be the result of conscious decision.

    • Fermin
    • Posted March 9, 2010 at 9:39 pm
    • Permalink

    You have to change this comment:
    // We’re inserting INTO the element that has id=’paragraph1′

    Because we’re not inserting INTO, we’re inserting actually besides of ‘paragraph1’

  24. Worked great!!! thank you so much for this blog post.. You’re right – its a great library, but the new docs SUCK.

  25. Thanks for this clarification!

    I love Prototype, but some of there explanations for methods and functions leaves much to be desired.

    I don’t expect volumes of examples…. but something more explanatory than:

    “To us a function, simply use it.”

    I know, I made that one up, but sometimes it feels like their explanations are not much better.

    (8)-)

    exoboy

    • gearz
    • Posted October 22, 2010 at 6:41 pm
    • Permalink

    Stupidly brief. Yes, very good.

    Also, have you considered submitting this to the folks at Prototype? They do take submissions.

    Cheers!

  26. thank you, thank you, thank you.
    and yes, ‘stupidly brief’!!!!!!
    so, so true. ^_^

    • Martin
    • Posted June 15, 2012 at 10:43 pm
    • Permalink

    Hi How can I get all the elements after I insert it. example : var d = new Element(‘div’,{id:’d1′});
    var txt = new Element(‘input’,{type:’text’,id:’txt1′});
    var rad = new Element(‘input’, {type:’radio’,id:’rad1′});
    var btt = new Element(‘button’ {id:’b1′})

    d.insert(‘before’ : txt); d.insert(‘before’,rad);

    btt.observe(‘click’, function (event){
    getMyElement(event,’d1′) // I pass d1 is div id to this function in order to get all the elements in this div. How do I get all the elements with its values out and how I can remove these elements from the div.
    });

  27. This is 2013 (actually, it’s almost 2014) and the Prototype docs are still as short and cryptic as ever. Incredible!

    It’s really annoying having to search the internet for how to correctly use practically every method I read about in the docs. Take “invoke()” for instance. Great method but why is there no mention in the docs of how to use it with user defined functions? (Google “using prototype invoke with a user defined function” and read the first link.)

    I actually prefer using Prototype to the far more popular jQuery but IMO the docs need a total revamp! (Some videos would be nice.)


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: