Each product page has a standard layout. The page divides into two vertical sections; the top vertical section is divided into two columns. The left column contains the main text describing the products on that page; the right column contains supplementary images and download links. The bottom vertical section contains a jQuery UI tab control, with one tab for each section of products being offered for sale on that page.

I needed to allow the user to edit the HTML used in the top left section. However, I didn’t want the user to have to write raw HTML, but rather to use a WYSIWYG editor. I identified the Open Source JavaScript editor CKEditor as a suitable candidate.

The process of integrating this editor with the existing Zend Framework application proved to be pretty simple:

1. Download the latest version of the editor from the CKEditor website.
2. Having unpacked the download, I uploaded the CKEditor directory (ckeditor) under the public web root (htdocs).
3. The layout script already contained the following in the page head, which forced the appropriate tags to load and enable jQuery to be added:

   echo $this->jQuery()->enable();

4. I added the following at the top of the view scripts that were going to make use of the editor. Note that the ID of the form field that was going to be enhanced by the editor was description.

   // CKEditor
   $this->jQuery()->addJavascriptFile('/ckeditor/ckeditor.js');
   $this->jQuery()->addJavascriptFile('/ckeditor/adapters/jquery.js');
   $this->jQuery()->addOnload("$('#description').ckeditor();");

5. I created a class to handle the form that used the editor. The class was named Application_Form_ProductPage and ultimately derived from Zend_Form via Application_Form_Abstract.
6. The init method of the class contained the following code to add the textarea that was enhanced going to be the editor:

   $this->addElement(
       'textarea', 'description', array(
       'label'		=> 'Product Description',
       'decorators'	=> $this->getFieldDecorators()
       )
   );

As a result of the able, the textarea was transformed into a fully-blown WYSIWYG editor. The raw HTML was passed behind the scenes, and was added to/retrieved from the database.

Lightbox is a simple, unobtrusive script used to overlay images on the current page. It’s a snap to setup and works on all modern browsers.

I decided to add the script to the GM-RAM website in order to allow visitors to view full-sized versions of the screen shots there without having to navigate to a separate page.

I downloaded the Lightbox JavaScript, style sheet and images that need to be placed in the publically-accessible part of the website. The JavaScript files were stored under /js/lightbox/, the style sheet at /css/lightbox.css and the images under /img/lightbox.

The first challenge arose from the fact that the site already uses jQuery, while Lightbox is based on Prototype and Scriptaculous. As both use the dollar ($) symbol, it was necessary to put jQuery into no conflict mode. Fortunately, as I was using ZendX_JQuery, there is a built-in mechanism for handling this.

In order to make sure that you use the correct jQuery “handler” character ($ or something else), you should dynamically determine what this is. An example of this is from the view handler I wrote to create the JavaScript used to load the results of an AJAX request into a block on the page:

class Application_View_Helper_LoadScript extends Zend_View_Helper_Abstract
{
  public function loadScript($id, $url)
  {
    $jqHandler = ZendX_JQuery_View_Helper_JQuery::getJQueryHandler();
    $script = sprintf($jqHandler . '("#%s").html("Loading..."); ' . 
      $jqHandler . '("#%s").load("%s");', $id, $id, $url);
    return $this->view->jQuery()->addOnload($script);
  }
}

Lightbox works unobtrusively by looking for links with the rel attribute set to either just lightbox or lightbox[group-name], where group-name is set to the same value for a series of images that the user should be able to view by navigating forwards and backwards. The links are wrapped around an image.

I changed the attributes of the images in line with this on the relevant pages. I then created a common script to be included in all the pages, which would set up Lightbox on them. The script is called lightbox.phtml and is located in /application/views/scripts. It is added to the pages’ view scripts by the following line:

<?php echo $this->render('lightbox.phtml'); ?>

The lightbox.phtml script starts by activating jQuery no conflict mode; as noted before, this is because Lightbox uses Prototype and Scriptaculous.

ZendX_JQuery_View_Helper_JQuery::enableNoConflictMode();

The script then adds the Lightbox JavaScript files. It is possible to do this here, as the view script is rendered before the layout, and therefore when echo $this->headScript() is used in the layout script to finally generate the list of script tags in the header, these are included in the output generated.

