Tutorial Time (again)! I just finished a background for my new game and recorded the steps. So if you’re interested to draw things like this (this is a motel room):

Keep on reading

First of all: This is not a tutorial about how to use paint programs, some basic knowledge in whatever application you use is needed.

There’re two common methods to start on low res background – you begin with a hand drawn sketch and scan it. Or you directly start from the scratch – without a template.

For this screen, I made a rough sketch on paper but drew it completely on the computer (no tablet). For the first 2 steps, I’ve used Pro Motion, but shading and anti aliasing has been done in Photoshop 6 (which runs fast enough on this old machine). If you need  8-bit color depth, then keep sticking to ProMotion (or whatever you like), otherwise Photoshop (or Gimp) is a real time saver.

1. Step – Outline the scene

I’ve tried to chose an interesting perspective with lot’s of sloping lines. The blue line’s the horizont, the red dots are the two vanishing points. Because it’s a quite boring to just look in a corner, I’ve added a ledge to the wall (maybe there’s a chimney on the other side or whatever ).

Now I’ve moved the scenery a little and added a ceiling – since this is going to be motel room and not a hallway. There’s also a window with curtains.

Now there’s also a table and a bed. I’ve used flashy colors to see if the composing is good and making painting over it easier.

The next station is a tv and a little detail on the carpet (at this point it also could have been a wooden floor). All the objects I’ve outlined so far are static objects. In the later game you can’t move them aroung, pick them up or anything alse. This is important for the shading because if you would have been able to move the table, you also had to move its shadow.

Step 2 – Basic coloring

Let’s bring some colors to the scene. First I’ve added a lamp to have a primary lightsource. ProMotion is really good in adding old school gradients and so I’ve chosen a goldish yellow and colored the wall. Unfortunately I did it wrong

Note the light on the ledge and the left wall. It’s impossible for the lamp to create that shadow – fortunately this has been fixed on the next image. Finding a color (and a texture) for the carpet gave me a hard time, so I ended up searching google for motel rooms. Most of them had red ones, so I also chose it until I realized that it’s damn ugly – so where the motel rooms btw

So for the next version I’ve used red for the table and a more convenient grayish blue for the carpet. Those color ideas were from an Ikea catalog

I’ve also fixed the gradients on the wall to look more natural and colored the bed and the TV. The bedsheet is actually the one I’ve currently use. As a hint – be creative choosing colors and textures. Here’s how you shouldn’t do it: White wallpaper, brown table, white bed, gray sheets, no curtains at the window and an inconspicuous color for the carpet.

Even if realitiy isn’t that colorful – most of us play games to forget about reality

Those white parts in the image are actually transparent, so the carpet doesn’t get white on the bottom of the screen.

Step 3 – Objects

I’ve added a new layer in ProMotion and added some objects to this quite naked room. Here are the objects without their background.

In case you don’t know what to add in a room, just think. A TV need something so you can watch it – voila: armchair in front of the TV and so on.

So here we have a door, some pictures, a pile of dirt, an armchair and a phone with a clipboard. For those objects I’ve created outlines again, just like in step 1 and some basic coloring.

Step 4 – Details, shading and the finishing touch

Here’s how it looks, if the objects are on the background. I also adjusted the color a little. Since I’m now in Photoshop, this is rather easy.

I’ve now added a slight vignette to draw the attention more to the center of the room. Note that the lamp is now lighter and the corners get darker.

Also the wallpaper looked quite boring, so I’ve decided to add some stripes – it’s never good to have large areas in the same color (search for a “tv lines” tutorial, if you don’t know how to do it).

There’s also glas in the window frame now.

The next part might be the hardest part for some of you – adding shadows. Just look at the light source and try to imagine where the light might hit the ground or where it might be blocked. Adding shadows in photoshop is quite easy (and there are a lot tutorials about it). I’ve used an additional layer, positioned it under the object layer and drew 100% black areas. Then I’ve applied a slight motion blur and set the layer’s opacity to about 30%. For the shadow on the carpet (it gets darker, the more it’s away from the lamp) I’ve used a seperate layer and made it completely black. Then I’ve added a layer mask and added a gradient from black to white on it – done

But as I’ve written above, there are far more better tutorials, covering shadows.

The last thing I did is to add some noise on rough surfaces – like the carpet and the arm chair.

And that’s it – it might not be perfect and there’s always room for improvements. But try not to dissipate your energies just to one screen. I’m sure, there will be a lot more you have to draw and in my oppinion it’s better to have some mediocre screens but a finished game instead of 2 perfects screens and a canceled project

