What is the best practice for Dojo dijit creation?

Question

What is the best practice for Dojo dijit creation?

1. A purely declarative approach (D)
2. A purely programmatic approach (P)
3. A combination of the two (D&P)

Criteria

1. Easiest to maintain
2. Fastest to develop with
3. Most intuitive
4. Best performance
5. Most functionality and flexibility

Context

I've been working with Dojo for a little less than a month now, and I've recently started working with the dijit library. One of the well-advertised aspects of dijits is that they can be declared programmatically or declaratively. I always like to approach a new set of tools with an understanding of best practices and some general idea of which approach has which strength/benefits for a particular application.

The information below comes from some personal experience with both styles, as well as the reference material I've been able to find, which isn't a whole lot. This link is the only one I've found in the official Dojo documentation on the subject, and this post provides some outside perspective with a basic presentation of how the code for each looks for simple scenarios. Both links are for older versions of dojo, before AMD was introduced in version 1.7.

Programmatic

1. Separates Dojo from HTML, which preserves semantic purity of HTML
2. Puts event handlers and widgets in the same place, increasing readability
3. Seems to make it easier to assign values to attributes dynamically (e.g. create unique IDs using a function)

Declarative

1. Rapid development -- intuitive, implied nesting, widgets defined like normal HTML elements
2. Valid HTML5 through use of data-jojo-* attributes
3. Does not preserve semantic purity of HTML
4. Event handlers come from outside scripts, creating some complexity and reducing readability
5. Initial parseOnLoad can slow up-front widget setup

A note on responses: Please address each of the criteria in your response. Feel free to propose any additional criteria you think are important. I am by no means an expert at evaluating best practices.

Update:

After browsing around for more info on this, I found another post with similar thinking, which provides some useful context on what implications these style differences have.

Answer 1

I don't think there isn't a best practice. Personally I like to use a combination of both programmatic and declarative code.

I think it makes more sense to seperate the presentation layer from the business logic layer (somewhat like the n-tier architecture). I mean, what's the difference between a dijit/form/TextBox and the standard <input type="text" /> HTML element? They're both part of the presentation layer and they both have the same purpose. The only difference is that the one is a custom element while the other one isn't.

But on the other hand, I consider event handling and validation as business logic, so I would put these into a JavaScript. You could also declare your dojo/store objects declarative, this is also something I don't like because it doesn't have to do with my presentation layer.

Now, back to addressing your points:

Easiest to maintain: If I had to change a dijit widget, then I would probably look into the HTML (seperation of concerns; presentation <--> business logic). It's also easier to find. For example, if you know that the dijit widget is right below the title and just above a button, then you exactly know where to look for in your HTML code. If we made it programmatically, it could be anywhere in your code.

Fastest to develop with: Well, maintaining and developing is a bit the same, but another advantage of declarative markup is that the markup you write actually serves as a placeholder while programmatically you will have to assign each property to a value.

Most intuitive: I also address this in the first part (easiest to maintain). I also think that it's pretty good that they also use a few standard HTML attributes like title, value, placeholder, ... . I don't think this pollutes your HTML markup, but increases readability too.

Best performance: It's not the fastest way, I'm well aware of it. But the margin is pretty small, it's not that it is a huge difference. You could also tweak it by disabling parseOnLoad and manually parse the nodes you need to be parsed. Another nice thing is that the end user "sees" something. For example, if you write the following code:

<select data-dojo-type="dijit/form/ComboBox"></select>
<input type="text" placeholder="Text..." />

The end user actually sees something when he loads the page (and it's pretty representative of the real result), even is the page is not parsed. When you create everything programmatically, the only thing the user will see is a white page.

Most functionality and flexibility: Because I think combining declarative and programatically way of developing, I can enjoy the benefits of both. You're somewhat blocked in doing everything in a declarative way (event handling really looks messy if you put it all in your HTML), but I would write those in JavaScript code.

On the other hand, it really looks messy when you're creating a widget programatically (that's an opinion), so I can define these in HTML where it's a lot easier.

---

So in the end I like to write a combination of both. Event handlers indeed come from outside scripts, but if you write proper MVC applications, they always will (since it is a part of the controller while the markup itself is part of the view).

I'm not saying you have to put all event handlers in one file, no, thanks to the AMD loader you can easily add other scripts. If you group all interaction of a certain widget (or a group of widgets) into files and name these correctly, it's pretty easy to find things.

The more files, the smaller the files usually are and the easier they can be read (so complexity goes down and readability goes up). You might end up with a lot of files, but if you name these correctly (and document them maybe), there should be no problem.

---

But in the end, this is an opinion, there are probably other opinions too which are as good or even better than mine. Sometimes it's also depending on the situation, if performance really is one of the biggest requirements, then defining everything in JavaScript might be the best solution too. It's not like these rules are carved into a stone somewhere.