Modules

AMD stands for “Asynchronous Module Definition”. So, what are modules? I’ll quote the definition from the CommonJS Module specification, as it describes it very well:

This specification addresses how modules should be written in order to be interoperable among a class of module systems that can be both client and server side, secure or insecure, implemented today or supported by future systems with syntax extensions. These modules are offered privacy of their top scope, facility for importing singleton objects from other modules, and exporting their own API.

So, modules are isolated parts of code that live in their own scope and are kind of self-contained. Well, that is pretty much how we see the individual Features in EmbedJS – we made our feature implementations as small as possible and reduced dependencies as much as possible. Many of EmbedJS’ features are also browser-independent, so why not make it possible to use some of the tools in a non-browser environment?

(If you want to learn more on modules and why we need them, I recommend @briancavalier‘s presentation on modules.)

Features in EmbedJS

So far, I didn’t really explain what I mean with “Features”, so let me do another quote, this time from the Project Page:

EmbedJS uses the concept of features: Functionalities are split up into features, as fine-grained as possible, and each feature might have multiple implementations.

Our Features are kinda small and contain only few methods, sometimes even just one. The asyc-promise feature, for example, will get you Promises, and the transport-jsonp feature will get you a method for pull in data via jsonp – and that’s it.  If multiple methods are contained within one feature, this is because they are too closely related to each other to split them up, like the html-class feature, which contains the addClass, removeClass, toggleClass and hasClass methods.

AMD vs CommonJS Modules 1.1

Now that we knew modules were the way to go, there was another, quite important question to solve: There are two common patterns for modules, so which one do we want to apply? One pattern is described in the above mentioned CommonJS Wiki, the other pattern is described in the AMD wiki.

Well, there have been some blog posts lately that compare the pros and cons of each of them, so I don’t want to repeat all of this – but I’m hiving a similar tendency towards AMD. Besides this, there was another big reason to go with AMD: Remember, EmbedJS is based on the Dojo Toolkit, and it’s a Dojo Foundation Project – and we hope that the efforts that went into making EmbedJS might flow back into the Dojo Toolkit one day. And as the Dojo Toolkit uses the AMD approach, the decision was quickly made to do so as well.

Implications for EmbedJS

There are several huge benefits for EmbedJS in using the AMD approach. The most noteworthy surely is the ease-of-use for developers. In your code, when you find you want an EmbedJS method, you look up the feature name that provides this method, add it to the require statement and there you go. Man, easy.

A second important thing is that EmbedJS now plays really nice with AMD based projects. In fact, you could see EmbedJS now as a collection of small useful modules, that can be easily integrated – and also easily extended.

The third major benefit is that we can now get rid of all the custom tools we built around EmbedJS – you can load features with any AMD loader (though we use and recommend RequireJS) and build it with any AMD optimizer/builder (we recommend r.js).

Let’s have an extra word on

Building

It was always possible with EmbedJS to create a custom build that would contain only the features you wanted/needed in your project. But, you had to use our build tool that we created. And learning & using Yet-Another-Build-Tool™ is always… well, let’s just say it would be cool to avoid it (and, not to forget, so is maintaining it). We did a lot to improve that, we created a GUI that allowed you to just “click together” the features you wanted, and we worked on a dynamic loader that would ease development. But still, the situation was far from ideal, and people just ended up going for our ready-made “kitchensink” builds that contained all of the features.

Now, we still provide those ready-made builds that contain only the implementations for a given platform (and are stripped of require/define calls), but I really hope that using the AMD approach and using an AMD optimizer to deploy will become the more adopted style.

Q: Cross-target? A: The Feature Plugin

One goal of EmbedJS is to allow for easy cross-device development. We got rid of run-time branching but instead went for an approach that held the different implementations for a given feature in separate files, so that one only has to deploy the actually needed code to a given device – and not all the alternate implementations, that sit useless in the device’s memory and never get used. We needed to achieve that with “in-house” means provided by the AMD approach. Lucky us, there’s the concept of loader-plugins, and so I created a feature-plugin for AMD loaders. The idea is simple yet effective: You create an implementation map that maps a feature name to an implementation, and if there are multiple implementations, you supply tests that tells the plugin which feature to use.

