转:dojo 的实例 HelloWorld

    技术2022-05-11  12

    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'

    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'

    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'

    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'

    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'

    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'

    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'

    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___573

    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'

    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'

    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'

    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'

    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'

    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'

    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'

    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'

    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___573

    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___582

    7.2 Using an ASP Server

    <% ' ' HelloWorldResponsePOST.asp ' -------- ' ' Print the name that is passed in the ' 'name'

    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'

    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'

    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'

    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'

    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'

    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'

    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'

    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___573

    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'

    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'

    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'

    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'

    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'

    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'

    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'

    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'

    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___573

    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___582

    7.2 Using an ASP Server

    ___FCKpd___583

    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 {

    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'

    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'

    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'

    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___573

    6.2 Using an ASP Server

    ___FCKpd___574

    6.3 Using a ColdFusion Server

    ___FCKpd___575

    6.4 Using a Java Server (JSP)

    ___FCKpd___576

    6.5 Using a Perl Server

    ___FCKpd___577

    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___578

    to:

    ___FCKpd___579

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

    ___FCKpd___580

    to:

    ___FCKpd___581

    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___582

    7.2 Using an ASP Server

    ___FCKpd___583

    7.3 Using a ColdFusion Server

    ___FCKpd___584

    7.4 Using a Java Server (JSP)

    ___FCKpd___585

    7.5 Using a Perl Server

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

    6.2 Using an ASP Server

    ___FCKpd___574

    6.3 Using a ColdFusion Server

    ___FCKpd___575

    6.4 Using a Java Server (JSP)

    ___FCKpd___576

    6.5 Using a Perl Server

    ___FCKpd___577

    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___578

    to:

    ___FCKpd___579

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

    ___FCKpd___580

    to:

    ___FCKpd___581

    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___582

    7.2 Using an ASP Server

    ___FCKpd___583

    7.3 Using a ColdFusion Server

    ___FCKpd___584

    7.4 Using a Java Server (JSP)

    ___FCKpd___585

    7.5 Using a Perl Server

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

    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'

    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'

    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'

    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'

    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'

    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'

    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'

    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___573

    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___582

    7.2 Using an ASP Server

    ___FCKpd___583

    7.3 Using a ColdFusion Server

    ___FCKpd___584

    7.4 Using a Java Server (JSP)

    ___FCKpd___585

    7.5 Using a Perl Server

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

    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'

    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'

    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'

    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___573

    6.2 Using an ASP Server

    ___FCKpd___574

    6.3 Using a ColdFusion Server

    ___FCKpd___575

    6.4 Using a Java Server (JSP)

    ___FCKpd___576

    6.5 Using a Perl Server

    ___FCKpd___577

    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___578

    to:

    ___FCKpd___579

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

    ___FCKpd___580

    to:

    ___FCKpd___581

    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___582

    7.2 Using an ASP Server

    ___FCKpd___583

    7.3 Using a ColdFusion Server

    ___FCKpd___584

    7.4 Using a Java Server (JSP)

    ___FCKpd___585

    7.5 Using a Perl Server

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

    6.2 Using an ASP Server

    ___FCKpd___574

    6.3 Using a ColdFusion Server

    ___FCKpd___575

    6.4 Using a Java Server (JSP)

    ___FCKpd___576

    6.5 Using a Perl Server

    ___FCKpd___577

    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___578

    to:

    ___FCKpd___579

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

    ___FCKpd___580

    to:

    ___FCKpd___581

    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___582

    7.2 Using an ASP Server

    ___FCKpd___583

    7.3 Using a ColdFusion Server

    ___FCKpd___584

    7.4 Using a Java Server (JSP)

    ___FCKpd___585

    7.5 Using a Perl Server

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

    7.2 Using an ASP Server

    ___FCKpd___583

    7.3 Using a ColdFusion Server

    ___FCKpd___584

    7.4 Using a Java Server (JSP)

    ___FCKpd___585

    7.5 Using a Perl Server

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

    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'

    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'

    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'

    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___573

    6.2 Using an ASP Server

    ___FCKpd___574

    6.3 Using a ColdFusion Server

    ___FCKpd___575

    6.4 Using a Java Server (JSP)

    ___FCKpd___576

    6.5 Using a Perl Server

    ___FCKpd___577

    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___578

    to:

    ___FCKpd___579

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

    ___FCKpd___580

    to:

    ___FCKpd___581

    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___582

    7.2 Using an ASP Server

    ___FCKpd___583

    7.3 Using a ColdFusion Server

    ___FCKpd___584

    7.4 Using a Java Server (JSP)

    ___FCKpd___585

    7.5 Using a Perl Server

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

    6.2 Using an ASP Server

    ___FCKpd___574

    6.3 Using a ColdFusion Server

    ___FCKpd___575

    6.4 Using a Java Server (JSP)

    ___FCKpd___576

    6.5 Using a Perl Server

    ___FCKpd___577

    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___578

    to:

    ___FCKpd___579

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

    ___FCKpd___580

    to:

    ___FCKpd___581

    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___582

    7.2 Using an ASP Server

    ___FCKpd___583

    7.3 Using a ColdFusion Server

    ___FCKpd___584

    7.4 Using a Java Server (JSP)

    ___FCKpd___585

    7.5 Using a Perl Server

    ___FCKpd___586   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___584

    7.4 Using a Java Server (JSP)

    ___FCKpd___585

    7.5 Using a Perl Server

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

    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'

    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'

    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'