HelloWorld_dojo_新学的东东

最新推荐文章于 2024-04-17 21:49:28 发布
最新推荐文章于 2024-04-17 21:49:28 发布
阅读量1.8k 收藏
点赞数
文章标签： dojo button server coldfusion function javascript
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/babydavic/article/details/1707344
版权

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

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: 

<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>

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: 

    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>

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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

To be: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>


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!');
        else
          alert(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: 

    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>

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.<type> 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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

to: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 

<?php
  /*
  * HelloWorldResponseGET.php
  * --------
  *
  * Print the name that is passed in the
  * 'name' 
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 


    
    
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: 


    
    
<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>





    
    


    
    
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: 


    
    
    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>





    
    


    
    
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: 


    
    
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





    
    


    
    
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: 


    
    
    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





    
    


    
    
To be: 


    
    
    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





    
    


    
    
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: 


    
    
    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>





    
    

    
    


    
    
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!');
        else
          alert(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: 


    
    
    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>





    
    


    
    
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.<type> 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: 


    
    
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





    
    


    
    
to: 


    
    
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 


    
    
___FCKpd___19


   
   




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 


<!---
  /*
  * HelloWorldResponseGET.cfm
  * --------
  *
  * Print the name that is passed in the
  * 'name' GET parameter in a sentence
  */
--->
<cfsetting showDebugOutput="No">
Hello, #url.name#, welcome to the world of Dojo!
</cfsetting>







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: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="name">







to: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    <form id="myForm" method="POST">
      Please enter your name: <input type="text" name="name">
    </form>







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 server
        dojo.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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box. 


7.1 Using a PHP Server 


<?php
  /*
  * HelloWorldResponsePOST.php
  * --------
  *
  * Print the name that is passed in the
  * 'name' 
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 


     
     
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: 


     
     
<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>





     
     


     
     
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: 


     
     
    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>





     
     


     
     
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: 


     
     
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





     
     


     
     
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: 


     
     
    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





     
     


     
     
To be: 


     
     
    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





     
     


     
     
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: 


     
     
    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>





     
     

     
     


     
     
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!');
        else
          alert(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: 


     
     
    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>





     
     


     
     
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.<type> 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: 


     
     
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





     
     


     
     
to: 


     
     
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 


     
     
<?php
  /*
  * HelloWorldResponseGET.php
  * --------
  *
  * Print the name that is passed in the
  * 'name' 
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 


        
        
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: 


        
        
<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>





        
        


        
        
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: 


        
        
    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>





        
        


        
        
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: 


        
        
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





        
        


        
        
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: 


        
        
    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





        
        


        
        
To be: 


        
        
    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





        
        


        
        
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: 


        
        
    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>





        
        

        
        


        
        
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!');
        else
          alert(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: 


        
        
    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>





        
        


        
        
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.<type> 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: 


        
        
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





        
        


        
        
to: 


        
        
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 


        
        
___FCKpd___19


       
       




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 


<!---
  /*
  * HelloWorldResponseGET.cfm
  * --------
  *
  * Print the name that is passed in the
  * 'name' GET parameter in a sentence
  */
--->
<cfsetting showDebugOutput="No">
Hello, #url.name#, welcome to the world of Dojo!
</cfsetting>







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: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="name">







to: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    <form id="myForm" method="POST">
      Please enter your name: <input type="text" name="name">
    </form>







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 server
        dojo.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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box. 


7.1 Using a PHP Server 


___FCKpd___28




     
     


     
     
7.2 Using an ASP Server 


     
     
<%
  '
  ' HelloWorldResponsePOST.asp
  ' --------
  '
  ' Print the name that is passed in the
  ' 'name' 
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 


        
        
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: 


        
        
<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>





        
        


        
        
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: 


        
        
    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>





        
        


        
        
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: 


        
        
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





        
        


        
        
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: 


        
        
    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





        
        


        
        
To be: 


        
        
    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





        
        


        
        
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: 


        
        
    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>





        
        

        
        


        
        
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!');
        else
          alert(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: 


        
        
    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>





        
        


        
        
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.<type> 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: 


        
        
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





        
        


        
        
to: 


        
        
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 


        
        
<?php
  /*
  * HelloWorldResponseGET.php
  * --------
  *
  * Print the name that is passed in the
  * 'name' 
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 


           
           
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: 


           
           
<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>





           
           


           
           
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: 


           
           
    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>





           
           


           
           
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: 


           
           
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





           
           


           
           
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: 


           
           
    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





           
           


           
           
To be: 


           
           
    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





           
           


           
           
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: 


           
           
    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>





           
           

           
           


           
           
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!');
        else
          alert(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: 


           
           
    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>





           
           


           
           
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.<type> 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: 


           
           
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





           
           


           
           
to: 


           
           
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 


           
           
___FCKpd___19


          
          




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 


<!---
  /*
  * HelloWorldResponseGET.cfm
  * --------
  *
  * Print the name that is passed in the
  * 'name' GET parameter in a sentence
  */
--->
<cfsetting showDebugOutput="No">
Hello, #url.name#, welcome to the world of Dojo!
</cfsetting>







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: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="name">







to: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    <form id="myForm" method="POST">
      Please enter your name: <input type="text" name="name">
    </form>







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 server
        dojo.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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box. 


7.1 Using a PHP Server 


<?php
  /*
  * HelloWorldResponsePOST.php
  * --------
  *
  * Print the name that is passed in the
  * 'name' 
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 


            
            
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: 


            
            
<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>





            
            


            
            
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: 


            
            
    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>





            
            


            
            
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: 


            
            
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





            
            


            
            
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: 


            
            
    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





            
            


            
            
To be: 


            
            
    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





            
            


            
            
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: 


            
            
    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>





            
            

            
            


            
            
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!');
        else
          alert(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: 


            
            
    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>





            
            


            
            
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.<type> 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: 


            
            
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





            
            


            
            
to: 


            
            
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 


            
            
<?php
  /*
  * HelloWorldResponseGET.php
  * --------
  *
  * Print the name that is passed in the
  * 'name' 
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 


               
               
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: 


               
               
<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>





               
               


               
               
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: 


               
               
    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>





               
               


               
               
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: 


               
               
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





               
               


               
               
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: 


               
               
    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





               
               


               
               
To be: 


               
               
    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





               
               


               
               
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: 


               
               
    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>





               
               

               
               


               
               
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!');
        else
          alert(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: 


               
               
    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>





               
               


               
               
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.<type> 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: 


               
               
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





               
               


               
               
to: 


               
               
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 


               
               
___FCKpd___19


              
              




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 


<!---
  /*
  * HelloWorldResponseGET.cfm
  * --------
  *
  * Print the name that is passed in the
  * 'name' GET parameter in a sentence
  */
--->
<cfsetting showDebugOutput="No">
Hello, #url.name#, welcome to the world of Dojo!
</cfsetting>







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: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="name">







to: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    <form id="myForm" method="POST">
      Please enter your name: <input type="text" name="name">
    </form>







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 server
        dojo.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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box. 


7.1 Using a PHP Server 


___FCKpd___28




            
            


            
            
7.2 Using an ASP Server 


            
            
___FCKpd___29


           
           




7.3 Using a ColdFusion Server 


<!---
  /*
  * HelloWorldResponsePOST.cfm
  * --------
  *
  * Print the name that is passed in the
  * 'name' POST parameter in a sentence
  */
--->
<cfsetting showDebugOutput="No">
Hello, #form.name#, welcome to the world of Dojo!
</cfsetting>







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";
 





       
       

GET parameter in a sentence
  */

  header('Content-type: text/plain');
  print "Hello {
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 


        
        
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: 


        
        
<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>





        
        


        
        
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: 


        
        
    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>





        
        


        
        
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: 


        
        
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





        
        


        
        
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: 


        
        
    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





        
        


        
        
To be: 


        
        
    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





        
        


        
        
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: 


        
        
    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>





        
        

        
        


        
        
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!');
        else
          alert(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: 


        
        
    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>





        
        


        
        
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.<type> 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: 


        
        
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





        
        


        
        
to: 


        
        
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 


        
        
___FCKpd___19


       
       




6.2 Using an ASP Server 


___FCKpd___20




     
     


     
     
6.3 Using a ColdFusion Server 


     
     
___FCKpd___21


    
    




6.4 Using a Java Server (JSP) 


___FCKpd___22






6.5 Using a Perl Server 


___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET['name']}, welcome to the world of Dojo!/n"; ?>

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
POST parameter in a sentence */ header('Content-type: text/plain'); print "Hello {

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

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: 

<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>

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: 

    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>

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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

To be: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>


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!');
        else
          alert(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: 

    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>

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.<type> 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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

to: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 

<?php
  /*
  * HelloWorldResponseGET.php
  * --------
  *
  * Print the name that is passed in the
  * 'name' 
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 


    
    
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: 


    
    
<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>





    
    


    
    
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: 


    
    
    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>





    
    


    
    
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: 


    
    
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





    
    


    
    
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: 


    
    
    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





    
    


    
    
To be: 


    
    
    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





    
    


    
    
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: 


    
    
    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>





    
    

    
    


    
    
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!');
        else
          alert(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: 


    
    
    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>





    
    


    
    
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.<type> 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: 


    
    
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





    
    


    
    
to: 


    
    
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 


    
    
___FCKpd___19


   
   




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 


<!---
  /*
  * HelloWorldResponseGET.cfm
  * --------
  *
  * Print the name that is passed in the
  * 'name' GET parameter in a sentence
  */
--->
<cfsetting showDebugOutput="No">
Hello, #url.name#, welcome to the world of Dojo!
</cfsetting>







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: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="name">







to: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    <form id="myForm" method="POST">
      Please enter your name: <input type="text" name="name">
    </form>







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 server
        dojo.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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box. 


7.1 Using a PHP Server 


___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET parameter in a sentence */ header('Content-type: text/plain'); print "Hello {

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

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: 

<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>

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: 

    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>

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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

To be: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>


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!');
        else
          alert(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: 

    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>

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.<type> 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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

to: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 

___FCKpd___19

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET['name']}, welcome to the world of Dojo!/n"; ?>

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
POST['name']}, welcome to the world of Dojo!/n"; ?>

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET parameter in a sentence */ header('Content-type: text/plain'); print "Hello {

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

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: 

<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>

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: 

    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>

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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

To be: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>


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!');
        else
          alert(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: 

    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>

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.<type> 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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

to: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 

___FCKpd___19

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET['name']}, welcome to the world of Dojo!/n"; ?>

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
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 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET parameter in a sentence */ header('Content-type: text/plain'); print "Hello {

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

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: 

<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>

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: 

    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>

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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

To be: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>


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!');
        else
          alert(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: 

    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>

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.<type> 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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

to: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 

___FCKpd___19

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET['name']}, welcome to the world of Dojo!/n"; ?>

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
POST parameter in a sentence */ header('Content-type: text/plain'); print "Hello {

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

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: 

<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>

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: 

    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>

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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

To be: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>


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!');
        else
          alert(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: 

    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>

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.<type> 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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

to: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 

<?php
  /*
  * HelloWorldResponseGET.php
  * --------
  *
  * Print the name that is passed in the
  * 'name' 
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 


    
    
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: 


    
    
<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>





    
    


    
    
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: 


    
    
    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>





    
    


    
    
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: 


    
    
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





    
    


    
    
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: 


    
    
    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





    
    


    
    
To be: 


    
    
    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>





    
    


    
    
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: 


    
    
    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>





    
    

    
    


    
    
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!');
        else
          alert(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: 


    
    
    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>





    
    


    
    
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.<type> 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: 


    
    
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>





    
    


    
    
to: 


    
    
    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 


    
    
___FCKpd___19


   
   




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 


<!---
  /*
  * HelloWorldResponseGET.cfm
  * --------
  *
  * Print the name that is passed in the
  * 'name' GET parameter in a sentence
  */
--->
<cfsetting showDebugOutput="No">
Hello, #url.name#, welcome to the world of Dojo!
</cfsetting>







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: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="name">







to: 


    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    <form id="myForm" method="POST">
      Please enter your name: <input type="text" name="name">
    </form>







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 server
        dojo.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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box. 


7.1 Using a PHP Server 


___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET parameter in a sentence */ header('Content-type: text/plain'); print "Hello {

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

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: 

<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>

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: 

    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>

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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

To be: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>


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!');
        else
          alert(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: 

    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>

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.<type> 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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

to: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 

___FCKpd___19

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET['name']}, welcome to the world of Dojo!/n"; ?>

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
POST['name']}, welcome to the world of Dojo!/n"; ?>

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET parameter in a sentence */ header('Content-type: text/plain'); print "Hello {

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

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: 

<html>
  <head>
    <title>Dojo: Hello World!</title>

    <!-- SECTION 1 -->
    <script type="text/javascript" src="js/dojo/dojo.js"></script>
  </head>

  <body>
  </body>
</html>

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: 

    <!-- SECTION 2 -->
	<script type="text/javascript">
            // Load Dojo's code relating to widget managing functions
            dojo.require("dojo.widget.*");

            // Load Dojo's code relating to the Button widget
            dojo.require("dojo.widget.Button");
	</script>

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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

To be: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
        dojo.require("dojo.event.*");
	dojo.require("dojo.widget.*");
	dojo.require("dojo.widget.Button");
    </script>

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: 

    <!-- SECTION 2 -->
    <script type="text/javascript">
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
      dojo.require("dojo.widget.Button");

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

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

      dojo.addOnLoad(init);
    </script>


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!');
        else
          alert(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: 

    <!-- SECTION 3 -->
    <script type="text/javascript">
      dojo.require("dojo.io.*");
      dojo.require("dojo.event.*");
      dojo.require("dojo.widget.*");
	  dojo.require("dojo.widget.Button");

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

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

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

      dojo.addOnLoad(init);
    </script>

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.<type> 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: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>

to: 

    <button dojoType="Button" widgetId="helloButton">Hello World!</button>
    <br>
    Please enter your name: <input type="text" id="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 server
        dojo.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 <name>, welcome to the world of Dojo!' where <name> 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 

___FCKpd___19

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
GET['name']}, welcome to the world of Dojo!/n"; ?>

6.2 Using an ASP Server 

___FCKpd___20

6.3 Using a ColdFusion Server 

___FCKpd___21

6.4 Using a Java Server (JSP) 

___FCKpd___22

6.5 Using a Perl Server 

___FCKpd___23

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: 

___FCKpd___24

to: 

___FCKpd___25

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

___FCKpd___26

to: 

___FCKpd___27

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 <name>, welcome to the world of Dojo!' where <name> is the name you entered into the text box.

7.1 Using a PHP Server 

___FCKpd___28

7.2 Using an ASP Server 

___FCKpd___29

7.3 Using a ColdFusion Server 

___FCKpd___30

7.4 Using a Java Server (JSP) 

___FCKpd___31

7.5 Using a Perl Server 

___FCKpd___32
babydavic
关注
  • 0
    点赞
  • 踩
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
Dojo-China.zip_chinadojo1688_dojo_dojo 实战_dojo中文网
09-22
Dojo中文手册——实战dojo工具包。一个品质远远超出“原型建造”的Ajax库。
Dojo入门三种HelloWorld!
huidaoli
10-15 1414
学习Dojo有些时间了，也整理了一些资料，先来个最入门级别的。HelloWorld Asp.Net+Dojo Dojo事件绑定，弹出HelloWorld [html]view plaincopyprint? <%@PageLanguage="C#"AutoEventWireup="true"CodeBehind="HelloWorldDojo.aspx.cs"Inhe...
dojo入门2_helloworld
gaoyadong1的博客
09-27 132
上一篇谈了dojo的环境配置，现在我们可以来开始动手写一个dojo的helloworld程序了，代码如下图： Insert title here @import "js/dojo-1.6.1/dijit/themes/tundra/tundra.css"; @import "js/dojo-1.6.1/dojo/resources/dojo.css" ...
用 Zend_Dojo 实现 captcha 图片切换
小落敲代码。
09-08 831
当我们实现诸如会员注册功能时，通常会给出一个验证码和输入框，要求用户输入，以确认该用户的有效性。 这个功能在 Zend Framework 里面由 Zend_Captcha 组件提供，特别是 Zend_Captcha_Image，它允许用户把验证码用图片的形式展示出来。 如下图 ： 以下我要实现的就是，当我们点击上面图片时，图片会自
Dojo学习和常用知识
Web3 & Basketball
07-29 930
Dojo 是一个流行的 JavaScript 库，用于开发 Web 应用程序。它提供了许多功能，如 DOM 操作、事件处理、动画效果、数据存储和许多其他实用功能。在今天的 Web 开发中，Dojo 仍然被广泛使用，尤其是在企业级应用程序开发中。下面是一个详细的 Dojo 详解，包括代码实例。
Srs.rar_dojo1.2 servlet_srs
09-21
用最近的dojo1.2.1制作前端的ajax购书网站，分注册用户购物和非注册用户购物两部分（其实非注册用户只是个噱头），一个页面完成所有必要功能，页面颜色有点难看，管理员部分没有做。后端为servlet+ms sqlserver2k,...
flutter_dojo
04-09
flutter_dojo 一个新的Flutter项目。 入门 该项目是Flutter应用程序的起点。 如果这是您的第一个Flutter项目，那么有一些资源可以帮助您入门： 要获得Flutter入门方面的帮助，请查看我们的，其中提供了教程，示例...
JsPlumb_Dojo_Integreate
04-30
此版本的状态此版本包括部分转换为AMD和部分正常运行的Dojo版本。 jQuery和YUI版本使用requireJs，而Dojo版本使用Dojo的AMD库。 但是，存在许多未解决的问题： jsPlumb使用许多全局变量，这与AMD风格的编程相反。 ...
Coding_Dojo_Web_Fundamentals
04-12
“＃Coding_Dojo_Web_Fundamentals”
【300套】基于Springboot+Vue的Java实战开发项目(附源码+演示视频+LW)
2301_77929200的博客
04-12 1383
🧡今天给大家分享300+的Java毕业设计，基于Springboot+vue框架，这些项目都经过精心挑选，涵盖了不同的实战主题和用例，可做毕业设计和课程设计参考。✍️除了源码，对于大部分项目实现的功能都有相应的介绍，并且配有演示视频，方便大家根据自己的需要择优下载学习。💂另外如有定制需求或者想要相对应的论文参考，文末可以十我VX联系。🤝后续还会持续更新，欢迎关注！
js的filter函数
xiaohua0708day的博客
04-14 236
这个函数接收数组中的每个元素作为参数，并检查该元素是否是偶数。如果是偶数，函数返回。是一个数组方法，它创建一个新数组，其包含通过提供的函数实现的测试的所有元素。函数遍历数组中的每个元素，并只将那些使测试函数返回。在这个箭头函数版本中，我们直接返回了表达式。在上面的代码中，我们传递了一个匿名函数给。方法就会将该元素包含在新数组中。，则该元素会被包含在新数组中。在JavaScript中，的元素包含在新数组中。
TS基础2-常用类型
qq_40147756的博客
04-12 392
ts 中常用类型和举例说明。
【可视化大屏开发】19. 加餐-百度地图API实现导航加线路热力图
pblh123的专栏
04-17 456
Web端使用场景中会涉及到地图导航路线情况，并利用热力图显示路况信息。实现效果如下：输入起始地点，选择并开始导航最终效果。
Day08React——第八天
最新发布
gu644335363的博客
04-17 668
概念：自定义Hook 是use打头的函数，通过自定义hook函数实现逻辑的封装复用声明一个以use打头的函数把函数体内可复用的逻辑(只要是可复用的逻辑)把组件中用到的状态或方法回调return出去组件调用结构赋值show);
echarts tooltip提示框显示不全
在职可交流前端开发，包括：web端、uniapp等，欢迎指教。
04-11 527
一个可由多个柱形图叠加而成的图表，命名为someHoverLine(可自定义)。 下面罗列了移动端和web端的封装组件代码； 展示了vue2、uniapp、vue3的不同封装和使用案列。
【vue】v-bind动态属性绑定
m0_63070489的博客
04-11 433
【vue】v-bind动态属性绑定
创建组件的10条准则
m0_52617844的博客
04-11 1041
基于Springboot的笔记记录分享网站（有报告）。Javaee项目，springboot项目。
XING的博客
04-11 732
基于Springboot的笔记记录分享网站（有报告）。Javaee项目，springboot项目。数据库作为系统数据储存平台，实现了基于B/S结构的Web系统。界面简洁，操作简单。采用M（model）V（view）C（controller）三层体系结构，通过。
dojo request get 接收 html
06-06
您可以使用以下代码来使用 Dojo 发送 GET 请求并接收 HTML 响应： ```javascript require(["dojo/request"], function(request){ request.get("http://example.com/mypage.html", { handleAs: "text" }).then(function(response){ console.log(response); // 打印 HTML 响应 }, function(error){ console.log(error); // 打印错误信息 }); }); ``` 在这个例子中，我们使用 Dojo 的 `request` 模块发送了一个 GET 请求到 `http://example.com/mypage.html` 并将响应作为文本处理。在 `then` 方法中，我们输出了响应内容，或者在发生错误时输出错误信息。 请注意，由于浏览器的安全限制，您只能从与您的 JavaScript 代码在同一个域的服务器上接收响应。如果您需要从其他域接收响应，您需要使用 JSONP 或 CORS 等技术。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值