When you’re ready to deploy, you have two choices: I f you really don’t know on what target your code is going to end up, you can use the dynamic implementation map containing the tests for the optimizer, and you’ll get a build that contains all of the available implementations. Then, during runtime, the feature plugin will run the tests and load the specific implementation. But, if you do know what target your code will run on, you provide a specific implementation map that doesn’t contain tests but directly maps to the according implementations, and you will only have those in your built file.

Synopsis

AMD is exactly what we needed to make EmbedJS more what we want it to be – an easy to use JavaScript toolbox that is especially handy for cross-target scenarios such as cross-platform mobile development. So, please don’t hesitate and check it out on Github, read the project page and check out the examples!

Resources / Further Reading

• EmbedJS on GitHub
• EmbedJS Project Page
• EmbedJS API Docs
• AMD-Feature plugin
• AMD Wiki
• CommonJS Wiki

Dojo also comes with two fresh implementations for the API, a non-persistent memory store and a JsonRest store that interacts with a server through RESTful HTTP requests. You can also observe changes made to objects in the store. What is missing is a store that uses a client-side persistent backend, which would be useful for a couple of reasons (e.g., as one commenter in that post asks, to use it as chache store for dojo.store.Cache). As Kris already mentions, it’s a piece of cake to create one, so let’s go ahead and do it!

Choosing the Backend

The post mentions two possible candidates: dojox.storage and StorageJS, both already having a similar API, so making them compliant to the Dojo Object Store API is fairly easy. For this tutorial I choose StorageJS – because it is very lightweight and still provides all we need (and, well, for a couple of other reasons that don’t belong in this post). So, what is the exact API we need to comply to? Check it out in the docs. See the first sentence in that paragraph? “Every method in the API is optional, it’s presence indicating support for that feature.” Wow, that’s nice!

Basic compliance

Let’s start with the methods get(), put(), add() and remove(). That will make our store pretty usable for most store scenarios.

First, create a ‘store’ object we can work with (StorageJS creates a global variable called storage where all it’s methods reside):

‘store’ now contains everything that ‘storage’ does, but we can leave the original ‘storage’ object alone and modify our ‘store’ object if needed. Time for the first method, let’s start with get(). StorageJS works with Strings as keys and values only, so we need to parse what we get from it.

Easy one, now move on to put(). The Object Store API allows user to do stuff like this: store.put({foo: 'bar'}, {id: 3}) as well as store.put({id: 3, foo: 'bar'}). Also, StorageJS only has the method set() instead of put() and add().

Easy, as well – you could write this as a one-liner. Now, add(). It’s close to put, except that it won’t overwrite data that already exists. So we just need to check if something with the given id already exists and throw an error if so.

What about remove()? Nothing to do there, it already has the desired signature and functionality.

That’s it, we’re done with basic compliance. Our ‘store’ object now implements the basic methods of the Dojo Object Store API and can be used by anything that can work with a Dojo Object Store – and it will keep it’s state persistent in the browser.

More compliance? Querying!

There’s one interesting thing in the API: the query() method. Uh, yeah, we want that! Lucky us, Dojo already provides a query engine as well as a method that makes sure there are iterative methods and a total property containing the number of hits available in our result (well, it also abstracts away the differences between sync and async results, but as StorageJS is purely synchronous, this is not important to us). First, define a queryEngine:

So, if we want our store to be able to run queries, all we need to do is to take the store’s data and hand it over to the query engine. We use StorageJS’ getAll() method to acquire the data. It will return an array of objects in the form { key: ‘theKey’, value: ‘theValue’}, but the queryEngine wants an array containing only the objects, so we need to do a conversion.

Now we can query our store for specific data, like so: var results = store.query({ prime: true }); This will give us all objects in the store that have a property called ‘prime’ and have that property set to true.

Hierarchie and Transactions

The API also mentions methods about data hierarchie and transactions, but I’m not going to cover these in this tutorial.

Convenience and Optimization

Currently, every time we run a query, we fetch all data again from our storage engine. So, if you don’t have a massive amount of data and want to query the store a lot, it might be wise to maintain a copy of all data in memory. There are other things you could optimize as well – or you could write your own queryEngine.

For your convenience,  here’s a wrapper that creates a Dojo Object Store like we did above and accepts a useMemory parameter during instantiation that denotes whether a copy of the data should be kept in memory or not. It uses the traditional require/provide instead of the AMD format. If you want to use it, make sure you use the right namespace in the declare() call! (Or, not recommended, copy it in the /dojo/store directory.)

