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.

The view script is used in conjunction with a layout, which we will not discuss here. The only thing we will mention here is that the layout script contains the following code in the head section:

// jQuery
echo $this->jQuery() . PHP_EOL;
 
// Links
echo $this->headLink() . PHP_EOL;

This uses the jQuery and headLink view helpers to:

• Render the appropriate tags for including the core jQuery files
• Render the link tags used to include the stylesheet.

The latter point is of relevance, as the first lines of the view script are:

// Append the login page stylesheet
$this->headLink()->appendStylesheet($this->baseUrl('/css/login.css'));

The stylesheet file appended here needs to be rendered, and the echo $this->headLink() statement in the layout script does just that.

The styles in the file are as follows:

#login_title
{
	text-align: center;	
}
 
#login_error
{
	text-align: center;
}
 
#login_form
{
	margin-left: auto;
	margin-right: auto;
	position: relative;
	width: 400px;
}
 
#login_form dl
{
	float: left;
	width: 400px;
	padding: 20px 0 20px 0;
	background: #d3d3d3;
	border: 1px solid gray;
}
 
#login_form dt
{
	clear: left;
	float: left;
	width: 120px;
	margin: 0;
	padding: 5px;
	text-align: right;
	font-weight: bold;
}
 
#login_form dd
{
	float: left;
	width: 240px;
	margin: 0;
	padding: 5px;
	text-align: left;
}

The form is rendered as a definition list (dl), so the main task of the above styling is to ensure that the label (dt) and input control (dd) are on the same line. This rendering is the default behaviour of Zend_Form.

The jQuery include is necessary, as the script makes use of it to give focus the appropriate field in the form.

The script first enables jQuery, then includes a general purpose JavaScript file, used to give focus to fields on a form.

// Add the form JavaScript file
ZendX_JQuery::enableView($this);
$this->jQuery()->addJavascriptFile($this->baseUrl('/js/form.js'));

The form.js JavaScript file contains the following script:

var Form = function()
{
	Form.prototype.FirstFieldFocus = function(form_id)
	{
		$("#" + form_id + " :input:visible:enabled:first").focus();
	};
 
	Form.prototype.ErrorFieldFocus = function(field_id)
	{
		$("#" + field_id).focus();
	};
};
 
var theForm = new Form();

The above provides two basic functions:

• Select the first field on a form
• Select a specific field on a form

The first requires an elaborate jQuery selector, which detemines the first input field on the form which is visible and enabled.

The script now moves on to render the page title:

// Display the page title
echo '<h3 id="login_title">Login</h3>' . PHP_EOL;

Finally, the script renders the form and any error messages. In addition to the form itself, the script also create the appropriate JavaScript to invoke the functions defined in form.js in order to either select the error field, if there was an error when the form was submitted, or the first field of the form, if the form has not yet been submitted.

// Display any error messages and set focus to the appropriate form field
if (isset($this->errorMessage))
{
	printf('<div id="login_error" class="error">%s</div>' . 
PHP_EOL, $this->errorMessage);
	$script = sprintf('theForm.ErrorFieldFocus("%s");', 
$this->errorField);
	$this->jQuery()->addOnload($script);
}
else
{
	$script = sprintf('theForm.FirstFieldFocus("%s");', 
$this->form->getAttrib('id'));
	$this->jQuery()->addOnload($script);
}
 
// Render login form
$this->form->setAction($this->baseUrl('/login'));
echo $this->form;

Note the use of $this->jQuery()->addOnload(). The script is not rendered directly to the page in the view script, but rather in the layout script, by the echo $this->jQuery() statement. It is wrapped inside a jQuery ready event, so that it is only executed when the whole page is loaded.

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.

The script contains the following code:

$this->tabPane(
  'tabs',
  $this->render('index/blogs/our-blogs.phtml'),
  array('title' => 'Our Blogs')
);
 
foreach ($this->blogs as $blog)
{
  $this->tabPane(
    'tabs',
    $this->partial('index/blogs/blog-partial.phtml',
      array(
        'name' => $blog->name,
        'href' => $blog->href,
        'description' => $blog->description,
        'id' => $blog->id
      )
    ),
    array('title' => $blog->name)
  );
}
 
echo $this->tabContainer('tabs');

The page makes use of the partial view helper to render the markup for each blog page’s tab. The partial helper takes two parameters; the first indicates the file containing the partial view script, the second the variable parameters used to fill out this script. The partial view script used here contains the following:

<h1><a href="<?php echo $this->href; ?>">
  <?php echo $this->name; ?></a></h1>
 
<p>
  <strong>URL: </strong> 
    <a href="<?php echo $this->href; ?>" rel="nofollow">
    <?php echo $this->href; ?></a>
</p>
 
<p>
  <strong>Description:</strong> 
    <?php echo $this->description; ?>
</p>
 
<?php
echo $this->ajaxFeedDigest($this->id) . PHP_EOL;

The parameters passed to the partial view script are the blog name and description, its URL, and its ID. The last is passed to the AjaxFeedDigest view helper.

We shall look at the implementation of the AjaxFeedDigest view helper in the next post. It is used to render a list of the most recent five posts on the specified blog, using the blog’s feed to fetch the information. The decision to use an AJAX approach to rendering this list was because sometime it can take a little time to fetch this information. If the site had to wait for it before rendering the rest of the page, the user can often be faced with an unacceptable wait staring at a blank browser tab. However, if the rest of the page is rendered first, then the user can at least view that; the information for each blog feed can then be filled in as soon as it is available.

