dhtmlxFolders. Quick Start.

Building Image Explorer Application

1. Necessary files

We start with including of necessary files into the page where we are going to use dhtmlxFolders. What are the files? They are, in minimum case:

dhtmlxcommon.js - DHTMLX common file (this file is necessary for all components of dhtmlx lib)
dhtmlxfolders.js - dhtmlxFolders library file
dhtmlxfolders.css - dhtmlxFolders styles

All mentioned files are in codebase folder inside the package you’ve downloaded from site or got with Professional Edition License. So the code we add to our page is like the following (expecting we are in the folder dhtmlxFolder/samples/image_explorer, when library files are in dhtmlxFolder/codebase):

You’ll also need images, xml and thumbnail creators for this sample. All these files can be found in the same folder where this document is located.

2. Initializing Folders on the page

Now you need to create container for folders on your page. As far as I plan image navigation area will be on the left side of the screen and image preview on the right side, I place one DIV element with float:left to use as Folders container and one IMG element after it for image preview.

<h1>dhtmlxFolders. Step-by-step tutorial</h1>

</body>

Now, as we have container for folders we can initiate dhtmlxFolders object based on this container:

var myFolders;

function doOnLoad(){

myFolders = new dhtmlxFolders(“folders_container”);

}

</script>

After you load the page with this code you’ll see nothing, as object was just initiated but wasn’t haven’t got any content.

3. Add content to Folders

There are at least three ways to add content to dhtmlxFolders Object:

a. load content from XML

b. load content from json object

c. add content with script

Here I’ll demonstrate the way which is useful as for simple content as for complex content – XML. As far as we are going to show images stored on the disc and their number and instances can vary, we can’t just create static XML file and use it – we need to get up-to-date information, so we need to output XML each time we get a request. Here is PHP sample of the code which outputs XML which contains most actual information about jpg, gif and png files stored in the directory where it is located. Save this code in ./photos/getPhotos.php (expecting you have necessary photos in ./photos/ folder)

<?php

if ( stristr($_SERVER["HTTP_ACCEPT"],"application/xhtml+xml") ) {

header("Content-type: application/xhtml+xml"); } else {

header("Content-type: text/xml");

}

echo("<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>\n");

echo("<data>");

$dirToScan = dirname(__FILE__);

$files = scandir($dirToScan);

if($files!=false && count($files)>0){

$i=0;

foreach($files as $file) {

//output all files which have jpg, gif or png extension

preg_match("/(\.(jpg)|(gif)|(png))$/i",$file,$matches);

if(count($matches)>0){

$fileFullPath = $dirToScan."/".$file;

$mtimeArray = getdate(filemtime($fileFullPath));

//file size in bytes

$fsize = filesize($fileFullPath);

//format date as yyyy-m-d hh:mm:ss

$fdate = sprintf("%04s-%02s-%02s %02s-%02s-%02s", $mtimeArray["year"],$mtimeArray["mon"],$mtimeArray["mday"],$mtimeArray["hours"],$mtimeArray["minutes"],$mtimeArray["seconds"]);

//item ID

$fid = $i;

//output item

print("<item name='".$file."' id='".$fid."'>");

print("<filesize>".$fsize."</filesize>");

print("<modifdate>".$fdate."</modifdate>"); print("</item>");

$i++;

}

echo("</data>");

Format of XML dhmlxFolders expects depends on the type of item you are going to use. All types we are going to use in this sample expect the following format:

<data>

</item>

…

</item>

</data>

Where:

item – tag which represents each image file

name attribute – file name

id attribute – unique item identifier (if doesn’t exist, it will be generated by dhtmlxFolder)

filesize – tag which contains size of file in bytes

modifdate – tag which contains date of file last modification

To load data from xml and show it with dhtmlxFolders, I add two lines of code to doOnLoad function and it looks like this after that:

function doOnLoad(){

myFolders = new dhtmlxFolders(“folders_container”);

myFolders.setItemType("ficon");

myFolders.loadXML("./photos/getPhotos.php","../../codebase/types/ficon.xsl");

}

setItemType tells Folders what item parser to use, loadXML points it to xml file to get data from and xsl file associated with previously set type “ficon”. See documentation for list of predefined types and associated xsl file.

When you load the page you get something similar to this:

4. Switching to another item type

One of the main advantages of dhtmlxFolders is the possibility to define any kind of item appearance keeping general functionality – organization, selection control, events, drag-n-drop, paginal output. Moreover you can switch to another type keeping same datasource. Here is how to do this.

First of all let’s add some switches to the page. We’ll use 3 types for this demo. So, I’ll define 3 switches:

<span onclick="changeType('tiles')">Tiles</span> |

<span onclick="changeType('icons')">Icons</span> |

<span onclick="changeType('table')">Table</span>

</div>

Each switch calls same function named changeType with different value specifying desired type of items to use in dhtmlxFolders. Here is the code for this function. Place it inside <script> block:

function changeType(typeName){

switch(typeName) {

case "tiles" :

myFolders.setItemType("ftiles", "../../codebase/types/ftiles.xsl");

break;

case "icons" :

myFolders.setItemType("ficon", "../../codebase/types/ficon.xsl");

break;

case "table" :

myFolders.setItemType("ftable", "../../codebase/types/ftable.xsl");

break;

}

So, what we have in it. Most interesting thing is myFolders.setItemType with two incoming arguments. First is type name (see docs for available predefined types, their names and associated xsl files), second is xsl file associated with this type. Calling method this way you tell Folders to keep existing data and apply new style.

5. Add Event handler

To interact with user you can use events system. In current sample we need to show image when user clicks on corresponding item. Here is the function which will show image. Incoming argument is ID of Folders item:

function previewImage(itemId){

var imgObj = document.getElementById("myimage");

var dataObj = myFolders.getItem(itemId).data.dataObj;

var fileName = dataObj.getAttribute("name");

imgObj.src = "./photos/"+fileName;

imgObj.style.visibility = "visible";

}

Where myFolders.getItem(itemId).data.dataObj is script statement to get access to item data object, which is item XML node. To get file name of the image we get value of attribute “name” of this node.

To attach this function to myFolders as onclick event handler we need to use attachEvent method. Place this inside doOnLoad function, which will finally look this way:

function doOnLoad(){

myFolders = new dhtmlxFolders("folders_container");

myFolders.setItemType("ficon");

myFolders.attachEvent("onclick",previewImage)

myFolders.loadXML("./photos/getPhotos.php","../../codebase/types/ficon.xsl");

}