Diary of a Zend Framework Buildup

Having worked for nearly a year on a roughed out codebase I siezed the opportunity to do what I'd wanted to do with the core client project at Clean Power Finance (cleanpowerfinance.com) on a smaller project -- a form wizard. In this context the forms were literal paper forms -- a series of forms that the state requires printouts of to approve a solar panel installation.

The project is quite self contained and amenable to Zend Framework treatment. The forms themselves will be driven by config file data provided by an independent contractor who parsed the original forms.

The forms required vary by state and utility. The basis for the information comes from the proposal system (see above) already in place at CPF. A credit system is part of the spec -- users need to be able to "spend" credits to establish forms, or buy credits for use in future forms. Also admins need to be able to buy credits and allocate them to other users. (non admin users will not be able to buy credits for themselves.)

The original spec was big on deliverables but short on process, structural detail or much of a vision for a workflow. The belief was that the entire project could be accomplished within a single recycled page -- partly driven by the tab based interface of the tool in which the client wanted to host the forms tool.

Step One: the plan

The first step was establishing a data model. Using Omnigraffle I sketched out a series of process diagrams. The frist was the ERM of the entire data model. The second set of diagrams was a basic workflow diagram, a state chart and a set of UI wireframes demonstrating the need for multiple panels.

Much discussion occurs around the linkage of proposal data to the formset data. The final model will be using the proposal as the initial seed for information, but keeping a system of record within the formset database. That is, for any given field, the value is first copied from the proposal (if possible) into a table in the formset system. Once established, the value is no longer linked to the proposal: the user will be able to edit either the proposal or the formset data independently, and must manually "recopy" the proposal data to maintain consistency between the proposal and the formset.

 Step Two: laying the groundwork -- unit tests and a mock database

The initial application had suffered from a lack of unit testing; not all projects require unit tests but this one did in spades. Having recently completed some "After the fact" unit tests to lock in the gains for the primary tool (a proposal generator) I decided to start with the test model from day one.

Using the Zend Eclipse IDE, starting a Zend Framework MVC project is a five second operation. However as with any project some cofiguration is required to allow for the uniqueness of this project. For instance, the default config assumes that the ZF project "owns" the domain. This project will be a subfolder of the tools URL so the base url must be manually set and the .htaccess files must be fiddled with.

The good news is that the newest build of the Zend Eclipse IDE also includes a formative test folder, so some of my testing work is done for me. There is a controller based test suite which I don't use -- at this state I am more concerned with domain object interaction.

This meant adopting the domain model -- wherein the table components are flexible enough to use either the database or a mock database (in this case a global .ini file of rows). There is no native domain system in Zend so I establish a baseline series of classes for the mock database and the domain system. This proves more problematic than I'd expected; for instance you are forced to either never use join syntax or to "mock" a join.

I establish a high level query system wherein you can pass a set of field and expected values that can either translate to a where clause in Zend's DB or is interpreted by a mock database that loads the entire table as an array of stdClass objects and discards mismatches. (I will publish the mock database and domain system later when I have the time.)

Once this system was established I crank out the first fiew table domain classes and punch out a few unit tests.

Step Three: the basic wireframe

Once this basic groundwork was established, I threw out the first basic control classes and a user login system. The front page was fairly complex becuase it is necessary to establish two launch lists:

1. A list of jobs (proposals) for which the user has not purchased and begun entry on the state forms
2. A list of jobs that have already been allocated a credit, and for which entry has begun.

Launching from the first list gives you an opportunity to spend a credit on a given job and launches you into a wizard that takes you form by form and fills out the information on a form by form basis. The end of this wizard is a PDF page that allows you to recieve the final formset as one big PDF. (there should also be allowance for individual form by form printouts, in case the user just needs to replace a subset of the document due to revision.

The Zend_Layout enabled layout will be a basic wireframe for now. A basic area for a header, an optional message alert div, and a main region for view content pretty much do the trick. A stub is the final piece of the layout.

A series of controllers for jobs, users, and formsets gives me the ability to mock out the entry wizard. I stick the current formset into session with Zend_Session and put the multiple form entry stubs under the formset controller, keeping track of the users' progress through the formset' forms with a url parameter on the wizard tabs. (the wizard tabs will ultiimately be disabled once there's a form on each page but for now they let you walk through the wireframed process.)

I add a ticket to the top of the page that affirms the identity and payment status of the current formset, using a partial -- a template that can be embedded inside another template. (One of the things I like about Zend Framewrk is that it uses standard PHP pages as templates: both the parent content block for each page, the overall layout, and the partials, in this case a formset ticket, use, for the most part, generic PHP syntax. They have helpers for special tasks like form elements that are loaded using object notation, and are prepopulated with data inside the controller action that launches them.

The wizard ends at a pdf print page that directs you to a PDF controller and a stub print page.