If you want to fool around with it in the console first, you can go here (non-memory-using) or here (memory-using), check out the source and fire up the console and try things out.

Getting StorageJS

The above code uses the features base and getAll, so you could do a specific build of StorageJS with these features or just grab a full build of it for your desired storage engine (the storage-full-[engine].js files). If you don’t know about storage engines, all modern browser support localStorage, so this is the one what you might want.

What is it?

It‘s a JavaScript Toolkit, especially aimed at embedded devices. Embedded devices, that is phones, tablet devices, TVs, car dashboards and the like. Devices that are capable of running JavaScript. We are sure that this list is going to grow over time – and will hopefully one day also include devices like your fridge. EmbedJS is based on the Dojo Toolkit.

Why?

Because the toolkits and frameworks that exist focus on desktop browsers and therefore have a different approach – an approach we didn‘t find that suitable for embedded/mobile development. And the JS frameworks that target mobile devices are flawed, too: either they target only a specific device or platform, or they provide far more than we do need and want.

What we wanted was a toolkit that offered a unified API across different platforms, but with the best implementation that was available for each platform. And we didn‘t want to ship code that implemented a certain feature for, say, an old Blackberry device to an iPhone. Plus, we wanted that API to be small – enough to assist us in our daily work, but not that bloated that we would ship code to a phone that we wouldn‘t need in most of our projects.

The Dojo Toolkit

We at uxebu have a strong affinity to the Dojo Toolkit – most of us are committers – for a good reason: we believe that it has done many things right, and that it has an excellent code quality. Thus, finding a starting point for our venture to what was later to be EmbedJS was pretty easy: It was the very core of the Dojo Toolkit, dojo._base.

We examined the code and split it into its smallest parts (features, how we call them in EmbedJS). After having the features all nicely separated, we could look for the best implementation for each of the platforms we wanted to support, and put it into a separate file. Then we optimized our code, tweaking here and there, but also using the code from dojo._base as it was, because it already was the best implementation.

And we needed to find means to put all these tiny parts together again, respecting any given dependecies, to create a file that then contained all the feature‘s implementations for a given platform – so the EmbedJS Tools were born, including our highly flexible build system.

API

EmbedJS‘ API is a small subset on Dojo‘s API. It provides around 70 methods, from the fields language enhancement (like Array manipulation or JSON), OO (like classes and inheritance), transport (like JSONP or XHR), event system (like connecting to DOM events or methods), DOM manipulation (like style or node creation) and misc things like Promises or pub/sub.

We kept the method signatures intact so that you can import your existing knowledge from working with the Dojo Toolkit to EmbedJS. There are only a few minor changes where we
a) found a new name highly useful, e.g dojo.io.script.get() is embed.jsonp()
b) we needed to strip given functionality for the sake of code size.

All methods in EmbedJS are available under the embed namespace as well as under the dojo namespace. I.e. to call the connect method you can use dojo.connect() and embed.connect().

The full API documentations is here, though it‘s undergoing some updates right now.

Summary

I didn‘t want to dig too deep in the first article on EmbedJS, but I guess you got the point: EmbedJS is a highly optimized Dojo core, and offers you a specialized, optimal build for a given platform. To explain how the build system works, how we manage dependencies, how we separate our features and our implementations and how one can create a project-oriented custom build will need another blog post – but if you are too curious, you are invited to take a look at the source code at github; a lot is self-explenatory there. A further source of information is the EmbedJS project page, as well as the EmbedJS Tools source.

The day started as planned with coffee and snacks and a Dojo introduction giving everybody who wasn’t really familiar with the Dojo Toolkit a better idea of what it actually is. A few demos such as xRay where shown to show some of the advanced features of Dojo such as live charting, custom themeing and much more.
After a short break we continued with a talk on how to design mobile architectures with the Dojo Toolkit for platforms such as PhoneGap, W3C widgets and other mobile platforms supporting JavaScript/HTML and CSS. This is a very interesting topic and it was great to share the experience we made at uxebu on finding viable solutions for the challenges we face. The third talk was a quick overview of the current documentation efforts for Dojo and different ways of finding the information you need when you are stuck or simply looking for API docs or similar.
Before the break, Tomer Mahlin from IBM in Jerusalem, who is working on the BIDI implementation in Dojo, gave a very interesting talk on the challenges, developers face when writing applications supporting BIDI. Not having to deal with the issues you get confronted with when having to develop BIDI applications, this talk was eye opening and very interesting.
After a great lunch we jumped into a hands on session building a very simple mobile app running on both PhoneGap and devices with a widget runtime supporting W3C widgets installed. This gave the audience a glimpse into mobile development and the challenges but also really exciting features.

