Wow, what an exciting first couple of days. Yesterday alone, we received about 100,000 page views and the responses were overwhelmingly positive. Amongst those responses, we’ve learned of a couple folks who are working on, or have created, some tools for the documentation. I want to throw out a couple of ideas here, and talk about how developers can make use of the docs. In addition to that, let’s find out what tools are already available to help you work with Prototype and JavaScript in general.

Atom to the rescue

One of the benefits of using Mephisto to power this site is the way in which it supports atom feeds. This opens the doors for some great uses of the documentation. Based on the comments we’ve received, some folks have already started on some tools.

You can get an atom feed for any section of the Prototype API docs. I’ve just added the official feed icon on the right side of the title for each object page. I have plans to get these pages in hAtom format as well, but that’ll come later on. In the meantime, you can get the feeds by clicking the feed icon next to the title. Feed URLs are also guessable. If you wanted to get the feed for Form.element, you’d have something like this:

http://prototypejs.org/feed/api/form/element/atom.xml

On to the tools

Ok, so what about those tools? There are a variety of tools available to help you become a more efficient Prototype and JavaScript developer. Here are some of the ones I’m aware of.

  • Quick API Search: One commenter whipped up a quick bookmarklet for quickly accessing pages within the documentation. You can get it by dragging this link to your bookmarks bar.

TextMate Plugins

  • Prototype Snippets and Language Grammar: Thomas Aylott is a TextMate machine! Grab his TextMate bundle here chocked full of stuff for Prototype. I also believe he’s working on a plugin for TextMate that would allow you to search the docs. Who knows what else he’ll throw in there. I’m sure it will be great once he gets it finished.

  • Lint Checking and Compression: Andrew has a nice plugin for lint checking and compressing your code (if you like that sort of thing). It’s a very handy tool that I abuse daily.

If you’re aware of other tools for Prototype, let me know and I’ll post them here.

Some ideas to ponder (or take action on)

There are a lot of things we can do with the documentation. Here are some of the things I’ve been thinking about.

  • Firefox search plugin
  • Firefox sidebar
  • TextMate tooltips and search
  • Integration with other editors (anyone know of something like this already?)

Technorati Profile

Comments

  1. Michael #

    Some nice work here. I’d love to see a firefox plugin and I think many others do aswell. As for integration with other editors I know Aptana has some, as far as code assistans goes, but I have no clue if it is up-to-date.

    keep more of this stuff coming! :D

    January 20th, 2007 @ 02:37 PM
  2. Aaron Bassett #

    The search one is pretty simple, and should work with FF as well as IE7

    I’ve created an example opensearch xml file (which uses google and the site operator to do the search) You can view it at: http://foobr.co.uk/opensearch_prototypejs.xml

    To make it available simply upload it to your server and then add: 
    <link href="http://prototypejs.org/opensearch_prototypejs.xml" title="Prototypejs.org site search" rel="search" type="application/opensearchdescription+xml" />
    within the head tag on your pages. When a user views the site they can then add it to their list of searches.
    January 20th, 2007 @ 02:41 PM
  3. Kroc Camen #

    Thanks for the tools guys, the TextMate JSLint plugin is useful. Suprisingly, out of about 20 js pages, only two had errors; I already write to a very high standard :D But it’s a life saver to have the results appear every time you save, so you can nip and slips in the bud right away.

    January 20th, 2007 @ 05:23 PM
  4. Thomas Aylott #

    Actually, I also just added Code Completion with and without a menu.

    It’s not too bright, but it works pretty well for me. It doesn’t do anything like parsing your document to know what methods your object supports or anything fancy like that, but it should be able to be extended for that kind of thing.

    Again, it’s all in the TextMate bundles. I might do a screencast or something eventually.

    January 20th, 2007 @ 05:52 PM
  5. Justin Palmer #

    Nice start Thomas.

    About your language bundle. I’ve been using the first one I put out some time ago because I’ve noticed you excluded one of the primary reasons I created it.

    You only highlight known methods in Prototype when creating classes/objects. It should highlight all object properties when an object is used as a storage mechanism for methods.

    e.g.

    
var Item = {
  methodHere: function() {

  }
}

    methodHere should be highlighted just like known Prototype methods.

    January 21st, 2007 @ 07:43 AM
  6. cmatech #

    Is it possible for us to download the documentation? Some of us don’t want to be dependent on a slow site for our information. Why can’t the documentation come with the prototype.js file? in a zip file or something?

    January 21st, 2007 @ 01:20 PM
  7. Thomas Aylott #

    Both the main Javascript syntax and the Prototype syntax need a lot more work.

    Actually, now that you mention it, I see the problem. It looks like my version is scoping library functions where it shouldn’t. Instead of excluding too much, I’m actually including stuff in the wrong place.

    EG: 
    
