devbl0g

Just found a great php documentator that is NOT phpdocumentor.

It is called docblox (http://www.docblox-project.org/).

Features (as taken from the site)

• Fast: it is currently able to fully parse and transform (these are rough stats, more detailed benchmarks may follow on another page):Agavi 1.0.4 and Solar Framework 1.1.2 in less than 90 seconds
• Zend Framework 2 in approximately 17 minutes
• Low memory usage: during the process I have not yet been able to detect any higher memory usage than 50MB when parsing Zend Framework 2. Agavi and Solar Framework did not even exceed 20MB.
• Namespace support: no further explanation required, right?
• Incremental parsing: the parsing process is capable of detecting changes in the given fileset and only parse those files that actually have changed. This will speed up the process a lot for Continuous Integration servers.
• For example: Agavi 1.0.4 parsed in approximately 3 seconds when no changes where present.
• Two-step process: DocBlox first parses the source code and generates an XML file containing the structure of the given application and then you may invoke the transformer to generate HTML output
• Search: DocBlox supports a Javascript search option. Whichever term you enter is matched and you can see immediately go to the right page.
• Theming and Templating: DocBlox separates the matter of templates and themes: a theme is a collection of files used to generate a certain look and feel, where as a template is a collection of transformation ruleswhich grants the power to generate anything in any combination of Look and Feels. with your own template you could even generate multiple themes in one documentation site if you’d wanted to!
• Custom renderers / writers: if themes do not give enough control over the layout and output format: a developer is able to write a class (called a Writer) which transforms the XML file into the needed output.

It really is really good, the documentation that it produces is top notch (in terms of user experience and features), it even generates a graphical classmap if the library for graphics is installed.

Give it a whirl its worth the look.

Getting the library

You can get the library from here http://dojotoolkit.org/download/, I recommend the CDN version for production sites.

Including the library

This is a very simple matter and includes one script file include in the page. e.g.

<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.7.0/dojo/dojo.js" type="text/javascript"></script>

Well that was simple wasn't it.

Start Coding

You can now start to get your feet wet by reading through some of the examples and tutorials on nettuts+ or the DOJO website.

http://net.tutsplus.com/tutorials/javascript-ajax/dig-into-dojo-dom-basics/

http://net.tutsplus.com/tutorials/javascript-ajax/dig-into-dojo-nodelist-modules-and-ajax/

http://net.tutsplus.com/tutorials/javascript-ajax/dig-into-dojo-dijit/

http://dojotoolkit.org/documentation/

Benefits

• Class based design patterns
• MVC based coding patterns (as of 1.7)
• Large potential UI library - great for admin systems
• Dependency management - only includes the JavaScript you need, when you need it.
• Maintainability
• Sizzle-like DOM based selectors
• Unit Tests for JS using D.O.H

Drawbacks

Why

Short answer, I love learning.

Long answer, well we build A LOT of modular based websites at the company I work for and we heavily rely on MVC and OOP techniques for our backend development and jQuery for most of our JavaScript development.

However some of us (the all-rounders from a programming background) tend to bring in helpers such as base2 and are starting to dabble in backbone.js to fill the gap in our hearts for OOP (proper class based inheritance and the like) and MVC techniques in JavaScript.

However this has a number of issues:

DOJO covers all the above points except maybe spaghetti code, however this can be tackled by following design patterns set out at the beginning of any project.

I will be writing up a tutorial on the various different aspects outlined in this post in the following weeks and expand on them, as well as giving tutorials on how to do certain things as I learn them, this should be an interesting journey.

Further Reading

Conceptual Information

This post I found particularly interesting as it expresses in a clear manner the issues encountered when coming from jQuery to DOJO.

Dojo Confessions (Or: How I gave up my jQuery Security Blanket and Lived to Tell the Tale) by Rebecca Murphey

Sure, it's a little aged but it's not really code related, it is instead very concept related.

User Documentation

http://dojotoolkit.org/reference-guide/dojo/index.html - the DOJO docs are rather sparse in some area's and are not as rounded as a lot of other frameworks out there but once you get used to their API style documentation it all becomes rather clear.

Object Oriented Programming Techniques

I think this is the feature that most sold me on my path to start to learn DOJO.

http://dojotoolkit.org/reference-guide/dojo/declare.html

 jQuery / MooTools/ DOJO call comparison

http://davidwalsh.name/dojo-mootools-jquery

I will be posting a series of articles over the coming weeks in relation to the path of my learning DOJO in the hopes to get a guide series going to help other developers out there who are wanting to learn DOJO as a possible alternative framework.

MVC Based Patterns in DOJO

http://livedocs.dojotoolkit.org/dojox/mvc

http://doughays.dojotoolkit.org/dojomvc/

Unit Testing

http://dojotoolkit.org/reference-guide/util/doh.html

One of my latest favourite techniques is to start an entry point of a system with an Class Instantiation.

<?php
class Index {
  /** Where the magic happens **/
  function __construct() {
    // All your normal global level code can go in here
    // OR you can always split them out into methods
    // which will give you further flexibility in the
    // future.
  }
}
new Index();

Benefits

• No variables on the global scope (important when on shared hosts)
• Object Oriented from the beginning of the application.