In total there were about 45 people attending the event which is an amazing amount of people for such a first time event, thanks again to everyone attending and especially to Yoav Rubin and the folks at IBM to make this happen.

I am already looking forward to the next Dojo event in Israel and hope that we can be part of it again.

Following are the slides to give you a little impression of the events content.

Following some more details for the event. You can find all info also at the DojoCampus.org event page and things are still subject to change.

Location:

IBM Haifa Research Lab
Haifa University Campus

Google map

Time:

09:30 – 15:00

Schedule

09:30 – 10:00 – Gathering

10:00 – 10:15 – Welcome and introduction

10:15 – 10:45 – Overview of Dojo Dijit and Dojox

11:00 – 12:00 – Dojo and Mobile

12:00 – 12:30 – Dojo based JavaScript API Docs generator

12:30 – 13:00 – Hacking mobile (this session might be extended)

13:00 – 14:00 – Lunch

14:10 – 14:30 – Support for bidirectional languages in Dojo

14:30 – 15:00 – Projects demonstration

If you want to give a talk about your experience with Dojo or anything Web related, leave a comment at the DojoCampus.org event page or send an email to nonken(_at_) dojotoolkit.org and we’ll make sure you get added to the schedule.

After the main event we will either continue hacking or go for food/drinks/dojo.beers() into town.

If you would like to attend, please add your name to the list below, so we can be sure that we will have enough space.

Looking forward to being in Haifa and meeting lots of Dojo, web, JavaScript folks.

Enjoy the short video we prepared to give you an impression of what EventNinja can do

EventNinja in Action

The EventNinja widget contains multiple pages, as you are used to from mobile applications. The home page shows all the events, allows you to search and filter them. Along the top bar you have the search bar, the “Help” and the “About” pages linked.
Clicking on the icon to the right of each event takes you to the details page of the event, from where you can go to multiple other places, like the map, to see where it exactly takes place, the schedule of the event. If the event has twitter tags saved for it can go to a page which shows you all the latest twitter messages flying in. Try it on EventNinja.net and explore the features.

EventNinja Features

User Features

• List of web developer events
• Searchable and filterable by tags, location and full-text search
• Exact location of the event
• Watch all twitter messages for each event
• Find out about details of an event

Technology Features

• Events are stored, retrieved and filtered by a Google Calendar
• Everything built on top of the Dojo Toolkit
• pure HTML, CSS, JavaScript based widget
• using PhoneGap to run on iPhone, Android and Blackberry
• Plugin architecture, allows for a modular enhancement of the widget
• Fully customizable via client-side templates and CSS of course

As you figure right from the list of features and cleverly combining them we can hook this widget onto any calendar, customize the features (via plugins), style and brand it the way we like it and have your custom widget.

This gives customization a far broader meaning. Just imagine combining the two components 1) base of the widget and 2) the twitter plugin. You get a widget which shows you all tweets for a certain event -that’s just a new widget itself, without writing a line of new code. Which again is a very different use case, than the widget you get here. Just hook in another plugin which allows replying via twitter and you get a full blown twitter client in the context of events.
The limits of what is thinkable is just limited by the plugins you can write.

EventNinja for the mobile2.0 Conference

Mobile2.0 is the first conference where you can really use EventNinja to get all the info possible, the schedule, twitter messages, etc. There surely will follow many more conferences and events that EventNinja can and will be used at. See the screenshots below to get a feeling of what it looks like for this conference.

Are events missing?

EventNinja for webdevelopers is driven by the great amount of community events.
If you see that events are missing, please contact us and we will add them immediately. If you organize events yourself let us know as well. You can send any kind of info about the event, e.g. name, location, tags, speakers, twitter tags, schedule details, price, and much more.

You want an EventNinja?

Send an email to eventninja _ at _ uxebu.com if you are interested in a customized version of EventNinja, are interested in the technology or simply want to chat. At the mobile2.0 conference you will recognize us easily when you look for the guys with those caps, hurry, because we are spreading caps and maybe there will be many more wearing this cap :-).

