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.
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>
Bobobobo's Weblog 
56 Comments
Thanks for this, found it very useful!
I totally agree and really appreciate for this clarification.
In general the docs are ridiculous for the different JS frameworks compared to MSDN ;)
Thanks for the blog post. You just saved me a ton of time!
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.
Thanks. This post is useful for me.
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”});
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.
well, thanks for this clarification, I misunderstood prototypejs docs, too. Maybe You could contribute a clear example to prototypejs docs?
THANK YOU SO VERY MUCH! You saved me a lot of time.
Thank’s a lot! I agree! The prototype docs really suck.
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!
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 …
Exactly what I needed to get running, thanks so much!!
Need a post more? Here’s another THANK YOU for clarifying this method, much appreciated.
Thanks so much for posting this. I was beating my head against the docs all morning.
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. :-)
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 >.<
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…
I *REALLY* prefer the pre 1.6 methods of using prototype. The Insertion class was so much easier to use.
Thanks a lot – saved me a couple of minutes at least…
Thanks Buddy
Holy cow!!
Thanks a bunch!
Thanks, this is such a very useful example to explain insert function.
Thanks,
I wasn’t sure about how to use this function either.
Thanks a lot,
introduction hit the nail a 100% :). Snippets are very helpful.
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?
$(‘You’}.thanks().for{
doing => this;
}
Thanks a million. This is the only article I found clearly explaining the syntax for the insert() function.
Cheers!
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!
thank you very much
Thank you… I was bashing my head with this one.
awesome!
jeez, I never would have gotten that right from the documentation
Thank you!! you saved me!
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
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.
hallelujah!
Any chance you have enough spare time to rewrite their documentation?
Agreed with the rest, Prototype’s docs aren’t the best. Thanks for taking the time to do this.
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.
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.
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.
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.
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 ?
Thank you. Very clear example that explains functionality and terminology precisely and concisely … unlike the ones in the API docs
thanks dude, I felt the same i.e. their docs are stupidly brief..
Thanks mate! Exactly what I needed!
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 ?
Sorry,
should have write :
$(element).insert(‘before’:’my comments’).
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.
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’
Worked great!!! thank you so much for this blog post.. You’re right – its a great library, but the new docs SUCK.
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
Stupidly brief. Yes, very good.
Also, have you considered submitting this to the folks at Prototype? They do take submissions.
Cheers!
thank you, thank you, thank you.
and yes, ‘stupidly brief’!!!!!!
so, so true. ^_^
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.
});
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.)