The script contains the following code:

<?php
$this->tabPane(
  'tabs',
  $this->render('index/contact/contact-us.phtml'),
  array('title' => 'Contact Us')
);
 
echo $this->tabContainer('tabs');

The contents of the tab are rendered by the contact-us.phtml script in the contact sub-directory. This starts by rendering the tab heading:

<h1>Contact Us</h1>

Then it determines whether an error has occurred; if it has, the amount of information displayed depends on whether the site is deployed in a development environment:

<?php
if (isset($this->errorMessage))
{
  if (APPLICATION_ENV == 'development')
  {
    printf('<p class="error">%s</p>', $this->errorMessage) . 
PHP_EOL;
  }
  else
  {
    printf('<p class="error">There was a problem sending 
your message; please phone us on %s, or try again later.
</p>' . PHP_EOL,
    $this->placeholder('phoneNumber'));
  }
}

If an error has not occurred, the script tests whether the message sent flag is set; if it has, it displays an appropriate message for the user:

else if (isset($this->sent))
{
  echo '<p>Thank you for contacting GM-RAM! We will attempt 
to respond to you as soon as possible.</p>' . PHP_EOL;
}

If the message sent flag is not sent, the script will render the contact form instructions and the form itself; if the form has been submitted, but failed validation, any errors will be displayed here and the appropriate form selected.

The script starts with the instructions:

else
{
  echo '<p>Please fill in the following form and click on the 
<strong>Send</strong> button.</p>' . PHP_EOL;

Then it tests for a validation error and displays the error message:

  if (isset($this->error))
  {
    // Display the error message
    printf('<p class="error">%s</p>' . 
PHP_EOL, $this->error['message']);

It also selects the error field using jQuery:

    // Select the error field
    $script = sprintf('$("#%s").focus()', $this->error['field']);
    $this->jQuery()->addOnload($script);
  }

Note that the script dynamically creates a jQuery selector which refers to the field id, e.g. $(“#name”) for the name field. Also note that it uses the ZendX_JQuery helper to add this code to the functions executed when the page has loaded; this makes sure that the field is selected properly.

If there is no error, a similar mechanism is used to select the first form field:

  else
  {
    // Select the first field
    $script = sprintf(
      '$("#%s :input:visible:enabled:first").focus()', 
      $this->form->getAttrib('id')); 
    $this->jQuery()->addOnload($script);
  }

Note the special jQuery selection code applied to the form to select the first field; this doesn’t depend on the field ID staying the same (or indeed on the form ID staying the same, as the script fetches that dynamically).

Finally, the script sets the form action and renders it:

  $this->form->setAction($this->url());
  echo $this->form . PHP_EOL;
}

We have already looked at the implementation of the action handler. In my next post I shall look at the classes used to implement the form.

The about page is rendered by the about action handler of the index controller.

The about action handler is an empty function:

public function aboutAction()
{
 
}

The functionality is contained within the view script:

<?php
$this->tabPane(
  'tabs',
  $this->render('index/about/about-us.phtml'),
  array('title' => 'About Us')
);
 
$this->tabPane(
  'tabs',
  $this->render('index/about/windows-development.phtml'),
  array('title' => 'Windows Development')
);
 
$this->tabPane(
  'tabs',
  $this->render('index/about/web-development.phtml'),
  array('title' => 'Web Development')
);
 
echo $this->tabContainer('tabs');

Like the home page, the about page makes use of jQuery UI tabs; the main difference is that there are three tabs on the page rather than one. See the post The Home Page for more information the ZendX_JQuery view helpers used here to generate the necessary markup and JavaScript.

The contents of the tabs are in three files stored in the about sub-directory. The content of these scripts is not repeated here, as it should be obvious from the online version of the site. The only thing to note is that the first script makes use of the custom view helper described in the post The Navigation Link View Helper.

The IndexController class is stored in the file IndexController.php inside the application/controllers directory. The skeleton for the class code is as follows:

class IndexController extends Zend_Controller_Action
{
  // Insert the action handlers here
}

The index action handler is an empty function:

public function indexAction()
{
 
}

The functionality is contained within the view script:

<?php
$this->tabPane(
	'tabs',
	$this->render('index/index/welcome.phtml'),
	array('title' => 'Welcome')
);
 
echo $this->tabContainer('tabs');

This makes use of a couple of view helpers supplied by the ZendX_JQuery module.

The ZendX_JQuery_View_Helper_TabPane helper is used to build up a set of tabs; here there is only one.

The ZendX_JQuery_View_Helper_TabContainer helper is used to render the tab container.

The helper also adds the necessary code to the header, in order to initiate the tab container on the page being loaded, in accordance with the usual jQuery usage.

The contents of the tab are container in a separate script file called welcome.phtml, which is located in the index sub-directory:

<h1>Welcome to the GM-RAM Website!</h1>
 
<p>
  GM-RAM is a company whose business is software development 
  and consultancy.
</p>
 
<p>
  Here you can find information 
  <?php echo $this->navLink('about_page', 'about the company'); ?> 
  and <?php echo $this->navLink('contact_page', 'how to contact us'); ?>.
</p>
 
<p>
  You can also find 
  <?php echo $this->navLink('blogs_page', 'details of our blogs'); ?> 
  and any projects we are working on.
</p>

The script makes use of the Default_View_Helper_NavLink custom helper in order to render the navigation links. I shall look at the implementation of this in my next post.

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.