Taking this as an opportunity we want to announce the next dojo.beer() in Barcelona on June 17th.
You can get all info about the event on the DojoCampus event site.

The day after, we are speaking at the Mobile2.0 developer day and will give a detailed introduction in how to write mobile applications using the Dojo Toolkit and making sure they are running on different platforms such as PhoneGap and the W3C widgets being supported by Vodafone.

If you are in Barcelona that week, feel free to get in touch and if you have time to join for drinks during the dojo.beer or the mobile 2.0 conference let us know. Please sign up using the poll below.

Para los españoles :-)

Como Wolfram ha escrito en su último artículo de blog, nosotros estamos muy involucrados en el mundo de los móviles y estamos especialmente investigando como desarollar de la mejor manera para dispositivos móviles con Dojo.

Aprovechamos esta oportunidad para anunciar el próximo dojo.beer() en Barcelona el 17 de junio de 2009.
Puedes encontrar toda la información en inglés sobre el evento en la página de eventos de DojoCampus.

Al día siguiente vamos a dar una ponencia en el Mobile2.0 developer day y vamos a explicar como escribir aplicaciones moviles usando el Dojo Toolit y como asegurarse de que funcionan en múltiples plataformas como PhoneGap y como W3C Widget apoyado por Vodafone entre otros.

Si estás en Barcelona durante esa semana y te apetece contactar con nosotros no dudes en venir a tomar una copa al dojo.beer o a la conferencia mobile2.0. Por favor participa en el poll abajo si quieres ir.

SitePen and uxebu are pleased to announce their first joint Dojo workshop in Munich, Germany. Come join some of the co-creators of Dojo on the 7th and 8th of May, 2009 to learn how to build great web sites and applications with Dojo.

This new workshop will be an engaging experience for anyone wanting to learn more about Dojo!

Dojo has an incredible set of features—from the essential tools to build AJAXy Web2.0 applications, to a rich set of widgets, layout components and to “edge of the web” extensions, Dojo has you covered. If you or your team members are already using Dojo, this workshop can help you strengthen your skills and also learn about the latest tricks and tips around JavaScript and Dojo in particular. Raise your productivity by learning techniques to optimize applications and learn best practices for the development process by better knowing your tool set.

Course Description

Ajax and Web 2.0 development are easy to learn but take significant effort to master. This workshop accelerates the process by teaching you the essential knowledge and best practices needed to quickly become more productive with Dojo, the most widely used Ajax toolkit in enterprise application development.

Day 1, May 7, 2009

• Kickoff
  • Course overview, getting set.
  • Getting comfortable with the development environment,
    tools including FireBug to do efficient Dojo development
  • Dojo core/base in depth: all the essentials for any web
    application or web site
• Building applications the Dojo way
  • How do I structure my Dojo app?
  • Code architecture
  • Taking some shortcuts using functional approaches, AOP and other
    modern techniques.
• Improving the User Experience with Dijit
  • dojo.fx, Dojo’s on-board effects system
  • Using Dijit
  • Customizing and styling existing widgets
  • Creating a custom widget using the DTL template language
• Applied Dojo
  • Hands-on session to apply the lessons learned in Day 1 to start
    building an application

Day 2, May 8, 2009

• Creating your own Dijit
  • Understanding the widget system in depth
  • Creating a new Dijit
  • Creating a Dijit theme
• Real-time Dojo
  • Grids, Charts and dojo.data
  • How to use cometD
• Optimization
  • Verify your functionality using DOH testing
  • Getting the application into production – the Dojo build system
  • Profiling, Analyzing and Optimization of your application
• Applied Dojo
  • Hands on session to create an application based on the lessons
    learned in this workshop

Though 16 hours is not enough time to cover every feature, we will show you the features that help you get the most out of Dojo and make you immediately productive with Dojo. At the end of the course, armed with your knowledge of the core Dojo features and many of the extras, you’ll know how to best leverage Dojo in your project. Throughout the workshop you will be guided through best practices and approaches for using Dojo, gaining insight from the SitePen and uxebu teams’ years of building web apps and creating the Dojo Toolkit.

By the end of this comprehensive workshop, you will know:

• How to set up a Dojo application and use the Dojo Toolkit
  efficiently
• The Core Dojo APIs and proper selection of APIs essential to
  development goals
• How to debug your source code and optimize application
  performance
• Secrets of expert developers in pragmatic and effective
  Dojo-based web development

