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 form class is derived from an abstract base class of my devising. This contains the functionality shared between all forms in an application. The abstract base class is itself derived from Zend_Form.

The abstract base class is defined as follows:

abstract class Application_Form_Abstract extends Zend_Form
{
  public function getFieldDecorators()
  {
    return array('ViewHelper', 
      array('HtmlTag', array('tag' => 'dd')), 
      array('Label', array('tag'  => 'dt'))
    );
  }
 
  public function getFirstFormError()
  {
    $fields = $this->getMessages();
 
    foreach ($fields as $field => $messages)
    {
      foreach ($messages as $message)
      {
        $error = array('message' => $message, 'field' => $field);
        return $error;
      }
    }
 
    return null;
  }
}

The class supplies contains two functions, both of which are connected to the rendering of error messages.

The first function modifies the standard field decorators to remove the error decorator, as I don’t usually want any error messages displayed beside the field. Instead, I prefer to show the first error message at the top of the form; it is the task of the second function to retrieve this.

The actual Login form class is straighforward:

class Application_Form_Login extends CapArgo_Form_Abstract
{
  public function init()
  {
    $this->setAttrib('id', 'login_form');
 
    $this->setMethod('post');
 
    $this->addElement(
      'text', 'username', array(
        'label'      => 'Username:',
        'maxLength'    => 64,
        'required'    => true,
        'filters'    => array('StringTrim'),
        'decorators'  => $this->getFieldDecorators(),
        'errorMessages'  => array('Please enter your username')
      )
    );
 
    $this->addElement(
      'password', 'password', array(
        'label'      => 'Password:',
        'maxLength'    => 64,
        'required'    => true,
        'decorators'  => $this->getFieldDecorators(),
        'errorMessages'  => array('Please enter your password')
      )
    );
 
    $this->addElement(
      'submit', 'submit', array(
        'ignore'    => true,
        'label'      => 'Login'
      )
    );
  }
}

The above code needs little explanation.

Note that there is a call to $this->getFieldDecorators() in order to attach the proper decorators to the input fields.

Also, note that the required option is set to true, and an error message is supplied, should the user fail to enter either a username or password; this uses Zend_Validate_NotEmpty to check that the user has entered a value.

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.

The skeleton code of the class is as follows:

class LoginController extends Zend_Controller_Action
{
  public function indexAction()
  {
    // TODO: Handle login attempt
  }
 
  public function logoutAction()
  {
    // TODO: Handle logout
  }
}

Let us look at the index action function, which is concerned with rendering the login form and handling login attempts made using it.

The function starts by creating a login form object:

    // Create the login form object
    $loginForm = new Application_Form_Login();

The implementation of this class will be discussed in a subsequent post.

The function now needs to check whether the form has been POSTed back to the application:

    // Check whether the user has submitted the login form
    $request = $this->getRequest();
 
    if ($request->isPost())
    {
      // TODO: Handle form being submitted
    }

If he has been submitted, the application needs to perform some basic validation, to check that the user has entered a username and password; if this validation fails, the cause is passed to the view script:

      // Validate form
      if ($loginForm->isValid($request->getPost()))
      {
        // TODO: Perform authentication of username and password
      }
      else
      {
        $error = $loginForm->getFirstFormError();
        $this->view->errorMessage = $error['message'];
        $this->view->errorField = $error['field'];
      }

If the submitted data passes this basic validation, the application needs to authenticate the username and password. If this is successful, the user is redirected to an appropriate page; otherwise, an error message is passed to the view script:

        // Get submitted values
        $values = $loginForm->getValues();
 
        // Attempt login
        $dbAdapter = $this->getInvokeArg('bootstrap')->getResource('db');
        $log = $this->getInvokeArg('bootstrap')->getResource('log');
        $login = new Application_Model_Login($dbAdapter, $log);
 
        if ($login->login($values['username'], $values['password']))
        {
          $this->_redirect('/');
        }
        else
        {
          $this->view->errorMessage = 'Invalid username or password';
          $this->view->errorField = 'username';
        }

Note that the authentication code is encapsulated inside a class (Application_Model_Login) which will be discussed in a subsequent post.

Also note that the application assumes that both the Db and Log resource plugins have been properly initialised by the bootstrapped (e.g. via the configuration file). See here and here for further details of these two resource plugins.

Finally, the form object needs to be passed to the view script:

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

The view script will be looked at in the next post.

The implementation of the logout action is simpler:

  public function logoutAction()
  {
    $login = new Application_Model_Login();
    $login->logout();
    $this->_redirect('/login');
  }

Again the Application_Model_Login class is used, this time to clear the user’s status as logged in. Then the user is redirected to an appropriate page.

Let us assume that we are adding our password and password repeat fields in the init method of our form class, which is derived from Zend_Form:

    $this->addElement(
      'password', 'password', array(
        'label'      => 'Password:',
        'maxLength'    => 64,
        'required'    => true,
        'decorators'  => $this->getFieldDecorators(),
        'errorMessages'  => array('Please enter a password')
      )
    );
 
    $this->addElement(
      'password', 'repeat_password', array(
        'label'      => 'Repeat Password:',
        'maxLength'    => 64,
        'required'    => true,
        'decorators'  => $this->getFieldDecorators(),
        'errorMessages'  => array('Please repeat the password correctly')
      )
    );

Note that both fields have the required option set to true; this is necessary event in the case of the repeat_password field, where we will be adding another validator later on. Also note that we have specified custom error messages for both fields, since the default messages are not appropriate.

