Web Application Framework (waf)
Page Basics
What is a page?
A page is the basic functional content unit within the framework. A page consists of a single php file which is called by the framework when the user requests it by name.
An example of a page name would be "home". Notice there is no path or file extension — this is correct. The framework will look in the page root for the file with this page name and the .php extension. "home" would be "/assets/pages/home.php". The url that the user would enter to request that page is "/index.php?pg=home", or "/index.php/home".
The second form is prefered and will most likely be the default mode in the v1.0 release. It makes more intuitive URLs and makes hierarchical page structures more sensible.
Hierarchical Pages
Within the page root you can create directories, which can contain more pages. This lends itself to grouping like pages, a particularly important task in any sizable installation. Directories can have the same name as pages, which actually produces very intuitive URLs. Consider the following:
| URL |
Filename |
Explanation |
| /docs |
/pages/docs.php |
The docs page, a topical listing of documentation available. |
| /docs/dogs |
/pages/docs/dogs.php |
The documentation on dogs. |
| /docs/cats |
/pages/docs/cats.php |
The documentation on cats. |
Directories can be nested indefinitely, limited by file-system restrictions on file name length and URL length restrictions.
.common.php
Whenever a page is requested, after all the preprocessing happens, immediately before the page is actually executed, the framework attempts to execute a file in the same directory as the requested page called ".common.php". If it doesn't exist it produces no warnings. This is a good tool for applying common settings to all pages within a directory.
For example: if the user requests the "docs" page (/pages/docs.php), then waf will attempt to execute "/pages/.common.php" immediately before "/pages/docs.php". Likewise, if the users requests the "docs/cats" page, waf will attempt to execute "/pages/docs/.common.php" immediately before "/pages/docs/cats.php". This allows you to specify commonalities amongst all of the documentation files, or whatever other organizational breakdown you use.
How does a page work?
As mentioned earlier, a page is just a PHP file that is executed by the framework. There are several things you can do within a page, giving you flexibility to output any type of data you see fit.
Most of the input and output for a page happens via the $Page associative array. $Page contains a number of variables which dictate what should be sent back to the user. Consider the following breakdown of $Page.
- $Page['name']
- Type: string
- Input
- This is the name of the page that the user requested. This allows you to construct self-referencing URLs in a portable manner. (See wafMakePageURL())
- $Page['src']
- Type: string
- Input
- This is the fully qualified path name to the file corresponding to $Page['name'], that is to say, this file.
- $Page['URI']
- Type: string
- Input
- This is the URI of the page, as requested by the browser. Can often be used to construct a self-referencing URL in lieu of $Page['name'] and the rest of the $_REQUEST variables.
- $Page['dir']
- Type: string
- Input
- This is the file-system directory where the current page resides. Not entirely useful.
- $Page['title']
- Type: string
- Output
- The title of the current page. Only applies if templating is enabled.
- $Page['subtitle']
- Type: string
- Output
- The sub-title of the current page. Only applies if templating is enabled.
- $Page['body']
- Type: string
- Output
- This should be set to contain all of the output destined for the user. If $Page['use-template'] is true then this will be inserted into the active template.
- $Page['nav']
- Type: associative array
- Output
- This is an array of key/value pairs representing the contents of the navigation bar, where key/value equates to caption/URL. This is translated into a string by the templating engine, if enabled; otherwise it is ignored.
- $Page['headers']
- Type: array
- Output
- This is an array of values, each representing a header to be included in the <head> section of the template. The array is enumerated and each entry concatenated, and inserted by the templating engine, if enabled; otherwise it is silently ignored.
- $Page['redir']
- Type: string
- Output
- A URL to which the user should be redirected. Unset by default, if this contains any value then all other output destined for the user will be silently ignored. The framework can do both temporary and permanent HTTP redirects, based on the $Page['redir-permanent'] option.
- $Page['redir-page']
- Type: string
- Output
- A page to which the user should be redirected. Works identically to the $Page['redir'] option and takes higher precidence.
- $Page['redir-permanent']
- Type: boolean
- Output
- Specifies whether the HTTP redirect (specified by $Page['redir']) should be permanent or not. If true then a HTTP/1.1 301 is sent, otherwise a HTTP/1.1 302 is sent. A permanent redirect is cacheable, while a temporary redirect may be subject to change and so will be queried by the same URL next time. Default value is undefined, equating to false.
- $Page['use-template']
- Type: boolean
- Output
- Specifies whether templating should be enabled. If it is enabled then $Page['body'], $Page['nav'], $Page['headers'], $Page['title'] and $Page['subtitle'] are used in substitution with the active template to produce the final output for the user. If disabled then $Page['body'] will be the final output.
- $Page['template-name']
- Type: string
- Output
- Specifies an alternate template to use, instead of the site-global default. If this template doesn't exist the framework will default to using the site-global default.
- The path specified is relative to the waf root.
Example 1: Basic Static Content
<?php
$Page['title'] = "My Dog";
?>
<h2>Color</h2>
<p>My dog has pink skin and a flourescent green mohawk down the length of
his back. The mohawk fur is dirty white. I often apply liberal amounts of gel
to spike it.</p>
<h2>Behavior Problems</h2>
<p>Sometimes he doesn't behave like I want. For instance, the other day
my friend Joey was over, mooching off my beer (as usual) and I told Sparks to
attack him. Sparks didn't attack him, he didn't even give him a disappointed
look. I was so dismayed by Sparks' blatant disregard for my commands that I
confined him to his kennel in the yard for six days. When I went to dig him out
from under the snow I could tell he would be better in the future.</p>
Aside from being very disturbing (and entirely fictional), this illustrates a very simple usage of the framework. $Page['title'] is being set, but the rest is just static HTML. Since $Page['body'] is not set, the static HTML is passed back to the framework, which will in turn insert it into the template.
Example 2: A Redirecting Form Handler
<?php
if($_POST['password'] == 'waf is great')
{
$Page['redir'] = wafMakePageURL('secret');
}
else
{
if(isset($_POST['password']))
{
// Show the error message if they entered a password, because it was incorrect
$Page['body'] .= "<p>Incorrect password!</p>\n";
}
// Show the login form
$Page['body'] .= "<form action='" . wafMakePageURL($Page['name']) . "' method='POST'>\n";
$Page['body'] .= " Enter Password: <input type='password' name='password' />\n";
$Page['body'] .= " <input type='submit' value='Log in'>\n";
$Page['body'] .= "</form>\n";
}
?>
Oh wow, that got way bigger, didn't it? Well, this shows a different method for specifying the output; that is, by manually populating $Page['body']. This page will generate a login form which submits to itself. If it is requested with no password value or an incorrect one it shows the login form, otherwise it redirects to the "secret" page.
Also notice the use of the wafMakePageURL() function. This makes the page more portable, where it will automatically generate correct URLs if you rename or move the page to a different directory.
In this case, since we're redirecting to another waf page, there's a shortcut. We can replace this line:
$Page['redir'] = wafMakePageURL('secret');
with this:
$Page['redir-page'] = 'secret';
The net result is the same — the user is sent a redirect to the URL for the 'secret' page.
Example 3: Sending non-HTML Data — JSON
<?php
$Result = Array(
'status' => true,
'error_code' => 0,
'error_string' => ''
);
$Page['use-template'] = false;
$Page['content-type'] = 'application/json';
$Page['body'] = json_encode($Result);
?>
Building a page like this allows you to build AJAX handlers within the same page structure as the rest of your site, with all the same benefits. You can return any sort of non-HTML data like this, even binary formats like images.
What I've done in the past is use the waf .common.php hierarchy to simplify this task. By putting the $Page['use-template'] and $Page['content-type'] lines into a new pages/ajax folder, any page you put into the ajax folder automatically outputs JSON instead of HTML.