var Item = {
  methodHere: function() {},
  addClassName: function() {}
}
Item.addClassName();
Item.methodHere();

    Defining the method addClassName shouldn’t scope it the same as when calling that method. But this only affects method names that are in the list of support functions. Other methods defined in this way are scoped meta.function.

    I need to improve the syntax. I especially need to add all the new 1.5 stuff.

    January 21st, 2007 @ 01:23 PM
  8. Andrew Dupont #

    A while back I floated the possibility of dynamic ScriptDoc generation. The format is still young, but is (in my opinion) the most promising JS auto-doc system right now.

    I really ought to revisit my JavaScript Lint TextMate commands and add a few more shortcuts, like a command that will take you to the first reported error/warning (and show a tooltip explaining the error).

    January 21st, 2007 @ 06:09 PM
  9. Christoph Roeder #

    Is it possible for us to download the documentation?

    I’d really like to have a local copy (HTML-files) of the documentation too.

    Thanks for this great js-lib!

    January 22nd, 2007 @ 02:15 AM
  10. Aaron Bassett #

    cmatech & Christoph if you had been following the mailing list you’d know that Kjell Bublitz has already done some great work putting together .chm of the current documents: < a href=’http://www.m3nt0r.de/devel/Prototype.chm’ title=’Prototype help file’>download

    And cmatech I didn’t see you doing anything but whining. If you find the site slow and want some offline documentation why didn’t you go ahead and make some like Kjell? Oh thats right cause its easier to moan until someone else does it!

    January 22nd, 2007 @ 04:13 AM
  11. Thomas Aylott #

    Offline docs should be pretty easy, just use one of the billion apps out there to archive the website of offline browsing. It’s build right into IE6 (disclaimer: IE6 may eat your soul)

    January 22nd, 2007 @ 06:12 AM
  12. Jared #

    My favorite documentation viewer is

    http://start.gotapi.com/

    and integrating you current docs is easy,

    http://gotapi.com/contribute/index.html

    I cant wait until the new prototype docs are available here. This blazing fast doc search tool is irreplaceable!

    January 22nd, 2007 @ 07:22 AM
  13. Jack Sleight #

    Hi, Great work on the web site, it looks fantastic. Sorry if this is off the topic of this post, but I didn’t see anywhere better to ask:

    Are you considering making prototype available in it’s individual files (like mootools does), rather than one big file? Because it would be nice to be able to just include the bits you want to use, rather then the whole lot.

    I know those files used to be available in Subversion, but I cant find the HTTP link any more, and it would be good to know which files are dependant on which others.

    January 22nd, 2007 @ 01:57 PM
  14. Cody #

    If this is the main Prototype site, how come you do not offer a compressed version of the script on the download page?

    January 22nd, 2007 @ 02:49 PM
  15. rick #

    Jack: http://dev.rubyonrails.org/svn/rails/spinoffs/prototype/trunk/src/

    January 22nd, 2007 @ 04:43 PM
  16. Jack Sleight #

    rick: Thanks!

    To anyone who knows: It would be great to know what the dependencies are for each of the separate parts, otherwise its gonna be guess work I suppose.

    January 22nd, 2007 @ 05:34 PM
  17. cmatech #

    the squeaky wheel gets the grease. ;)

    January 22nd, 2007 @ 09:40 PM
  18. Thomas Fuchs #

    Jack Sleight: As you noticed the files are dependent on each other in many ways. Because Prototype is ~15KB when gzipped, I don’t think there is any (sane) reason for using only parts of it.

    January 23rd, 2007 @ 04:00 AM
  19. Andrew McMaster #

    This new site is awesome – really well put together documentation

    Bravo !!!

    January 23rd, 2007 @ 12:40 PM
  20. Grady Kuhnline #

    One thing I would strongly suggest adding to the documentation is the ability for users to comment. I personally find that user contributed comments add priceless value to documentation.

    Anyone who has ever used the fantastic PHP documentation knows exactly how much more value there is in the comments than the documentation itself.

    January 24th, 2007 @ 01:00 AM
  21. Kortina #

    This documentation is really useful. Two things on my wishlist:

    1. a show source button for each method so i can see what it does without going to the js

    2. a page listing all the functions and methods so i can easily scan them all, or a search function.

    Great work.

    January 24th, 2007 @ 01:21 PM
  22. Joe #

    Just posting to say that Prototype is an awesome library. I hated Javascript until I found Prototype. $() and bindAsEventListener are a lifesaver. The new features in 1.5 are great, and the documentation is useful as well. Thanks to everyone on the Prototype team.

    January 25th, 2007 @ 01:58 PM
  23. Bob #

    Wow, that was quick. Is that it for the blogging? Nothing for almost a week?

    January 26th, 2007 @ 02:14 PM
  24. Justin Palmer #

    @Bob: What were you expecting? Ajaxian? Techcrunch? BoingBoing? We all donate our time to this cause. If there isn’t anything newsworthy, there won’t be any news.

    We’ve been responding to comments, working on patches and improvements, and doing our day to day jobs that pay the bills.

    January 26th, 2007 @ 04:23 PM
  25. Kyle #

    I first tried prototype quite a while ago when there was very little documentation. Now that I want to use it again I’m very pleased to find loads of documentation!

    I believe it was also this site that told me about behaviour.js a while back, so I’d also like to thank you for that as well.

    But I have 1 question. I can’t get getDimensions, getHeight or getWidth to work properly in IE7. IE7 doesn’t error but the script doesn’t execute properly either. The old offset* methods work though.

    January 27th, 2007 @ 08:59 AM
  26. Bob #

    @Justin: You’re right, sorry about that. I’m conditioned to seeing updates continually via RSS, but that’s across a multitude of sites, versus any one site providing the same continual stream of content updates.

    January 27th, 2007 @ 04:19 PM
  27. Tobie Langel #

    Kyle: could you please file a proper bug report for the particular issue you have?

    I just double checked: all the tests pass in IE7. So I guess you must be using these methods in a specific situation we haven’t accounted for.

    Thanks.

    January 28th, 2007 @ 09:14 PM
  28. Kyle #

    Tobie: I think was I was mistaken in the uses for getDimensions() They are to get fixed heights from CSS right? I was trying to get the heights of non-fixed elements and assumed get*() was yet another of prototype’s cross-browser thingies.

    I do have a problem with remove() on tables though. Am I not using it properly or it is a bug?

    For example: element = A

    with contents I’m applying an effect to. element.parentNode = The element.parentNode.parentNode = The I want to remove after the effect.

    This works in FF: element.parentNode.parentNode.remove()

    It also appears to work in IE7 but throws an error and asks me if I want to debug, even though it appears like it has actually worked (there’s no DOM inspector for IE but visually the table row looks gone).

    This works in FF and IE7 and throws no errors in either: element.parentNode.parentNode.parentNode.removeChild(element.parentNode.parentNode)

    Is it me using it wrong or is remove() bugged?

    January 30th, 2007 @ 06:45 AM
  29. Kyle #

    Sorry! It didn’t escape less than and greater than.

    Tobie: I think was I was mistaken in the uses for getDimensions() They are to get fixed heights from CSS right? I was trying to get the heights of non-fixed elements and assumed get*() was yet another of prototype’s cross-browser thingies.

    I do have a problem with remove() on tables though. Am I not using it properly or it is a bug?

    For example: element = A div with contents I’m applying an effect to. element.parentNode = The td element.parentNode.parentNode = The tr I want to remove after the effect.

    This works in FF: element.parentNode.parentNode.remove()

    It also appears to work in IE7 but throws an error and asks me if I want to debug, even though it appears like it has actually worked (there’s no DOM inspector for IE but visually the table row looks gone).

    This works in FF and IE7 and throws no errors in either: element.parentNode.parentNode.parentNode.removeChild(element.parentNode.parentNode)

    Is it me using it wrong or is remove() bugged?

    January 30th, 2007 @ 06:47 AM
  30. Kyle #

    It’s still messed up. Some of my line breaks are missing but it makes enough sense.

    January 30th, 2007 @ 06:48 AM
  31. Tobie Langel #

    Hi Kyle,

    Have a look our tutorial How Prototype Extends the Dom. This should help clear your issues with Element.remove (and any other Element method) in IE.

    Maybe I’m still half asleep, but I’m not sure I understand what you meand by “getting the height of non-fixed elements”.

    January 30th, 2007 @ 09:22 AM
  32. Kniaź #

    I have accustommed to offline onepage html documentation by Sergio Pereira very much. I miss possibility of downloading such a document from this site very much:-(

    In spite of that, great work guys – thanks a lot :-)

    January 30th, 2007 @ 11:42 AM
  33. Marius Feraru #

    Firefox sidebar?! It’s available since day 1 ;-)

    January 31st, 2007 @ 02:31 PM
  34. Steve O #

    Regarding the above comments about gzipping the files, I recall reading about problems that IE6 (SP1 maybe?) has with decompressing/executing these files. Is this something to be worried about?

    January 31st, 2007 @ 06:50 PM
  35. Richard Quadling #

    I develop using Windows (I’m sorry, but the kit is supplied by the boss)

    Having a windows CHM help file for the documentation would be REALLY useful for me.

    I have the majority of my reference guides in CHM format.

    Alternatively, the OSoft ThoutReader application may also be of use as an alternative to this.

    Are the docs available as an archive? Or are they only held in the HTML that we see from the web page? If they are held outside of HTML (XML maybe???) then the docbook xsl could be used to convert this into any number of formats (HTML, CHM, PDF, etc). Not without some work though, but then you would have a common format for anyone who wants to take the docs and add them to there environment in any way they like.

    Regards,

    Richard Quadling.

    February 1st, 2007 @ 02:31 AM
  36. Andy Scherzinger #
    A Firefox search plugin should be pretty simple: 
    
<opensearchdescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<shortname>Prototypejs API</shortname>
<description>Prototype Javascript Framework - API search</description>
<image type="image/x-icon" height="16" width="16">http://www.prototypejs.org/favicon.ico</image><url template="http://prototypejs.org/api/{searchTerms}" type="text/html" method="get" />
</opensearchdescription>
    The example does not handle lower case conversion, unfortunately.

    Regards, Andy

    February 1st, 2007 @ 04:23 AM
  37. Piter #

    prototype is a great library! thanks to everybody who helped creating it!

    i had a few ideas for helping to improve the documentation: - as someone already said, an option to view the source of a function to obtain the gritty details of what a function does would be great.

    - something like the w3schools-site has, a try-it-youself demo window, with a few simple examples preprogrammed and a ‘run’ button. should be very easy with javascript, so you can immediately try out what works and what don’t in a console-type fashion.

    February 1st, 2007 @ 06:44 AM
  38. Nick #

    Hello guys!

    Thanks for your work. I have a question – is it possible to get the docs in the downloadable format?

    February 3rd, 2007 @ 06:40 AM
  39. Tobie Langel #

    Hi Nick,

    check out our latest post.

    February 3rd, 2007 @ 02:12 PM
  40. Mark Birbeck #

    I just created a toolbar for IE that allows you to go directly to a page in the Prototype documentation using a ‘search term’. It was built using XForms, and a tutorial on how it was done is here.

    The toolbar does everything you need with only one XForms control and one action handler, which means that there’s plenty of scope for adding additional features like a list of previous searches, and so on. I’ll also be adding a few other ‘applications’ that make use of the Atom data.

    I know that most people will be smugly using Firefox with Firebug. :) But if you do use IE…well, now you don’t have to be so envious, since you have a toolbar available if you want it.

    All the best,

    Mark

    PS I should add…great site!

    Mark Birbeck CEO x-port.net Ltd.

    February 4th, 2007 @ 09:29 PM
  41. Andrew #

    Page titles!

    It’s nigh impossible to find something on prototypejs.org with Google because of its lack of unique page titles on API and Tutorial pages.

    Seriously, check it out:

    Small fix with a big payoff :)

    February 6th, 2007 @ 11:20 AM
  42. Justin Palmer #

    Blasphemy! How could we have overlooked that one.

    February 13th, 2007 @ 06:58 PM
  43. Rich #

    Like it will matter or not, but I was playing around with Yahoo Pipes and created this simple search in the API.

    http://pipes.yahoo.com/pipes/mr6kBhG92xGwldGer8cPhQ/

    February 15th, 2007 @ 10:55 AM
  44. uli preuss #

    Extended Quick API Search Bookmarklet:

    
javascript:q = %22%22 + (window.getSelection ? window.getSelection() : document.getSelection ? document.getSelection() : document.selection.createRange().text); if (!q) q = prompt(%22Search Prototype API%22, %22%22); q = q.replace(/\./g, %22/%22).replace(/ $/, %22%22).toLowerCase(); if (q!=null) location=%22http://prototypejs.org/api/%22 + escape(q).replace(/ /g, %22+%22); void 0
    February 17th, 2007 @ 01:07 PM

Sorry, comments are closed for this article.

Search Blog


Search the prototype blog.

Subscribe to the blog

Categories

Akismet badge