So long, I hope you liked it!

Now we’re dealing with that grid. Finally, since we’ve been kept busy with the basics so far

3.6 dojo.grid in javascript

After search for the name “Petersen”, the webserver returns a JSON-String, containing all people with this name. Our goal is now to process this data into a grid .

So let’s have a look at gridtut.js again.

Using the command “var result = eval(‘(‘+data+’)');” an array (or better a javascript object) is beeing created from the JSON-string and been saved in the variable “result”.

With this array, we can now populate the grid… but wait, there definately missing a grid :-O

Firstof all, we have to tell the grid, how many columns we want to use. This is called view in the world of dojo. Here’s the example for our view:

var view1 = {
	cells: [
		[
			{name: 'Customer_ID', field:'id'},
			{name: 'Given Name', field:'givname'},
			{name: 'Name', field:'surname'},
			{name: 'Job', field:'job'},
			{name: 'Age', field:'age'},
			{name: 'Action', get: linkInGrid}
		]
	]
};

The property cells contains an array (that why we use square brackets), containing small objects (curly brackets). The property “name” of those objects contains the title for the column header, the property “field” contains the name field of the data array we’re going to display.

Lazyness wants us to use global variables so we can access the grid (and the datastore) from all functions and we need a some sample data.

var ddata;
var grid;
var store;
var layout = [ view1 ];

var dummydata = { "identifier": 'id',
				   "items":[
				     {	"id": 0,
				     	"givname":"There is",
				      	"surname":"no data ",
				      	"job": "-",
				      	"age": 0}
				   ]
};

The dojo grid ist very flexible and supports rows, subrows and even subgrids.  The column-layout is defined by the variable “layout “(obviously ) and we use our just created view for that. The square brackets are mandatory by the way, because we have to use an array again.

The dummy data is usefull in two ways:

1) we can test the grid and exclude the webserver as an error source

2) the sample data is used an a message, that no data has been found. Also the grid only needs to be updated in the future, the creation has been done during the first call of the page.

For the sample data, we need the property “identifier” to tell the grid about our dataset’s primary key (or better: unique identifier)

The property “items” contains the datasets in an array.

Following function is going to create the grid:

function createGrid(myData) {

	store = new dojo.data.ItemFileReadStore({jsId: 'jsonStore',data: myData});

	ddata = new dojox.grid.data.DojoData(null,store,{jsId: 'model', clientSort: true, query: { id: '*' }});

	grid = new dojox.Grid({id: "OurGrid", model: ddata, onRowMouseOver: keepPopup});

	dojo.byId("gridContainer").appendChild(grid.domNode);

	grid.setStructure(layout);

	grid.startup();
}

A lot of stuff has been done here, so we better take a close look.

Line 2:
The first thing we do, is to create an ItemFileReadStore using the dojo data model. It gets the javascript id “jsonStore” (as I’ve told you, Dojo likes ids) . For the second parameter we pass our data array – to keep the function flexible, we use the variable mydata (the parameter in the function call).

Line 3:
Since we now have an ItemFileReadStore, we have to connect it with the grid. The grid knows two ways for the data connection: grid.data.DojoData and grid.data.Table.

Using the table object could be easier: Just pass some sample data without encapsulation in identifier and items. Just plain data, even an ItemFileReadStore isn’t necessary.

// easy but not userful for us...

ddata = new dojox.grid.data.Table(null, dummydaten);

Well, this is not too hard, but unfortunately not too useful So we have to use DojoData and pass our store to it. The property “clientSort”allows the user to sort the data locally with the browser. Looking at the property “query” show us it’s relationship to the database world. We’re telling the model to collect all unique record sets, using id as a primary key – somehow a client-side “SELECT *”.

Line 4:
Finally we create the grid itself. It gets an Id and we pass the store, as well as the model.

Line 5:
We also have the define the layout und use “setStructure” for that.

Line 6:
In part 1  we already defined a placeholder for the grid (that <div>-Container) and here we attach the grid to it.

Line 7:
At last it’s time to start the grid. Our just created function might come handy for this task

createGrid(dummydaten);

Only a little  bit of CSS is needed, we add to our html-file:

<style type="text/css">

 div.gridDiv {

 width: 600px;

 height: 450px;

 }

</style>

It is necessary to define the grid’s width, otherwise nothing is shown – this is a popular error source by the way.

If we’ve been good, the following is shown (depending on your language, of course):

More to come in the next part.

Here’s the second part of the dojo tutorial – covering an AJAX call and the answer from the webserver in PHP.

3.2 Step-2 Create a HTML-Form

