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>