1. Introduction

1.1 The Model-View-Controller ('MVC') Design Pattern

In the MVC design pattern, application flow is mediated by a central Controller. The Controller delegates requests - in our case, HTTP requests - to an appropriate handler. The handlers are tied to a Model, and each handler acts as an adapter between the request and the Model. The Model represents, or encapsulates, an application's business logic or state. Control is usually then forwarded back through the Controller to the appropriate View. The forwarding can be determined by consulting a set of mappings, usually loaded from a database or configuration file. This provides a loose coupling between the View and Model, which can make an application significantly easier to create and maintain.

1.2 "Phrame"work Overview

True to the Model-View-Controller design pattern, Phrame applications have three major components: a controller, which is provided by Phrame itself, Pages (the "view"), and the application's business logic (or the "model"). Let's step through how this all fits together.

The Phrame controller bundles and routes HTTP requests to other objects in the framework, including pages and Action subclasses provided by the Phrame developer. When initialized, the controller parses a configuration resource file. The configuration resource defines (among other things) the ActionMappings for an application. The controller uses these mappings to turn HTTP requests into application actions.

An ActionMapping will usually specify:

• a request path (or "URI"),
• the object type (Action subclass) to act upon the request,
• and other properties as needed.

An Action object can create a shopping cart object, add an item to the cart, place the object in the session collection, and then forward control to another mapping. That mapping may use a page to display the contents of the user's cart. Since each client has their own session, they will each also have their own shopping cart. In a Phrame application, most of the business logic can be represented using models. An Action can call the properties of a model without knowing how it actually works. This encapsulates the business logic, so that the Action can focus on error handling and where to forward control.

Objects can also be used to manage input forms. A key problem in designing Web applications is retaining and validating what a user has entered between requests. With Phrame, you can define your own set of form classes, by subclassing ActionForm, and easily store the data for an input form in these form objects. The object is saved in one of the standard, shared context collections, so that it can be used by other objects, especially an Action object.

The form object can be used by a page to collect data from the user ... by an Action object to validate the user-entered data ... and then by the page again to re-populate the form fields. In the case of validation errors, Phrame has a shared mechanism for raising and displaying error messages.

A Phrame form object is declared in the configuration resource, defined in a PHP file, and linked to an ActionMapping using a common property name. When a request calls for an Action that uses a form object, the controller either retrieves or creates the form object, and passes it to the Action object. The Action object can then check the contents of the form object before its input form is displayed, and also queue messages to be handled by the form. When ready, the Action object can return control with a forwarding to its input form. The controller can then respond to the HTTP request and direct the client to the next page.

For the simplest applications, an Action object may sometimes handle the business logic associated with a request. However, in most cases, an Action object should invoke another object, usually a Model, to perform the actual business logic. This lets the Action focus on error handling and control flow, rather than business logic. To allow reuse on other platforms, business-logic Models should not refer to any Web application objects. The Action object should translate needed details from the HTTP request and pass those along to the business-logic beans as regular PHP variables.

In a database application, for example:

• A business-logic model will connect to and query the database,
• The business-logic model returns the result to the Action,
• The Action stores the result in an object, or form object, in the request,
• The next page displays the result in a HTML form.

The rest of this Users Guide explains the various Phrame components in greater detail. The Phrame release also includes several Tutorials covering various aspects of the framework, along with sample applications, and, of course, the complete source code!

Phrame is distributed under the GPL license. The code is copyrighted and is free to use in any application. See the GPL license for specifics.

1.3 The Model: System State and Business Logic Models

The Model portion of an MVC-based system can be subdivided into concepts -- the internal state of the system, and the actions that can be taken to change that state. In grammatical terms, we might think about state information as nouns (things) and actions as verbs (changes to the state of those things).

Generally, your application will represent the internal state of the system as a set of one or more objects, with properties that represent the details of the state. Depending on your application's complexity, these objects may be self contained.

Large-scale applications will often represent the set of possible business logic actions as methods that can be called on the objects maintaining the state information. For example, you might have a shopping cart object, stored in session scope for each current user, with properties that represent the current set of items that the user has decided to purchase. This object might also have a checkOut() method that authorizes the user's credit card, and sends the order to the warehouse to be picked and shipped. Other systems will represent the available actions separately, perhaps as Business Logic Models.

In some smaller scale applications, on the other hand, the available actions might be embedded within the Action classes that are part of the Controller role. This is appropriate when the logic is very simple, or where reuse of the business logic in other environments is not contemplated. The "Phrame"work supports any of these approaches, but strongly recommends separating the business logic ("how it's done") from the role that Action classes play ("what to do").

1.4 The View: Pages and Presentation Components

The View portion of a Phrame-based application is generally constructed using PHP or XSLT technology. PHP pages can contain static HTML (or XML) text called "template text", plus the ability to insert dynamic content based on the interpretation (at page request time).

1.5 The Controller: ActionController and ActionMapping

The Controller portion of the application is focused on receiving requests from the client (typically a user running a web browser), deciding what business logic function is to be performed, and then delegating responsibility for producing the next phase of the user interface to an appropriate View component. In Phrame, the primary component of the Controller is an ActionController class. This class is configured by defining a set of ActionMappings. An ActionMapping defines a path that is matched against the request URI of the incoming request, and usually specifies the fully qualified class name of an Action class. All Actions are subclassed from Action. Actions encapsulate the business logic, interpret the outcome, and ultimately dispatch control to the appropriate View component to create the response.

Phrame also supports the ability to use ActionMapping classes that have additional properties beyond the standard ones required to operate the framework. This allows you to store additional information specific to your application, but still utilize the remaining features of the framework. In addition, Struts lets you define logical "names" to which control should be forwarded so that an action method can ask for the "Main Menu" page (for example), without knowing what the actual name of the corresponding page is. These features greatly assist you in separating the control logic (what to do) with the view logic (how it's rendered).