Bonus

All attendees will receive a copy of Dojo: The Definitive Guide. Additionally, if you stick around for another day, and join us for the next free dojo.beer() on May 9th, 2009, this time with two special guests (guess who). A separate announcement will be made later with more details.

About the Instructors

You will get an excellent set of instructors for this event: Pete Higgins (Dojo Project Lead), Dylan Schiemann (co-founder of Dojo and SitePen), Nikolai Onken (co-founder of uxebu, Dojo community evangelist, and Dojo widget themes and CSS maestro), Tobias von Klipstein and Wolfram Kriesing (both co-founders of uxebu).

Sign-up

If you want to sign-up for the Dojo course, please send an email to workshop ( at ) uxebu.com and we will send you more information.

Fast forwarding … what came out of it is the API docs viewer which, we here at uxebu, built over the christmas holidays. It is completely client-based, for creating the documentation and retreiving all the information, no server-side code is needed anymore, it’s all done in dojo.

If you want to see a detailed introductional video, sit back, relax and enjoy the following screencast:

Inline doc styles

There are a couple of JavaScript inline documentation tools and styles out there, but no real standard has evolved yet. Maybe because of JavaScript’s dynamic nature it’s hard to fix it to just one style. Though this just makes the task more interesting, actually.

Let’s take a step back and take a look at just three of the various different inline doc styles.

The jQuery way, pretty much textual.

The YUI way, as you will see it’s very JavaDoc like, the method is documented above the actual definition and uses the @ sign for identifiers.

The dojo way, with proprietary identifiers, inside the function code!

We see that there are different levels of depth and explicitness in the inline comments. But they all have in common, that important and interesting information are contained inside the source code, that should be exposed to the users of those APIs.

The __doc__ approach

In python, a certain type of comments is available as the docstring property __doc__ of the function it is in. This was actually the initial idea, to provide the docs in this kind of way:

It’s is pretty obvious, that this is is pretty ugly source code in the first place and secondly a comment is not a comment anymore but becomes source code. Prone to errors, and not really leading to higher productivity, we realized that this approach was actually just a learning stage.
Still it is pretty handy to use the command line in FireBug and have the docs at hand via autocompletion e.g. just typing dojo.trim.__doc__ and the docs are there (this feature is currently also implemented, but the __doc__ property must be generated by a function call afterwards and it is not in the main focus for the current state of the project).

The less disruptive approach

Since the __doc__ approach has the ugly side effect that library authors would have to change all their source code it was dismissed pretty quickly. New ways had to be explored. Driven by the flexibility of JavaScript and it’s dynamic nature we found a nice mix of reflection and minimal file parsing that allows us to extract the information from the existing raw (unpacked and not minified!) source code, without the need to modify it upfront.

First comes the reflection. Using the simple for-in loop over the prototype and the object itself allows us to extract all the methods and properties. Applying a little bit of logic using toString() and alikes and we know if the implementation of this object overrides, inherites or creates this method, we find out the default value of properties and a lot more. In the special case of dojo we can also easily find out the parent class(es). The reflection is actually worth a separate article, since it is quite powerful and allows deep insights into a class’s inner values.

Second step is simple file parsing. Since we know that object “foo” has the method “bar”, we know that in the source code we can find the definition by looking for the following patterns:

There are a couple of special but rare other cases, but the patterns are very simple to detect as you can see. So our FileParser doesn’t really need to understand the JavaScript syntax, it is just looking for exact patterns and is therefore quite fast (we can surely still improve on the performance!).
Using regular expressions we also find out the parameters and the actual docstring itself, which then is parsed by the DocStringParser.

Let’s summarize. We have an object’s/class’s (if you want to call it a class) methods, properties, their according docstring and the docstrings of the class itself. We know the inheritance structure, can determine the type (public, private, etc.) from the name (for now we assume it is private when it starts with an “_”) or soon we will use the docstring identifier “tags” (which was just shortly introduced into dojo as you can see it used here). And we have example code, which is contained in a lot of docstrings. So this is already quite an amount of useful data. Let’s make them useable.

Plugging it all together

The pieces are there, they just need to be plugged together and hopefully a useful API docs viewer will arise. For this special dojo use case, we also had to build a mapper which enables the mapping of a namespace to the correct file(s). E.g. dojo.query() is actually a function inside the dojo object, which would naturally mean it is inside dojo.js, but in this case this method is in a separate file query.js which is “the knowledge” of the mapper.

