HelloWorld

Version 59, changed by lduivenb@iinet.net.au 01/11/2007.   Show version history

NOTE: This page is currently undergoing modification/updating. It should be finished no later than 30th January 2007

Table of Contents

• Introduction
• Changelog
• Notes / Requirements
• Contacting the Author
• 1.Setting Up Dojo
• 2. Getting Started
• 3. Creating a Button Widget
• 4. Connecting an Event to the Widget
• 5. Reading Data from the Server
• 6. Sending Data to the Server Using GET
  • 6.1. Using a PHP Server
  • 6.2. Using an ASP Server
  • 6.3. Using a ColdFusion Server
  • 6.4. Using a Java Server (JSP)
  • 6.5. Using a Perl Server
• 7. Sending Data to the Server Using POST
  • 7.1. Using a PHP Server
  • 7.2. Using an ASP Server
  • 7.3. Using a ColdFusion Server
  • 7.4. Using a Java Server (JSP)
  • 7.5. Using a Perl Server
• 8. Finding More Resources

Introduction

The purpose of this tutorial is to provide a starting point for users who are new to Dojo. Whilst every effort is made to introduce as much as possible about Dojo, it is impossible to include more of the detailed information since to do so would be counter productive and confusing to new users. For more information on the concepts introduced here, please see the links to other resources at the end of this document (Section 8 - Finding More Resources).

Changelog

• 28th June 2006 - Addition of Perl Server examples for GET and POST (courtesy of Gareth Tansey)
• 21th June 2006 - Modification for compatibility with 0.3.x release (Bill Keese)
• 22th May 2006 - Addition of Java Server (JSP) examples for GET and POST (courtesy of Kexi)
• 19th May 2006 - Addition of ColdFusion examples for GET and POST (courtesy of Matthew Reinbold)
• 8th May 2006 - Initial Public Release

Notes / Requirements

Since this tutorial makes use of Dojo‘s event, IO, and widget systems, it is important that the "Kitchen Sink" Dojo build version 0.4.0 is utilised. This can be found at the following address:

http://download.dojotoolkit.org/release-0.4.0/

Contacting the Author

Thinking of making modifications to this document? Want to make suggestions / constructive criticism?

If so, please contact me (Lance Duivenbode) at dojo AT duivenbode DOT id DOT au. Feedback is always welcome since it helps me improve my documentation - both now and in the future. Thanks!

1. Setting Up Dojo

The first step to use Dojo in this tutorial is to create the directory structure and set up the location of the files. To achieve this, you will need to create the following directory structure in the location of your choice (which for the purposes of this example will be called ‘HelloWorldTutorial‘).

    - HelloWorldTutorial/||---- js/|---- dojo/

Once this has been done, grab the latest ‘Kitchen Sink‘ build from http://dojotoolkit.org/download/ and decompress it into the HelloWorld/js/dojo/ directory. You should now have a directory structure that is similar to the following (where ‘..‘ indicates that there are more files under that directory, but that they are not shown here):

    - HelloWorldTutorial/||-- js/|-- dojo/|-- build.txt-- CHANGELOG-- demos|-- ..-- dojo.js-- dojo.js.uncompressed.js-- iframe_history.html-- LICENSE-- README-- src/|-- ..

2. Getting Started

Once we have setup the directory and file structure for the tutorial, we will need to setup the Javascript component of our HTML page. Have a look at the code below:

As it can be seen above, the page is a just a standard HTML skeleton with a script element inserted into the head section. This script element is responsible for loading the base Dojo script that provides access to all the other Dojo functionality that we will use.

3. Creating a Button Widget

Ok, now for the exciting part! In this example we‘re going to create a Button widget with the text ‘Hello World!‘. In the case of the Button widget, three visual states (mouseOut, mouseOver, and mouseDown) are available which means that we are able to enhance the user‘s experience somewhat.

The first step in creating the widget is telling Dojo to load the appropriate modules. In the header, add another section (hereafter referred to as section 2) below section 1 as follows:

The first dojo.require lines instructs Dojo to include the widget managing functions (it does NOT load all the widgets!) , whilst the second dojo.require line instructs Dojo to load the Button widget. If you were to omit the second line, the markup code for the button would not be evaluated by Dojo upon loading, resulting in a plain HTML button instead of what you expect.

After making the changes, insert the following code into the body section of the HTML:

    Hello World!

