Those who work with Java Script know, that Dojo Toolkit is not perceived as ideal library. Followers claim it addresses missing “enterprise” features along with mobile support and breadth palette of UI widgets, opponents discredit such viewpoint nailing down many core problems, poor documentation among them. I do not have a luxury of choice as IBM products I work with, like BPM or Worklight, heavily rely on Dojo. Being constantly offline, ancient books and the online-only dev guides are pain in my frequently traveling ass. And that pushed me to make up local Dojo documentation server.

API documentation

While reference guide was easy to find in prepackaged form, the API detailed documentation is available in web-app fashion. I did my first attempt to setup local API server when dojo 1.8 was in pre-release phase so that I was following version 1.7. Based on this nice howto I applied it on my environment solving Windows specific roadblocks. Soon after that 1.8 became latest-greatest I wished to get it too, just to be caught by changed data format and documentation compilation process. Since the new approach can hold documentation for all versions from 1.3 up to 1.8 so I decided to start over.

Lessons were learned, portable local server assembled and time wasted too. Complete installation instructions can be found on github on “api-viewer” application  however to get it done quicker here I made up detailed step-by-step guide for Windows users:

1. In subsequent steps the ./ is root for portable installation. Pick up any empty directory to start assembly.
2. Download and decompress all necessary packages:
   • api-viewer-master.zip – unpacked as ./api
   • dojo toolkit 1.8.1 – as ./dojotoolkit
   • PHP 5.4.9 – as ./php
   • Apache 2.4.3 – as ./apache
   • PHP module – unpacked php5apache2_4.dll-php-5.4-win32.zip/PHP 5.4.9/php5apache2_4.dll to ./php

   Note: keeping to default directory names (like “api” and “api_data”) minimizes reconfiguration of defaults and keeps local server URLs similar to public ones.

3. Instead of following lengthy and cursorily written “documentation generation” chapter you can simply download data files used on online server. For version 1.8 get http://dojotoolkit.org/api_data/1.8/details.xml and http://dojotoolkit.org/api_data/1.8/tree.json and put them into ./api_data/1.8 directory.
   Since “http://dojotoolkit.org/api” is serving API docs for all dojo versions after 1.2, you can download other versions of “api data” if you need. For consistency keep the same numeric scheme i.e. files taken from “http://dojotoolkit.org/api_data/1.7/…” should be placed into ./api_data/1.7 and so on.
4. Reconfigure Apache by opening ./apache/conf/httpd.conf and modifying existing sections or adding missing lines. You can place that snippet at the beginning of file and comment out subsequent repeating sections:

   ServerRoot "../" LoadModule rewrite_module modules/mod_rewrite.so LoadModule php5_module "../php/php5apache2_4.dll" AddHandler application/x-httpd-php .php PHPIniDir "../php" DocumentRoot ${DOJO_SERV} <Directory "${DOJO_SERV}/"> Options Indexes FollowSymLinks AllowOverride None Require all granted Allow from all </Directory>; DirectoryIndex index.php RedirectMatch ^/$ /api Listen 8765 ServerName localhost

   ServerRoot "../" LoadModule rewrite_module modules/mod_rewrite.so LoadModule php5_module "../php/php5apache2_4.dll" AddHandler application/x-httpd-php .php PHPIniDir "../php" DocumentRoot ${DOJO_SERV} <Directory "${DOJO_SERV}/"> Options Indexes FollowSymLinks AllowOverride None Require all granted Allow from all </Directory>; DirectoryIndex index.php RedirectMatch ^/$ /api Listen 8765 ServerName localhost

5. Since <Directory> directive of httpd.conf requires absolute paths, to make installation portable environment variable DOJO_SERV is introduced. Note that PHP paths are relative to current directory of http daemon. To make it working apache process has to start from ./apache/bin and has to have variable defined. This is done by ./start.bat script:

   @echo off REM REM set DOJO_SERV to root dir (where this batch is place) REM (variable is used in ./apache/conf/httpd.conf) REM set DOJO_SERV=%~dp0 cd %DOJO_SERV%/apache/bin echo Close this window to terminate DOJO API documentation server echo available at http://localhost:8765/api start http://localhost:8765/api httpd.exe

   @echo off REM REM set DOJO_SERV to root dir (where this batch is place) REM (variable is used in ./apache/conf/httpd.conf) REM set DOJO_SERV=%~dp0 cd %DOJO_SERV%/apache/bin echo Close this window to terminate DOJO API documentation server echo available at http://localhost:8765/api start http://localhost:8765/api httpd.exe

6. Reconfigure “api viewer” by opening ./api/config.php and modifying dojo toolkit location, commenting out online version and providing local installation:

   # $dojoroot = "//ajax.googleapis.com/ajax/libs/dojo/1.8.0"; $dojoroot = "/dojotoolkit";

   # $dojoroot = "//ajax.googleapis.com/ajax/libs/dojo/1.8.0"; $dojoroot = "/dojotoolkit";

7. Copy ./php/php.ini-production as ./php/php.ini; no additional PHP reconfiguration is required.
8. As the local server only provides API documentation, links on the top of the dojo website, such as “download” or “community”, will not work. The whole header is removed by commenting out ./api/themes/dtk/header.php content:

   <?php /* require(dirname(__FILE__) . "/includes/header.inc"); */ ?>;

   <?php /* require(dirname(__FILE__) . "/includes/header.inc"); */ ?>;

9. Launch web server with ./start.bat. It will open for you system default browser with documentation.

Reference guide

Reference guide files can be downloaded as bundle of static web pages. This way you can use separately or put them next to the same API server to keep it in one place:

1. Download reference guide files. While you can find official download for 1.6.0 and 1.7.1 I could not find ready made bundle for 1.8. If you have the same problem, jump to the bottom of this post to download section.
2. Unpack ref guide to directory with the same version number i.e. for 1.8 to ./reference-gude/1.8.
3. Enable two buttons for API and Reference Guide in header of doc website. Uncomment ./api/themes/dtk/header.php if you commented the content out in step 7. Then edit ./api/themes/dtk/includes/header.inc stripping UL list to two items:

   <ul id="navigation"> <li class="docs"><a href="/api">API</a></li> <li class="docs"><a href="/reference-guide/1.8">Reference guide</a></li> </ul>

   <ul id="navigation"> <li class="docs"><a href="/api">API</a></li> <li class="docs"><a href="/reference-guide/1.8">Reference guide</a></li> </ul>

4. Modify ref guide HTML files to also have two buttons in header. Search for occurrence of <ul id=”navigation”> and replace UL list like in previous point. Search also for all other occurrences of href=”http://dojotoolkit.org/api” and href=”http://dojotoolkit.org/reference-guide” to convert them to relative references, href=”/api” and href=”/reference-guide”respectively.
5. Since layout broke apart, you can fix it a little. Edit CSS of API (./api/themes/dtk/css/site.css) and ref guide (./reference-guide/1.8/_static/css/site.css) commenting out line 76 i.e. /*right: 230px;*/ for #header ul selector.
6. If you need to get reference manual for 1.6  and 1.7 you need to repeat previous 2 steps for each version.

Voila!
Note that local documentation server is incomplete hence some links will not work if you are offline.

If you got to this point you seem to be serious about offline docs and I have a gift for you – ready-made package with complete portable server for download:

• Portable server with API (download 52MB)
• Reference-guide 1.8 for API server (download 43MB)

Enjoy!