The second and final step is to override the isValid method of the form class, and add the validator there:

  public function isValid($data)
  {
    $this->getElement('repeat_password')->
      addValidator(new Zend_Validate_Identical($data['password']));
 
    return parent::isValid($data);
  }

It is necessary to do it at this point, since it is only then that we have access to the value of the password field.

The form will now fail to validate if the password is not repeated correctly, and the appropriate error message will be generated.

The abstract class is called Default_Form_Abstract and is stored in the application/forms directory. It is derived from Zend Form.

The skeleton abstract class declaration is as follows:

<?php
abstract class Default_Form_Abstract extends Zend_Form
{
  // The class methods and variables are declared here.
}

The Zend_Form module uses the decorator pattern to define the markup used to render a form. The base form class uses decorators to render the forms as tables. The decorators used to render the form fields are contained in the following two variables:

  private $_fieldDecorators = array(
    'ViewHelper',
    array(array('data' => 'HtmlTag'), 
array('tag' => 'td', 'class' => 'element')),
    array('Label', array('tag' => 'td')),
    array(array('row' => 'HtmlTag'), 
array('tag' => 'tr'))
  );
 
  private $_buttonDecorators = array(
    'ViewHelper',
    array(array('data' => 'HtmlTag'), 
array('tag' => 'td', 'class' => 'element')),
    array(array('label' => 'HtmlTag'), 
array('tag' => 'td', 'placement' => 'prepend')),
    array(array('row' => 'HtmlTag'), 
array('tag' => 'tr'))
  );

These decorators are applied to field elements declared in derived classes using the following two methods. The first is used for most fields, which have labels; the second is used for buttons such as the submit button, which don’t have a label:

  public function setFieldDecorators($field)
  {
    $field->setDecorators($this->_fieldDecorators);
  }
 
  public function setButtonDecorators($button)
  {
    $button->setDecorators($this->_buttonDecorators);
  }

The overall styling for the form is set in the init method:

  public function init()
  {
    // Set the form decorators
    $this->setDecorators(
      array(
        'FormElements',
        array('HtmlTag', array('tag' => 'table')),
        'Form'
      )
    );
  }

Finally, there is a method used to retrieve the first error message generated by a failed validation:

  public function getFirstFormError()
  {
    $fields = $this->getMessages();
 
    foreach ($fields as $field => $messages)
    {
      foreach ($messages as $message)
      {
        $error = array('message' => $message, 'field' => $field);
        return $error;
      }
    }
 
    return null;
  }

This method is necessary as normally details of all fields that have failed validation are returned, but the usual (and my preferred) practice is to only report the first field that has failed validation. This has always struck me as less confusing for the user.

The abstract class is called Default_Form_Abstract and is stored in the application/forms directory. It is derived from Zend Form.

The skeleton abstract class declaration is as follows:

<?php
class Default_Form_Contact extends Default_Form_Abstract
{
  public function init()
  {
    // The code used to initialise the form is inserted here.
  }
}

The init method starts by calling the init method of the parent class:

    parent::init();

This is essential as the parent method sets up the form decorators.

Next the method sets the form ID:

    // Set the form ID
    $this->setAttrib('id', 'contact_form');

Then the method sets the form submission method to POST:

    // Submit the form using a POST request
    $this->setMethod('post');

The first form element is the Name field, which is a normal text field.

The script first creates an appropriate form element:

    // Name field
    $name = new Zend_Form_Element_Text('name',
      array(
        'label'      => 'Your name:', 
        'required'    => true, 
        'filters'    => array('StringTrim'),
        'maxlength'    => 64
      )
    );

The first parameter is the field name/id.

The second parameter is an array of additional settings. Here these are:

• label: This specifies the label attached to the field.
• required: This specifies whether the field is required; in this case it is, so the field will fail validation if it is not.
• filters: This specifies the filters to apply to the field; in this case, it is the trim filter, used to remove leading and trailing space.
• maxlength: This specifies the maximum length of the data than can be entered in the field.

The script then adds the error message to display, if the field fails validation:

    $name->setErrorMessages(array('Please enter your name.'));

The script then adds the appropriate decorators to the field, to ensure that it is rendered as a table row:

    $this->setFieldDecorators($name);

Finally the field is added to the form:

    $this->addElement($name);

A similar process is followed for the other form fields:

    // E-mail field
    $email = new Zend_Form_Element_Text('email', 
      array(
        'label'      => 'Your e-mail address:', 
        'required'    => true, 
        'filters'    => array('StringTrim'), 
        'validators'  => array('EmailAddress'),
        'maxlength'    => 255
      )
    );
    $email->setErrorMessages(
array('Please enter a valid e-mail address.'));
    $this->setFieldDecorators($email);
    $this->addElement($email);
 
    // Message field
    $message = new Zend_Form_Element_Textarea('message', 
      array(
        'label'     => 'Your message:',
        'required'  => true,
        'rows'      => 6,
        'cols'      => 50
      )
    );
    $message->setErrorMessages(array('Please enter a message.'));
    $this->setFieldDecorators($message);
    $this->addElement($message);
 
    // Submit button
    $submit = new Zend_Form_Element_Submit('submit', 
      array(
        'ignore'    => true, 
        'label'     => 'Send',
        'class'     => 'ui-state-default ui-corner-all'
      )
    );
    $this->setButtonDecorators($submit);
    $this->addElement($submit);

The e-mail field has a specific validator applied to it, rather than the general required setting.

The text area has its rows and columns set, rather than a maxlength.

Note that the submit button has different decorators applied to it, as unlike the other fields, it does not have a label.

In my next most, I shall finish my coverage of the contact page by looking at the class used to send the contact e-mail.

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.

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.