Building the namespace tree was another challenge, loading all the files in the browser and inspecting the entire namespace via JavaScript would just be an aweful waste of resources. So currently there is a small python script which generates the JSON files which contain the contents of the tree to the left. But the high flexibility of using dynamic extending of objects (like e.g. NodeList-fx does) mixins and other things make it hard to rely purely on the generated contents of the tree, so they are partly hand-crafted too.

The UI is purely dojo, showing off some of the neat features, like the slick ExpandoPane. In my eyes it looks very nice, with a lot of attention to the detail. The UI was actually the part that needed the least time to build, thanks to Nikolai’s deep knowledge it was a piece of cake. There are of course a couple of glitches like the wrapping of the tabs, but hopefully this is just another kick in the right direction to speed up those kind of fixes. Because what is there is already much more than just the base of a GUI toolkit with some widgets, it is a full-fledged-ready-to-go-batteries-included-kick-ass set of UI components. (Ok, enough wallowing, yes I am biased :-).) So look for yourself and let us know what you think.

The future

As you know it too, working on those kind of projects always spins off a lot of new ideas. So we want to share some with you and maybe even get some help on some of them. First: we will put the source code out on google code (or alike) and it will be open for contributions, of course. We just need to do some renaming to ensure future-proof enhancements won’t just clobber this thing and make it unmaintainable.

Another idea is to configure the API docs viewer for custom namespaces and as long as the inline comments are dojo style it should be just a snap of a finger to get your own project’s API docs out. Well, actually the snap of a finger is the creation of the above mentioned JSON file, which contains the tree structure. But one day we will also have an auto-detector which builds the tree initially out of traversing through a given existing namespace (given that it is entirely loaded).

Idea No. 734 :-) was to provide the API viewer for other libraries too. The architecture is made this way, that the reflection and file parsing are separated and could be extended to work with another inline doc style syntax (we made first experiments with it). In order to do this right we think about having a common interface where to put and get the apidoc data from. A json-schema for API doc data is required. I have started on one, but this task really is huge when done right.

Of course the __doc__ property will be provided. Currently when working with libraries or function that I don’t know I mostly use toString() on it and learn from the source code. I could also very well imagine myself using __doc__ if it was there. So keep looking for that, I think it can change the way one uses the FireBug console and learns about libraries.

Since we know all the objects, methods on the one hand and the according docs on the other hand we can tell how good the doc coverage is. This heads into the direction of continuous integration and imho that is really where JavaScript still has a long way to go.

And there are a couple more ideas, like running the inline doctests in the UI, integrating the API viewer with Bespin and allowing to throw the api viewer onto any page using a bookmarklet, which would nicely let you browse the JavaScript API of any site, no matter if you want to learn, fix something or whatever. To mention just some of the ideas …

Now if you want to get your hands dirty and play with the code, see how it can integrate with your own code or just have offline dojo api documentation, drop us an email ( labs (a t) uxebu.com ) and we will make sure a copy of the code lands in your mailbox. Also, if you find bugs, have ideas, want to contribute, contact us and we will exchange ideas to make this tool the best available javascript api viewer out there.

The root of all evil was a simple function that was searching for certain information in some data and returning me a piece of those, it looked like this:

Looks pretty simple, but it failed in IE. There is some problem with the filter() function in IE, it just barks when I run the following

May be I oversaw some really simple error I made. But anyway, that lead me to debugging this thing and trying stuff out and I discovered that the following happens.

But I was very sure that dojo would return an array of three elements with null each. So I tried that of course.

Aha, that’s what I expected. So jQuery just does it a little different. Ok, good to know, this again means that I can cut my initial script shorter, by just removing the filter() call. Good thing.

So that this works and only returns the id if it is larger than 1, which is actually the case that I need. While I find this quite handy and had wished for it a lot of times in dojo too, I see it as rather inconsistent, simply because it is a special case, you would need to know about.
Since Firefox3 comes with the map() function already implemented (so it must be at least JavaScript 1.6) I tried the native method:

And as I expected it does return the elements in the array, just like dojo does.
So note jQuery does it differently. Which is kind of ok, since the map() function is implemented in it’s own namespace and does not override the native map() function but I find it confusing.
And dojo just does it as the map() function which is defined in the JavaScript spec.
Just in case someone else stumbles over it …