Let’s have a closer look at the following code

<form name="form_search" id="form_search" action="gridtut_request.php" method="post">

<input type="text"
		name="txt_name"
		id="txt_name"
		value=""
        dojoType="dijit.form.TextBox"
        trim="true"
        propercase="true" /> 

<input type="submit" id="find" value="Find!" />
</form>

<br />

<div id="gridContainer" class="gridDiv"></div>

As you can see, we just use a textfield and a search button. Everything looks like we’re used to (well, except the textfield), and that’s good because the site is usable without javascript. We only use typical html element like <form> or <input>. When the browser loads the site, the dojo parser looks for the attribute “dojoType” (case sensitive) and decides which elements to be included. Dojo calls these elements dijits (Dojo Widgets).

Because those html elements are changed by the dojo parser, you could also use <div> or <span> tags. And it would be even faster, not to parse for html tags, but to generate them directly via Javascript. But in both ways the site wouldn’t be usable without javascript. And robots would find anything too.

Allright, back to the topic The form is followed by a <div>-Container, which is meant to be a placeholder for the grid.

We’re done for html, time to see some javascript!

3.3 Step-3 First javascript

Up for now, our tutorial looks a little disappointing. The file gridtut.js is totally empty, but we already called the function “init” from it, thus creating an error. We’re going to change that now!

// This function is called first

function init() {
	searchbutton = dojo.byId("find");
	// connect the submit button with the proper function
	searchbuttonConnection = dojo.connect(searchbutton, 'onclick', null, my_submit);

}

function my_submit(event) {

 dojo.stopEvent(event);

 alert('Yohoo!');

}

The function “init()” is called by dojo, as soon as the parser finished loading the site. By the way, the more code you have in your html-file, the longer it takes to parse it.

We now use the init-Function to replace the form’s standard submit with our own custom function. For this, dojo likes to use element ids, not names.

dojo.connect is used to connect the search button and the browser event “onclick” with our custom function, the last command “dojo.stopEvent(event)” is used to disable the standard submit.

For getting this to work, we need an additional parameter (I used “event”) in the parentheses of our new submit function.

Dojo.connects uses the parameter automatically,

Now if we did everything right, we should get an alert with “Yohoo!” instead of the submit

3.4 Step-4 Time for some AJAX.

Of course we want to use Ajax! Since it is one of the main reasons we use dojo and you can’t present a new project without it.

function my_submit (event) {

  dojo.stopEvent(event);

  var kw = {

    url: "gridtut_request.php",

    load: function(data){

   var result = eval('('+data+')');

  	  alert ("There is some data: " + data);

    },

    error: function(data){

   alert("An error occured: " + data);

    },

    form: "form_search"

  };

  dojo.xhrPost(kw);

}

Now this looks more complicated than it is.

First of all, KW is just a shortcut for keywords, but you can freely choose a different name. Most dojo functions accept javascript objects as parameter, so it’s very convenient to create an object with all needed parameters and pass it to “dojo.xhrPost” afterwards.

Here’s what we need to make an AJAX call.

URL:
Here we specify the location of our dynamic web site. This could also be .jsp or .asp – I try to keep the php specific part a small as possible.

LOAD:
When the webserver sends a response, this function is being called. Out of laziness I used an anonymous function without an own name. But you’re free to call a function which is buried somewhere else in the code. The parameter “data” contains the responded payload – for this example a JSON string.

ERROR:
Same as load, if we get an error, this function is being called.

FORM:
The form, we’re going to transmit (referenced by its id)

All these parameters are now packed in a single object (kw), which we are passing to “dojo.xhrPost”.

So what we did now, would have been already possible with pure html: sending a form to the webserver. But much more complicated

Being asynchronous and having error-handling makes the difference. Not to mention, that this code is very expandable.

3.5 PHP – Generate some JSON

For all friends of php, here’s some code creating a JSON string for us.