$this->headScript()->appendFile(
  $this->baseUrl('/js/lightbox/prototype.js'));
$this->headScript()->appendFile(
  $this->baseUrl('/js/lightbox/scriptaculous.js?load=effects,builder'));
$this->headScript()->appendFile(
  $this->baseUrl('/js/lightbox/lightbox.js'));

Because the implementation of Lightbox assumes locations for its images that are not always correct, we need to add some JavaScript to change them. The script we generate is added using the same mechanism as for the basic script files, although here we are using inline script that we have generated.

$this->headScript()->appendScript(
  'LightboxOptions.fileLoadingImage = "' . 
  $this->baseUrl('/img/lightbox/loading.gif') . '";');
$this->headScript()->appendScript(
  'LightboxOptions.fileBottomNavCloseImage = "' . 
  $this->baseUrl('/img/lightbox/closelabel.gif') . '";');

Then we add the Lightbox style sheet using a similar mechanism, this time using the headLink helper. This helper is called via echo $this->headLink() in the layout script, which renders this link along with the others added there.

$this->headLink()->appendStylesheet($this->baseUrl('/css/lightbox.css'));

Finally, we need to override some of the styling, which relates to the location of images. We used the headStyle helper for this; as with the headScript and headLink helpers, this relies on the layout script making a call to the helper, this time via echo $this->headStyle(). Note that this call to headStyle should come after the call to headLink in the header to ensure the overriding of the styling.

$this->headStyle()->captureStart();
?>
#prevLink:hover, #prevLink:visited:hover
{
  background: url(<?php echo $this->baseUrl('/img/lightbox/prevlabel.gif'); ?>) 
left 15% no-repeat;
}
 
#nextLink:hover, #nextLink:visited:hover
{
  background: url(<?php echo $this->baseUrl('/img/lightbox/nextlabel.gif'); ?>) 
right 15% no-repeat;
}
<?php
$this->headStyle()->captureEnd();

Note the use of the captureStart and captureEnd methods to allow the CSS to be rendered inline.

Regarding the calls to headScript, headLink and headStyle, the relevant section of the layout script is as follows:

// Scripts
echo $this->headScript() . PHP_EOL;
 
// Links
$this->headLink()->prependStylesheet($this->baseUrl('/css/default.css'));
$this->headLink(array('rel' => 'shortcut icon', 
  'href' => $this->baseUrl('/img/favicon.ico'), 'type' => 'image/x-icon'));
echo $this->headLink() . PHP_EOL;
 
// Styles
echo $this->headStyle() . PHP_EOL;

Now the Lightbox effect should be applied to all the tagged images on the page.

As the implementation is complex and is spread over a number of files and classes, I shall be looking at it over the course of several posts. In this post I shall be concentrating on the action handler.

The action handler starts by retrieving the request object:

public function contactAction()
{
  $request = $this->getRequest();

This will be used to determine whether the user has submitted the contact form and what data was submitted.

Then the function creates the form object:

  $form = new Default_Form_Contact();

We shall look at the implementation of this class in a later post.

Then the function determines whether the user has posted the form:

  if ($request->isPost())
  {

If the user has posted the form, the function retrieves the data posted and validates it against the form:

    $post = $request->getPost();
 
    if ($form->isValid($post))
    {

If the data is valid, the function then creates and sends the e-mail.

The first step is to create a Zend_Layout object, then set the layout script and its location:

      try
      {
        $layout = new Zend_Layout();
        $layout->setLayoutPath(APPLICATION_PATH . "/layouts/scripts");
        $layout->setLayout('contact-email');

The Zend_Layout will now look for a file called contact-email.phtml in the application/layouts/scripts directory.

The next step is to create a filter and use it to eliminate any possible HTML injection, before passing the parameters to the layout script:

        $htmlEntities = new Zend_Filter_HtmlEntities();
        $layout->name = $htmlEntities->filter($post['name']);
        $layout->email = $htmlEntities->filter($post['email']);
        $layout->message = $htmlEntities->filter($post['message']);

Then the layout is rendered and stored in a variable:

        $bodyHtml = $layout->render();

The sending of the mail is handled by the Default_Model_Mail_Contact class, which will be examined in a later post. The function creates an object of that class and call its send method, passing the HTML generated above as the parameter:

        $mail = new Default_Model_Mail_Contact();
        $mail->send($bodyHtml);

Then a variable is passed to the view script to flag that the mail has been sent:

        $this->view->sent = true;
      }

Any exceptions thrown during the process of sending the mail are handled in the following catch block:

      catch (Exception $e)
      {
        $this->view->errorMessage = $e->getMessage();
      }
    }

If the form validation fails, the error is passed in a variable to the view script:

    else
    {
      $this->view->error = $form->getFirstFormError();
    }
  }

Finally, the form object is always passed to the view script, to allow it to be rendered if necessary.

  $this->view->form = $form;
}

