just another developer

Zend Framework and DoJo

July 23, 2008 – 5:29 pm

I pretty much wet my self when ZF announced that they'd be integrating Dojo with the next iteration, and low and behold the first RC was made publicly available a few days ago. I literally dived in head first today, only to find the documentation was some what lacking.

I don't think the documentation is quite complete, but hats off to ZF for taking a step in the right direction.

Here's a quick tutorial on using Dojo's container's and pane's with ZF. I've added line breaks so it fits into the old blog.

Setting Up

Ok, so you're first step will be to enable your view to support Dojo.

Download the latest version of Dojo and copy it to your scripts folder (/html/scripts is where I put mine).

Unfortunately some of Dojo's files don't work with ZF's rewrite rules in .htaccess, you'll need to amend it to look like this.

 
      RewriteEngine on
      RewriteCond %{REQUEST_FILENAME} -f [NC,OR]
      RewriteCond %{REQUEST_FILENAME} -d [NC]
      RewriteRule .* - [L]
      RewriteRule !\.(js|ico|gif|jpg|png|css)$ index.php
 

This will prevent files that exist in the sites root folder from being re-written to index.php i.e. html files which the Dojo library requires.

Now you'll need to enable the Dojo through your controller, if you've extended Zend_Controller_Action stick this in your init method, else you can just put it in the init method for every controller that requires the Dojo library.

 
public function init(){
      Zend_Dojo::enableView($this->view);
}
 

In your layout template you will need to add the following lines of code to the head.

 
<?php
      if($dojo()->isEnabled()){
            $this->dojo()->setLocalPath('/scripts/dojo/dojo/dojo.js')
                  ->addStyleSheetModule('dijit.themes.nihilo');
            echo $this->dojo();
      }
?>
 

This will add all of the required DoJo JS files and include the theme style sheet you choose, "setLocalPath" is the path to your DoJo.js file in the scripts folder, and "addStyleSheetModule" is the theme you wish to use, you have a choice between nihilo, soria and tundra.

You will also need to add a class to your body with the name of the theme. i.e. if the theme you wish to use is nihilo, you add class="nihilo" to your body.

Creating a basic CMS frame

The ZF DoJo View Helper has several ways of rendering elements, I'll be showing you two methods in this example.

Hopefully you're using Zend Studio for Eclipse and have an index.phtml view ready to edit.

In this we'll start by creating a borderContainer, this will contain all of your "pane's". Pane's contain content, the borderContainer requires 4 content panes, think of old schools frames, where you have a top pane for your header, left pane for your menu, center pane for your main content and bottom pane for your copyright notices or status messages.

Our first line of code will be

 
<?php
	$this->borderContainer()->captureStart('masterLayout', array(
		'design' => 'headline',
		'persist' => true),
		array('style' => 'width: 100%; height: 100%;')
	);
?>
 

This will begin capturing everything we're about to code into an output buffer, I'm going to demonstrate what I've found to be the best way to do this, by relating all of the DoJo Dijit Layout classes to DIV's it's the easiest way to understand this all. It's worth noting that you'll need to add:

body, html { margin: 0; height: 100%; }

To your CSS to make the border container the height of the page.

You'll need to create the 4 pane's for the border container, captureStart and captureEnd are inherited to all of the Dijit layout classes, anyting you output between captureStart and captureEnd will be added to the output buffer. You're basic 4 content panes will look like this.

 
<?php $this->contentPane()->captureStart('titlePane', array('region' => 'top'));
        // Start title pane capture
?>
<h1>My Custom CMS</h1>
 
<?php echo $this->contentPane()->captureEnd('titlePane');
        // End title pane capture and output
?>
 

 
<?php $this->contentPane()->captureStart('navPane',
                array('region' => 'left',
                'splitter' => true, 'orientation' => 'vertical'));
                // Start navPane capture
?>
<h1>My Nav Pane</h1>
 
<?php echo $this->contentPane()->captureEnd('navPane');
                // End navPane capture and output
?>
 

 
<?php $this->contentPane()->captureStart('mainPane',
                array('region' => 'center'),
                array('style' => 'background-color: white;'));
                // Start mainPane capture
?>
 
This will contain my main content
 
<?php echo $this->contentPane()->captureEnd('mainPane');
                // End navPane capture and output
?>
 

 
<?php $this->contentPane()->captureStart('statusPane',
                array('region' => 'bottom'));
                // End navPane capture and output
?>
 
This is my status pane it appears at the bottom.
 
<?php echo $this->contentPane()->captureEnd('statusPane');
                // End navPane capture and output
?>
 

You'll notice that the captureStart method can take 3 arguments.

The first argument is the id of the pane, this will be the same as the ID output in the XHTML.

The econd argument is a config array that will be passed to Dojo, if you're unsure about what your configuration options are for a particular pane you're best bet will be to hit The Book Of Dojo if you want to make a pane resizable, you will just need to add 'splitter' => true, 'orientation' => 'vertical' where orientation is how you want the resizing bar to appear i.e. at the bottom/top or left/right of the pane. Region dictates where in the borderContainer you want the pane to appear, options are center, left, bottom and top.

The final argument is an array of parameters you want to pass to the html as attributes, i.e. styles, classes etc.

Capture end can only take one argument, and that is the ID of the contentPane you want to stop capturing and output. captureEnd will return the XHTML to output, you can either store this in a variable or echo it, because we're using output buffering echoing it is the best way.

Finally you'll want to output everything

<?php echo $this->borderContainer()->captureEnd('masterLayout'); ?>

Earlier I mentiond it's easy to relate this to creating DIV's in XHTML, can you see where I'm coming from now? Your opening DIV's are your capture start's and your closing DIV's are the captureEnd's as long as you format your template files properly everything should be hunky dory.

Getting a bit more complex with an accordion

One of the nice features of the Dojo library is the accordion, you can add these to panels which looks pretty cool. I'm going to be showing you how to add an accordion to your navPane.

It's pretty simple, just replace:

 
<h1>My Nav Pane</h1>
 

With:

 
<?php $this->accordionContainer()->captureStart('navAccordion',
        array('duration' => 200),
        array('style' => 'width: 200px; height: 300px;'));
        // Start accordion capture
?>
 
      <?php $this->accordionPane()->captureStart('accordion1',
                array('title' => 'First Accordion'));
                // Start first accordion item capture
      ?>
 
This is my first accordion content pane
 
      <?php echo $this->accordionPane()->captureEnd('accordion1');
                // End First accordion item capture and output
      ?>
 
      <?php $this->accordionPane()->captureStart('accordion2',
                array('title' => 'Second Accordion'));
                // Start first accordion item capture
      ?>
 
This is my second accordion content pane
 
      <?php echo $this->accordionPane()->captureEnd('accordion2');
                // End First accordion item capture and output
      ?>
 
<?php echo $this->accordionContainer()->captureEnd('navAccordion');
                // End accordion capture and output
?>
 

This will create an accordion in the navPane you can add as many accordion panes in the accordion container as you like.

That's pretty much it, you can have a look at the demo here http://sandbox.justanotherdeveloper.co.uk/zend_dojo_layout, I'll post the full code in a day or two.

Ideally it would be nice to extend the Zend_View and have custom tags and parsing them rather than writing PHP.