JSON, btw. means Javascript Object Notation and is one way, to exchange data between client and server (XML is the other popular way. Actually JSON is just a piece of javascript code which creates a javascript object once it is executed. So our PHP array is going to converted into a construction plan for a javascript object.

Important: The JSON string has to returned by echo, not by return. This is because the string has to be the response of the server.

<?php

	// some sample data
	$data = array ();

	$data[] = array ('id' =>1,
					 'surname' =>'Petersen',
					 'givname' =>'Bob',
					 'job' =>'cop',
					 'age' =>32);

	$data[] = array ('id' =>2,
					 'surname' =>'Petersen',
					 'givname' =>'Elvis',
					 'job' =>'dog catcher',
					 'age' =>25);

	$data[] = array ('id' =>3,
					 'surname' =>'Petersen',
					 'givname' =>'Peter',
					 'job' =>'	photographer',
					 'age' =>52);

	$data[] = array ('id' =>4,
					 'surname' =>'Petersen',
					 'givname' =>'Joe',
					 'job' =>'dike reeve',
					 'age' =>61);

	$data[] = array ('id' =>5,
					 'surname' =>'Schröder',
					 'givname' =>'Petra',
					 'job' =>'baker',
					 'age' =>31);

	$data[] = array ('id' =>6,
					 'surname' =>'Schröder',
					 'givname' =>'Elvira',
					 'job' =>'meat salesperson',
					 'age' =>23);

	$data[] = array ('id' =>7,
					 'surname' =>'Schröder',
					 'givname' =>'Martin',
					 'job' =>'cook',
					 'age' =>37);

	// the searchresult
	$result = false;
	// Array counter, since the JSON function need a clearly ordered array from zero on
	$counter = 0;

// main part
if (!empty($_REQUEST['txt_name'])) {

	// search for the data
	foreach ($data as $row => $value) {
		if ($value['surname'] == html_entity_decode($_REQUEST['txt_name'])){

			// first search hit
			if (!$result) $result = array();

			// put the search result into an array
			$result[$counter]['id'] = $data[$row]['id'];
			$result[$counter]['surname'] = htmlentities($data[$row]['surname']);
			$result[$counter]['givname'] = htmlentities($data[$row]['givname']);
			$result[$counter]['job'] = htmlentities($data[$row]['job']);
			$result[$counter]['age'] = $data[$row]['age'];
			$counter++;
		}
	}

	// empty search result
	if (!$result) $result[] = array ('id' =>0,
					'surname'=>'found',
					'givname'=>'No data',
					'job' =>' ',
					'age' =>0);

        $temp = Array ('identifier'=>'id', 'items'=>$result);
	echo json_encode($temp);

}
?>

So we’re searching for the given name and return the result as JSON. Of course this looks a little different in jsp or asp.

It’s good to know, that PHP’s JSON function can’t handle foreign characters, so I convert everything html entities (auml instead of ä).

If you start a new project (or are already using it), converting to UTF-8 makes your dojo life a lot easier. Unfortunately I still have to work with ISO-885-91.

Here’s how a JSON string should look like (having searched for Petersen):

{"identifier":"id","items":[{"id":1,"surname":"Petersen","givname":"Bob","job":"cop","age":32},{"id":2,"surname":"Petersen","givname":"Elvis","job":"dog catcher","age":25},{"id":3,"surname":"Petersen","givname":"Peter","job":"\tphotographer","age":52},{"id":4,"surname":"Petersen","givname":"Joe","job":"dike reeve","age":61}]}

I you don’t have a webserver handy, you can also copy and paste this string to a textfile and using it as the response.

Hi there, this tutorial is about the dojo toolkit and how to generate a grid. Since I haven’t found a guide which covers all the basics from including dojo, over AJAX to server-side communication, I’ve decided to write it myself.

Okay then, let’s start.

1. Ingredients

We’re going to need 3 to 4 files:

• a HTML file
• a javascript file for organization and code seperation
• a dynamic web language file (I’m only good at PHP) for the data to be loaded into the grid
• optional: a html-Datei for a popup

Furthermore need the current version of the dojo toolkit (v.1.02). Also friends of IE better fetch a nightly build, but don’t worry, we’ll do that together.

btw. As dojo 1.1 is released, you won’t need the nightly build anymore

2. Preparation

2.1 Download dojo

Here’s the download <klick>. If version 1.02 is still the current version, we need a nightly build in order to deal with some nasty bugs (grid’s not shown in IE): <klick>.

2.2 Folderstructure

First we create a main folder, which is accessible to Apache (or iis).

We extract the dojo’s archive in a sub folder, e.g. dojotoolkit-release-1.0.2.

It has proven itself in practice (okay, in my practise ) to keep the release number in the foldername. So if you want to switch the release later on, it much easier to manage.

Now extract the nightly build somewhere else and copy the folder called dojox into the dojotoolkit-release-1.0.2 folder. That’s how it looks like:

/gridtutorial

|---+ dojo-release-1.0.2

       |--- dijit

       |--- dojo

       |--- dojox    (from the nightly build)

       |--- util

Let’s create our 4 file then:

gridtut.html

gridtut.js

gridtut_request.php

gridtut_pop.html

Okay, popups are clearly out of style and the dojo.dialog would be a very nice replacement, but a big challenge is to integrate dojo into existing projects. Furthermore, this is example should be still usable without javascript.

3.1 Step-1 Setup Dojo

I think it’s time to see some code

I suppose, everybody knows how to create a HTML file, so we start directly including dojo to our site.

First, we nees CSS files for the <head> Tag:

<link rel="stylesheet" href="./dojo-release-1.0.2/dijit/themes/tundra/tundra.css" type="text/css">

<link rel="stylesheet" href="./dojo-release-1.0.2/dojo/resources/dojo.css" type="text/css">

<link rel="stylesheet" href="./dojo-release-1.0.2/dojox/grid/_grid/tundraGrid.css" type="text/css">

Hereby we’ve defined the look of all dojo widgets.. err dijits. In order to have the grid look like the rest, we also include tundraGrid.css.

Second, we include dojo itself as javascript files.

<script type="text/javascript" src="./dojo-release-1.0.2/dojo/dojo.js"

 djConfig="parseOnLoad: true,debugAtAllCosts: true"></script>

All depending files are included by dojo itself, but we have some parameters to configure:

parseOnLoad - in order to create dojo widgets by html markup, we need a parser

debugAtAllCosts - for development, debugging can't be wrong, although you should disable it in a production environment

The next things is to tell dojo, what modules we’re going to use for our example.

<script  type="text/javascript">

 dojo.require('dojo.parser');

 dojo.require("dojo.data.ItemFileReadStore");

 dojo.require('dijit.form.Button');

 dojo.require("dijit.form.TextBox");

 dojo.require("dijit.form.NumberTextBox");

 dojo.require("dijit.form.FilteringSelect");

 dojo.require("dojox.grid.Grid");

 dojo.require("dojox.grid._data.model");

</script>

Unfortunately this portion of javascript cannot be included in the .js file we reserved for that, otherwise the path for inclusion of those files gets messed up. You can already see, that we’re also cover some form dijits later on

The final part:

<script type="text/javascript" src="gridtut.js"></script>

<script type="text/javascript">

 dojo.addOnLoad(init);

</script>

Okay, we’re ready. The order of those ports is quit important, by the way. The file gridtut.js is going to contain the function “addOnLoad” and so we can only call the function after it has been loaded.

So, that’s it for the first part. Thanks for reading.

UNDER CONSTRUCTION

This tutorial is separated into six parts and is going to explain how to setup dojo, fill a grid from the server side and open popups from the grid. In addition the site is kept usable without javascript.

Here’s an example how it should look like. If this is not what you’ve been looking for, there’s still time to leave

http://www.sonores.de/dojo_tutorial/gridtut_en/gridtut.html
(search for Petersen or Schröder if you have that char)

I tried to keep the tutorial very common, so that you don’t need much dojo experience. However a glimpse into the documentation won’t hurt you.
http://dojotoolkit.org/book/dojo-book-1-0

Here’s the result of what the code will look like after the tutorial (dojo has still to be downloaded), the code is fully commented (and translated )

Grid Tutorial en.zip

But now enjoy the show

Part 1:
We’ll cover the basics here: downloading dojo and including it into our site
http://blog.sonores.de/2008/02/29/dojo-tutorial-with-a-grid-part-1-english-version/

Part 2:
We’ll create a form and connect the HTML-Elements with the event-system. After that we talk to the server via AJAX and let it answer in JSON (done in PHP)
http://blog.sonores.de/2008/03/05/dojo-tutorial-with-a-grid-part-2-english-version/

Part 3:
Now we put some sample data into the grid (and create it before that)

http://blog.sonores.de/2008/03/14/dojo-tutorial-with-a-grid-part-3-english-version/

Part 4:
Having the sampledata shown in the grid, it’s time to populate it with server-side data. Also we try to avoid problems with foreign characters and AJAX
(not translated yet)

http://blog.sonores.de/2008/02/12/dojo-tutorial-mit-grid-teil-4/

Part 5:
We add an activity-indicator and make use of the event system’s listener-conecpt.
(not translated yet)

http://blog.sonores.de/2008/02/13/dojo-tutorial-mit-grid-teil-5-events/

Part 6:
Last but not least we generate links with grid’s get-function
(not translated yet)

http://blog.sonores.de/2008/02/13/dojo-tutorial-mit-grid-teil-6-links-im-grid/

Part 6 1/2:
In order to keep our example working with PHP < 5.2.0. here’s the solution
(not translated yet)
http://blog.sonores.de/2008/02/13/dojo-tutorial-mit-grid-teil-6-12-json-mit-php-4/