The layout script for the e-mail is quite simple:

<div>
  <div><strong>Name:</strong> 
<?php echo $this->layout()->name; ?></div>
  <div>
    <strong>E-mail:</strong> 
    <a href="mailto:<?php echo $this->layout()->email; ?>">
<?php echo $this->layout()->email; ?></a>
  </div>
  <div><strong>Message:</strong> 
<?php echo $this->layout()->message; ?></div>
</div>

The fields submitted by the user are injected into the appropriate places in the e-mail.

In the next post, I shall look at the view script for the contact page.

The script begins by rendering the DOCTYPE at the head of the page:

<?php echo $this->doctype() . PHP_EOL; ?>

This has previously been set by the custom view resource plugin, as described in the previous post Bootstrapping the Application: a Custom View Resource Plugin.

The rest of the page is enclosed inside an html block:

<html xmlns="http://www.w3.org/1999/xhtml" 
  dir="ltr" lang="en" xml:lang="en">
  <!-- Page content is rendered here -->
</html>

The html tag has the following attributes set:

• xmlns: This specifies the namespace to use; it is required, as the DOCTYPE is set to XHTML, and it is set to the standard value http://www.w3.org/1999/xhtml.
• dir: This specifies the text direction for the content. It is set to ltr (left to right), which is the correct value for English.
• lang: This specifies a language code for the content. It is set to en (English).
• xml:lang: This specifies a language code for the content in XHTML documents. It is set to en (English).

Inside the html block are the head and body blocks:

<head>
  <!-- Head content is rendered here -->
</head>
<body>
  <!-- Body content is rendered here -->
</body>

The head block is generated programmatically using Zend Framework view helpers:

<?php
// Title
echo $this->headTitle('GM-RAM Limited') . PHP_EOL;
 
// Metadata
$this->headMeta()->appendHttpEquiv
  ('Content-Type', 'text/html; charset=UTF-8');
$this->headMeta()->appendHttpEquiv('Content-Language', 'en-GB');
$this->headMeta()->appendName('copyright', 'Copyright ' . 
  $this->placeholder('copyrightDate') . ' GM-RAM Limited');
$this->headMeta()->appendName('verify-v1', '...'); 
  // Google verification code
echo $this->headMeta() . PHP_EOL;
 
// jQuery
$this->jQuery()->setLocalPath('/js/jquery-1.3.2.min.js');
$this->jQuery()->setUiLocalPath('/js/jquery-ui-1.7.2.custom.min.js');
$this->jQuery()->addStylesheet
  ('/css/smoothness/jquery-ui-1.7.2.custom.css');
echo $this->jQuery() . PHP_EOL;
 
// Links
$this->headLink()->appendStylesheet('/css/default.css');
$this->headLink(array('rel' => 'shortcut icon', 
  'href' => '/img/favicon.ico', 'type' => 'image/x-icon'));
echo $this->headLink() . PHP_EOL;
?>

The view helpers used are:

• Zend_View_Helper_HeadTitle (headTitle)
• Zend_View_Helper_HeadMeta (headMeta)
• Zend_View_Helper_HeadLink (headLink)
• ZendX_JQuery_View_Helper_JQuery (jQuery)

These all employ the same pattern of usage: one or more calls are made to the relevant function, which aggregates the content to be rendered; each call returns the content so far, but only the last call is actually echoed to the page.