The key attribute of this HTML element to notice is the dojoType attribute. The dojoType attribute is responsible for instructing Dojo on how to process the element when the page is loading. In this case we‘ve used a button element for the button though we could have used an input element - Dojo will work with either as long as the dojoType attribute is present. It is worth noting that if we did use an input element, we would have to specify the button‘s text by using adding a caption attribute that contained the desired text.

Note: Whilst in this example we have used widgetId="helloButton", this could be replaced with id="helloButton" without the functionality being affected - Dojo‘s widget system is smart enough to convert regular id attributes to widgetId‘s if no widgetId` attribute is explicitly named.

4. Connecting an Event to the Widget

A button is all well and good, but what about getting it to do something when it‘s clicked? We could just specify an onClick event handler for the button, but there‘s another, more efficient way - the Dojo event system!

To get started we need to modify the Javascript headers once more to include the event modules. So change the following:

To be:

Notice the .* on the end of dojo.event? That tells Dojo to include all the event functions just as we have included all the widget related functions (but NOT all the widgets) by specifying dojo.widget.*. The next step is to write a function that will be called by the button when it is clicked. For now the following will do, so insert that into the last Javascript section, after the code that already exists.

    function helloPressed(){alert(‘You pressed the button‘);}

Pretty simple - just what you‘d normally expect. Now we need to hook up the button to the function. However, in order for it to work, we need to do this after the widgets have been created by Dojo. Don‘t worry though - Dojo has it covered! Simply insert the following code into the last Javascript section:

    function init(){var helloButton = dojo.widget.byId(‘helloButton‘);dojo.event.connect(helloButton, ‘onClick‘, ‘helloPressed‘)}dojo.addOnLoad(init);

Firstly, the line dojo.addOnLoad(init); tells Dojo to call the init function when it has finished loading correctly. This is very important! If the init function was called before Dojo has finished parsing the HTML it would fail since the Button widget would not exist at that point in time - causing a nasty error.

Once Dojo has finished loading and the init function is being run, the first line of the function (var helloButton = ...) gets a Javascript object reference to the created Button widget. Using document.getElementById will not work since the DOM has been modified by Dojo. Instead, Dojo keeps a reference of all widgets it has created that can be accessed with the dojo.widget.byId function - providing you specify either the widgetId or id attribute in your markup.

So, to recap, the Javascript code in the third section of the header should resemble:

5. Reading Data from the Server

Having an alert pop up when we press the button is great, but what if we want to retrieve some data from the server? Again, Dojo comes to the rescue with an easy method of accomplishing this - dojo.io.bind. For easy reference, the code for this section is available as HelloWorld-Section5.html and response.txt in the attachments section.

Before going further, it is worth noting that dojo.io.bind can be a complex function - and one that would take a lot of writing to explain. However, such a document does exist at http://dojotoolkit.org/docs/intro_to_dojo_io.html. This tutorial does not go into great detail - it will simply show how to achieve common functionality.

So, to get started, we first need a callback function to handle the data to be returned from the server. Insert the following code into the last Javascript section in the header:

      function helloCallback(type, data, evt){if (type == ‘error‘)alert(‘Error when retrieving data from the server!‘);elsealert(data);}

The three arguments to the function (type, data, and evt) are important - don‘t leave any of them out! The first argument (type), specifies the return type - which is usually ‘load‘ on success or ‘error‘ on error. The second argument (data) contains the data sent back from the server, whilst the third argument contains a Dojo event object. In the above function, we‘ve used the type argument to determine whether the request was successful, displaying an error message if it wasn‘t or the returned data if it was.

The next step is to link the click of the button to the server request. To do this, modify the following code:

      function helloPressed(){alert(‘You pressed the button‘);}

To resemble:

      function helloPressed(){dojo.io.bind({url: ‘response.txt‘,handler: helloCallback});}

The above code basically tells Dojo to query the URL specified by url and to use the function specified by handler to process the response from the server.

Finally, we need to create another file in the same directory as HelloWorld.html called response.txt. In this file, place the text ‘Welcome to the Dojo Hello World Tutorial‘.

Now, when the button is clicked, a Javascript alert should display the text from the response.txt file. Dojo-Easy!

So, to recap, the third Javascript section should resemble:

Next, we‘ll look at doing something meaningful with that server request.

6. Sending Data to the Server Using GET

It‘s all well and good retrieving static data from the server, but it is hardly a widely used situation in real life. So, instead of simply requesting data from the server we also will send it some information for it to process. In this section, we‘ll use the GET method whilst in the next section we‘ll use the POST method. For easy reference, the code for this section is available as HelloWorld-Section6.html in the attachments section. Server side code is also available as HelloWorldResponseGET. where type is ASP (‘.asp‘), PHP (‘.php‘), ColdFusion (‘.cfm‘), or Java (‘.jsp‘).

Firstly, in the markup section of the HelloWorld.html file (i.e. the body section), we need to add another element - an input element. So, change the code in this section from:

    Hello World!

to:

    Hello World!
Please enter your name: 

Once this has been done, we will also need to change the code in the last section of Javascript in the header from:

      function helloPressed(){dojo.io.bind({url: ‘response.txt‘,handler: helloCallback});}

to:

      function helloPressed(){// Don‘t forget to replace the value for ‘url‘ with// the value of appropriate file for your server// (i.e. ‘HelloWorldResponseGET.asp‘) for an ASP serverdojo.io.bind({url: ‘HelloWorldResponseGET.php‘,handler: helloCallback,content: {name: dojo.byId(‘name‘).value }});}

Before we go any further - it is important to mention that the url property in the dojo.io.bind function call must be set to the file that is appropriate to your environment. If you are using an ASP server then the value must read ‘HelloWorldResponseGET.asp‘ instead of ‘HelloWorldResponseGET.php‘ Likewise, if you are using a ColdFusion server then the value must read ‘HelloWorldResponseGET.cfm‘ instead of ‘HelloWorldResponseGET.php‘. Finally, if you are using a Java server (JSP) then the value must read ‘HelloWorldResponseGET.jsp‘ instead of ‘HelloWorldResponseGET.php‘, or if you are using a Perl server then the value must read ‘HelloWorldResponseGET.pl‘ instead of ‘HelloWorldResponseGET.pl‘. The code for these files is in the sections below, and is also available as attachments to this tutorial.

In the code above, you will notice that there is a new property that has been passed to the dojo.io.bind function. This property - content - allows the programmer to send arbitary values to the server as parameters. In this case, since we are using the default method of dojo.io.bind which is GET, the server side script will have the value of the textbox available to it as a the GET parameter ‘name‘. It is worth mentioning that if the script expected the parameter under a different name (such as ‘myName‘), we would simply change the content property to be (note the change of ‘name‘ to ‘myName‘ on the left of the assignment operator ‘:‘):

    content: {myName: dojo.byId(‘name‘).value }

Since we‘ve not used it before, it is also worth noting the call dojo.byId(‘name‘).value. Quite simply, this call is a shortcut for the standard document.getElementById(..) function.

Finally, if you enter your name into the text box and you click the ‘Hello World‘ button, an alert box should appear with the message ‘Hello , welcome to the world of Dojo!‘ where is the name you entered into the text box.

Next, we‘ll look at using POST data instead of GET data.

6.1 Using a PHP Server

6.2 Using an ASP Server

<%‘‘ HelloWorldResponseGET.asp‘ --------‘‘ Print the name that is passed in the‘ ‘name‘ GET parameter in a sentence‘response.ContentType="text/plain"response.write("Hello " & request.querystring("name") & ", welcome to the world of Dojo!\n")%>

6.3 Using a ColdFusion Server

Hello, #url.name#, welcome to the world of Dojo!

6.4 Using a Java Server (JSP)

<%/*‘ HelloWorldResponseGET.jsp‘ --------‘‘ Print the name that is passed in the‘ ‘name‘ GET parameter in a sentence*/response.setContentType("text/plain");%>Hello <%= request.getParameter("name") %> , welcome to the world of Dojo!

6.5 Using a Perl Server

#!/usr/bin/perl##  ‘ HelloWorldResponseGET.pl#  ‘ --------#  ‘#  ‘ Print the name that is passed in the#  ‘ ‘name‘ GET parameter in a sentence#use strict;use CGI;my $cgi = CGI::new();print $cgi->header(-type => "text/html; charset=utf-8");print "Hello " . $cgi->param(‘name‘) . ", welcome to the world of Dojo!\n";

7. Sending Data to the Server Using POST

Using GET data is all well and good, but sometimes you want to use Dojo to improve the user‘s experience when using a traditional HTML form. As usual, Dojo has a very nice way of making this easier. Again, the code for these files is in the sections below, and are also available as attachments to this tutorial. Additionally, as with the last section, you will need to change the ‘url‘ property to point to the file that is appropriate to your environment.

Firstly, we need to change the markup in the body of HelloWorld.html from:

    Hello World!
Please enter your name: 

to:

    Hello World!
Please enter your name: 

Next we need to change the helloPressed function of the last Javascript section in the document‘s head from:

      function helloPressed(){// Don‘t forget to replace the value for ‘url‘ with// the value of appropriate file for your server// (i.e. ‘HelloWorldResponseGET.asp‘) for an ASP serverdojo.io.bind({url: ‘HelloWorldResponseGET.php‘,handler: helloCallback,content: {name: dojo.byId(‘name‘).value }});}

to:

      function helloPressed(){// Don‘t forget to replace the value for ‘url‘ with// the value of appropriate file for your server// (i.e. ‘HelloWorldResponsePOST.asp‘) for an ASP serverdojo.io.bind({url: ‘HelloWorldResponsePOST.php‘,handler: helloCallback,formNode: dojo.byId(‘myForm‘)});}

As it can be seen from the code above, we‘ve removed the ‘content‘ property of the dojo.io.bind call and replaced it with a new property ‘formNode‘. This basically informs the dojo.io.bind function that it needs to use the form ‘myForm‘ as the source for the data in the call. In the case of this form, the method has been set to ‘POST‘ so Dojo will in turn use POST when submitting the data. If the form‘s method was either missing or set to ‘GET‘, Dojo would use the GET method instead.

As with the last section, entering your name and clicking ‘Hello World!‘ should yield a message such as ‘Hello , welcome to the world of Dojo!‘ where is the name you entered into the text box.

7.1 Using a PHP Server

7.2 Using an ASP Server

<%‘‘ HelloWorldResponsePOST.asp‘ --------‘‘ Print the name that is passed in the‘ ‘name‘ $_POST parameter in a sentence‘response.ContentType="text/plain"response.write("Hello " & request.form("name") & ", welcome to the world of Dojo!\n")%>

7.3 Using a ColdFusion Server

Hello, #form.name#, welcome to the world of Dojo!

7.4 Using a Java Server (JSP)

<%/*‘ HelloWorldResponsePOST.jsp‘ --------‘‘ Print the name that is passed in the‘ ‘name‘ POST parameter in a sentence*/response.setContentType("text/plain");%>Hello <%= request.getParameter("name") %> , welcome to the world of Dojo!

7.5 Using a Perl Server

#!/usr/bin/perl##  ‘ HelloWorldResponsePOST.pl#  ‘ --------#  ‘#  ‘ Print the name that is passed in the#  ‘ ‘name‘ POST parameter in a sentence#use strict;use CGI;my $cgi = CGI::new();print $cgi->header(-type => "text/html; charset=utf-8");print "Hello " . $cgi->param(‘name‘) . ", welcome to the world of Dojo!\n";

8. Finding more resources

I hope you‘ve enjoyed this tutorial and found it informative. No doubt though, you will need more information on Dojo and how it and it‘s widgets work. Below is a list of links that will point you in the right direction.

• http://dojotoolkit.org/docs/ - The documentation page for Dojo. Has links to all documentation.

• http://dojo.jot.com/ - The Dojo wiki. Has lots of examples and tutorials.

• http://manual.dojotoolkit.org/index.html - Although it‘s not a complete manual yet, it has sufficient info so you can see what Dojo covers and has the basics covered. Not full descriptions but methods and features lists with some comments.

• http://dojotoolkit.org/docs/dojo_event_system.html - The Dojo event system. How you can link functions to the normal JS events the dojo way.

• http://dojotoolkit.org/docs/intro_to_dojo_io.html - Dojo asynchronous request API (aka dojo.io.bind)

• http://dojotoolkit.org/docs/fast_widget_authoring.html - Widgets! Components! Based on what you read earlier, walks you through building a JS UI component. Does the complete tour of the creation of a fully functional UI component and it‘s usage.

• http://archive.dojotoolkit.org/nightly/tests/ - Tests from current nightly build (good for learning how things work)

• http://archive.dojotoolkit.org/nightly/tests/widget/ - Widget tests from the current nightly build (good for learning how widgets work)