Dojo offline documentation

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:

    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
  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
  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";
  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"); */ ?>;
  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>
  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:

Enjoy!

This entry was posted in Software and tagged , , . Bookmark the permalink.

4 Responses to Dojo offline documentation

  1. Nicolas says:

    Great post. I was beginning on dojo in an environment without an internet connection and this really helps me. Just need to includes the Tutorial section now 🙂

    Also, for the httpd.conf file in top of the snippet shown here, I had to add quite a few LoadModule directive (I just copied all the one from the orginal conf file)

    Cheers

    Nicolas

  2. Nick Ace says:

    Hi
    Thanks this helps me a lot., on my windows box I configure it according to this instruction but under xampp and it works fine.

    I have change my OS to ubuntu and same configuration doest work all files have been loaded but it show a dojo:15 systax error. which I cannot fixed please help – using lampp.

    Thanks

    • andy says:

      Nick, sorry I have neither working environment to test your case nor time for it. When you solve it, share back with me 🙂

  3. Wilson says:

    Thanks for this gift, it’s very important for me. Only one question, do you know where I can find some like this but for the last version 1.10 of DOJO. Thanks

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.