Discovering Dojo for Domino: Part 1- The basics

My journey in learning to use Dojo with Notes and Domino web enabled applications.

I have recently taken over supporting some Domino applications that use dojo, so I thought I had better learn a thing or two about it. I have never used any of the javascript frameworks, and my javascript knowledge is patchy. It's all been learned through 'copy and paste' from other peoples work and the web. Some things I think I know pretty well but there are gaps.

I'm going to write up my experiences as I go. So this is not a structured tutorial and may lead off down the wrong path at times. Feel free to comment on better approaches if you see me doing something wrong.

So - where to start? The best place I found is the Dojo Quick Start Guide

Now I don't just want to learn dojo, I want to learn dojo for use with Domino. And if your are a Notes / Domino developer you know that some things work just like in the web examples and some things don't.

The first challenge is always, where to put the various code snippets that are shown in the examples. I started by creating a form and a javascript script library to go with it. I am going to have a 'dojo template' form with the basics in it, and a template javascript library. Each time I need a new form, I will copy the templates and start from there. In this post I'll describe how to get to the basic 'yeah it works' stage.

The basics: Getting the code

Well I haven't actually done this myself. The environment I am working in has the dojo scripts on the server already (Domino 7.x). You can download the source files and place them on your server, you can put them in your database as a file resource, or you can reference them directly from a CDN - instructions on the download page.

Dojo comes in three parts -

• core: the basics. Event handlers, DOM manipulation, graphics effects
• digit: 'Great interface widgits'. This is what I am really after
• dojoX: complex widgits, graphing and charting

I'll deal with the core first, then move on to digits. I probably won't get to dojoX

How to add dojo to Domino

The Quick Start guide has some simple HTML and scripts you can then play with. I put the example HTML on the form and marked it up as Pass-thru HTML. I could have left the script directly on the page as well. However the point of this excercise is to learn how to use dojo with Domino so I put some of the code in the in a script library and some in the Javascipt Header section of the form.

The following is included on the tutorial first page:

It's important to note that you should not set on an onLoad function directly on the tag when using Dojo. dojo.addOnLoad(someFunc) is prefered over and window.onload = someFunc;

and provides examples such as the following:

dojo.require("dijit.form.Button");
dojo.require("dijit.TitlePane");
dojo.addOnLoad(function(){
  dojo.byId("testHeading").innerHTML = "We're on our way!";
  console.log("onLoad fires after require() is done");
});  

I put the dojo require() and addOnLoad() functions in the js header (passing a funtion name init() to the addOnLoad function), created an init() function in my scipt libary and put any example code in the init() function. I also created a style sheet and embedded it on the form for the simple styles used in the examples.

So the break-up went like this:

HTML Head Content

<script type="text/javascript" src="[relatve file path]/dojo.js"
 djConfig="parseOnLoad:true, isDebug:true"></script>

JS Header
[Resource: "libJSMyTestForm"]

dojo.require("dijit.form.Button");
  dojo.require("dijit.TitlePane");
  dojo.addOnLoad(init)

Script library libJSMyTestForm

function init() {
  dojo.byId("testHeading").innerHTML = "We're on our way!";
  console.log("onLoad fires after require() is done");
}

I added the HTML to the form, style to my style sheet, opened the form in a browser et voila - working dojo!

Moving on.. just a little

I was able to work through the tutorial fairly easily. It quickly demonstrates getting parts of the DOM and modifying them (throwing in a fade-out here and a slide-left there as well as the standards of replacing innerHTML and classes). It moves through basic event handling (registering an onClick function for a single element and using dojo.connect to register the event for multiple elements) to animation effects (slides, fades, etc) and the events that these animations themselves have. For example animations have beforeBegin and events, allowing you to easily chain animations.

The tutorial then covers basic Ajax - fetching text, posting a form, and fetching json. By the end of an hour or two, you are flying like a pro: dynamically changing your form, adding animations, playing with event handlers and Ajax.

But this is where my javascript knowledge starts to hit it's boundaries. The examples are full of code like this:

var init = function(){
  var contentNode = dojo.byId("content");
  dojo.xhrGet({
    url: "js/sample.txt",
    handleAs: "text",
    load: function(data,args){
      // fade out the node we're modifying
      dojo.fadeOut({
        node: contentNode,
        onEnd: function(){
   // set the data, fade it back in
   contentNode.innerHTML = data;
   dojo.fadeIn({node: contentNode}).play();  
  }
      }).play();
    },
    // if any error occurs, it goes here:
    error: function(error,args){
      console.warn("error!",error);
    }
  });
};
dojo.addOnLoad(init);

Now I know there are different ways of declaring functions - using the FUNCTION statement, assigning a function to a variable and using the new function() constructor, and in-line as shown above.

But why? And where do you use one instead of the other? What is the scope of in-line functions like those above? What if I want to use an existing function in one of my script libraries? simply adding the function name followed by () did not seem to work. Why?

So now I think I have to divert from my journey to dojo enlightenment and seek a side-road through Advanced Javascript.

Can anyone recommend a good reference?

UPDATE: fixed the HTML Head Content - I had closed off my <Script> tag in the wrong place. Sorry for anyone who tried to copy it earlier (note to self: do not manually type code from memory. Always copy and paste working code!)