AssortedBits

Qcodo is a fantastic PHP framework which uses code generation to accelerate the process of developing database driven websites. It not only generates all of the CRUD code for data objects, it also has a set of form objects from which to build the presentation layer. Out of the box it generates some basic forms to view and edit the data objects. This is the first in a series of articles discussing a simple technique for creating a consistent look and feel for a Qcodo site, while at the same time making it very easy to change the look of all or some of the pages at any time.

Assumptions

This article assumes that you have a basic understanding of how to setup Qcodo and generate your code. If this is not the case, you should read the installation and setup documentation available on the Qcodo web site.

Goals

The goals for this system are simple.

1. Allow each page to have a unique title (and any other HTML head items)
2. Provide a consistent layout for all pages
3. Be able to easily change page layout, by replacing 1 (or 2) files
4. Easily support having a standard set of form items on each page (i.e. a search box, etc)
5. Minimize the amount of duplicate code in forms (preferabley to zero)

In short, we want to let Qcodo handle all of the code generation for the boring (and error prone) backend code, while we concentrate on designing a great looking site. We also want to be able to use all the form objects to create our site.

A look at the generated forms

The code generator creates a pretty generic starting point for the forms necessary for a fully functional web application. It creates 4 files. The xxx_list.php and xxx_edit.php files contain the php classes defining the forms to list and edit objects. The xxx_list.php.inc and xxx_edit.php.inc files contain the HTML template code to render the forms.

If you take a closer look at the class files you will notice that in addition to defining the class, they actually run the form. The last line of the file says something like this:

ObjectListForm::Run("ObjectListForm", "generated/object_list.php.inc");

The arguments for the Run method are the class name of the form and the filename of the template file.

Taking a look at the template file reveals that the form template actually contains the HTML code to render the entire page. This includes the , , and tags. There are two important side effects of this fact. First, you can only have a single form on a page, and second, in order to change the look of your site, you need to change every one of the form templates. Fortunately, we can rely on the single form per page fact to solve the more annoying issue of having to change multiple files to update the look of the site.

The Solution

There are 6 steps to our solution

1. Subclass (or modify) QForm
2. Use our new QForm subclass as the parent for our application forms
3. Each application forms now use the layout template as the second argument to the Run method
4. Change the form templates
5. Create a generic layout template for all form object to use
6. require the form templates from the layout template

QForm Subclass

The QForm subclass is pretty straight forward. It is an abstract subclass of QForm which contains the properties we want all of our forms to have. To keep this simple, we’ll start with a title and the name of the template file for the form. (All of the code for this article can be downloaded here).

The class declarations looks like this:

abstract class ABCForm extends QForm {

protected $formTemplate;

protected $pageTitle;

[... we also need to define the __get and __set methods for ABCForm ...]
}


Now when we create our application forms, instead of subclassing QForm, we subclass ABCForm. Before we go any farther, it should be noted that instead of subclassing QForm, we could have modified QForm directly. My personal preference is to keep customizations to the framework isolated from the framework code itself, which is why I chose to subclass QForm. This reduces the chance that my changes will get trashed by an update to the framework.

When we create our ABCForm subclasses, we need to make sure that both pageTitle and formTemplate are defined. This is easily accomplished in the Form_Run method. We will also use the new layout template (which will be defined below) as the template argument to our Run method call in our form classes, like this:

MyNewForm::Run("MyNewForm", "templates/layoutTemplate.php.inc");


Changing the templates

The change to the form templates is a very simple one. We will simply remove everything between and including the tag and the RenderBegin() ?> from the top of the file. Then we remove everything between and including the RenderEnd() ?> and the lines. The rest of the file remains the same. That leaves only the parts of the file that are specific to the form we are editing.

Defining layoutTemplate.php.inc is straighforward as well. To keep things simple, we’ll ignore styles for this article. So our template file looks like this:




here and start experimenting with it.

This entry was posted on Monday, June 19th, 2006 at 4:51 pm and is filed under PHP, Qcodo. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.