The above code should be fairly self-explanatory in terms of what is being rendered. The call to headTitle is used to generate the title element; the calls to headMeta are used to generate the various metadata elements; the calls to headLink are used to add the links to the stylesheet and shortcut icon. As the site makes use of the jQuery JavaScript library, there are calls to the jQuery view helper to generate the appropriate elements for including the necessary JavaScript files and also generating the code which sets jQuery to perform certain actions on start up; the latter will be covered in more detail in later posts.

The skeleton structure of the body section is:

<div id="wrapper">
  <div id="header">
    <!-- Header content is rendered here -->
  </div>
  <div id="content">
    <!-- Main page content is rendered here -->
  </div>
  <div id="footer">
    <!-- Footer content is rendered here -->
  </div>
</div>

The header breaks down into:

• The navigation menu at the top
• The company’s logo
• The description of the company’s area of business
• The company’s phone number

The navigation menu is rendered like this:

  <div id="nav">
    <?php echo $this->navigation()->menu()->render() . PHP_EOL; ?>
  </div>

This uses the Zend_Navigation object, which is initialised using the configuration file as described in the post Bootstrapping the Application: the Standard Navigation Resource Plugin. Here, the pages in the navigation are rendered as a menu, which generates an unordered list of links.

The other three elements are rendered as follows:

  <img src="/img/logo.gif" alt="GM-RAM Limited" title="GM-RAM Limited" />
  <div>Software Development and Consultancy</div>
  <div>
    <strong>Phone:</strong> 
    <?php echo $this->placeholder('phoneNumber'); ?>
  </div>

Note the use of the placeholder view helper. This makes use of the placeholders set up using a custom resource plugin, as described in the post Bootstrapping the Application: a Custom View Resource Plugin.

The main page content simply consists of a call to fetch the layout object, so that its content member variable can be rendered:

<?php echo $this->layout()->content . PHP_EOL; ?>

This results in the output generated by the view script for the specific page being injected into the content div.

The footer consists of the following markup:

<div>
  <a href="http://framework.zend.com/">
    <img src="/img/PoweredBy_ZF_4LightBG.png" alt="Zend Framework" />
  </a>
</div>
<div>
  Copyright &copy; <?php echo $this->placeholder('copyrightDate'); ?> 
  GM-RAM Limited
</div>

Note again the use of the placeholder view helper.

In the next post, I shall look at the stylesheet for the website, in particular how it applies to the layout script.

The standard content is contained in a layout script, which is much like a view script. The script will contain the following piece of PHP code, or something very like it, to inject the content rendering by the view script into the layout script:

echo $this->layout()->content;

There are several ways to turn on the template engine; one has been covered in the post Bootstrapping the Application: the Standard Layout Resource Plugin. Note that the location of the layout scripts is specified in the configuration file settings. It is also possible to set the location directly from the controller, like this:

$this->_helper->layout->setLayoutPath(APPLICATION_PATH . 
  "/layouts/scripts");

Note that the layout is accessed from the controller via the helper broker $this->_helper; this object is configured to expose all the available helpers as if they were member variables of that object.

By default, the engine looks for a script called layout.phtml; if you want to use a different script, you need to specify it explicitly. For instance, the application also uses the engine to render the contact e-mail; the name of the script it uses is contact-email.phtml. The following code would instruct the engine to use this script:

$this->_helper->layout->setLayout('contact-email');

If you want to disable the use of the layout for a particular action, include the following call in its handler:

$this->_helper->layout->disableLayout();

In the next few posts, we shall look at the main layout script for the sample application in more detail.

To use Zend_Layout, you need to specify the location of the layout scripts, then invoke Zend_Layout::startMvc(). The standard resource plugin Zend_Application_Resource_Layout is used by Zend_Application to automate this process. To use this plugin, you should add the following line to the configuration file:

resources.layout.layoutPath = APPLICATION_PATH "/layouts/scripts"

This specifies the location of the layout scripts. If your scripts are in a different location, you should change the value of layoutPath.

We shall look at Zend_Layout in more detail in later posts.