Getting Started with HTML_FlexyFramework, DataObjects and HTML_Template_Flexy : roojs.org

Published 2006-07-28 00:00:00

Since most of the applications I write, and get teams to write for me, use the FlexyFramework, I though some simple instructions might be usefull.

FlexyFramework, is an extremely simple pair of classes that help load action classes, do internal redirection, and load up basic configuration settings. Basically taking all the hard work out of setting up a reasonably secure web application.

In this simple example, I'm going to use a little project called FlexyCash, so if you are setting up a project, just replace all the references to FlexyCash with your project name.

You'll have to visit the site, as the actual tutorial is in the extended entry bit....

Step 1 - Make a Project directory.

create the project directory:
mkdir /var/www/flexycash

Step 2 - Install pearball

download the pearball tgz or create one using the pearball creation script, and extract it into the project directory
cd /var/www/flexycash
tar xvfz pearball-......tgz

Note: this pearball includes the FlexyFramework code..

Step 3 - Create bootstrap file

create a bootstrap/config file (eg. cash.php), or index.php
I've not used index.php, as the project is stored in subversion, and when checked out, you can rename the file to index.php, and change to values to suit the installation.
See this file for an example:

<?php

// set up the include path to work! - our project, and our private pear install
ini_set('include_path', 
    realpath(dirname(__FILE__)) . ":" 
    . PATH_SEPARATOR .  realpath(dirname(__FILE__))  . '/pear' 
);

require_once 'HTML/FlexyFramework.php';
 

new HTML_FlexyFramework(array(
    // all of these are available via HTML_FlexyFramework::get()->**section**


    'project' => 'FlexyCash',   // our project name


    
    'FlexyCash' => array(           // our project varoable
        // put project options in here..
    ),
    
    // set up the database connection + path to dataobjects.
    'DB_DataObject' => array(
        'database'        => 'mysql://user:@localhost/gnucash',   // fill in the correct details here!
        'schema_location' => 'FlexyCash/DataObjects',
        'class_location'  => 'FlexyCash/DataObjects',
        'require_prefix'  => 'FlexyCash/DataObjects/',
        'class_prefix'    => 'FlexyCash_DataObjects_',
        //'quote_identifiers' = 1
    ),
    // any other stuff can go here..
    
    

));

Step 4 - Create Project base class

create the base class for the project.
Things to remember here

template should be defined (which template is shown when you go to the root page of the site)
getAuth() should be defined, and if everyone is allowed to the homepage, just return true.
get() and post() should be defined, and should check the incomming string, if it's not handled, then redirect to an error handler (or in our simple example, just exit.)

<?php

class FlexyCash extends HTML_FlexyFramework_Page 
{
    
    var $template = 'welcome.html';
    
    function getAuth()
    {
        return true; // everyone is allowed here!
    }
    
    function get($str)
    {
        // if we get a url that is not handled throw a 404 error page.
        if (strlen($str)) {
            echo "404 - not allowed";
            // HTML_FlexyFramework::run('Error/404');
            exit;
        }
        
    }
    function post($str)
    {
        // if we get a url that is not handled throw a 404 error page.
        if (strlen($str)) {
            echo "404 - not allowed";
            // HTML_FlexyFramework::run('Error/404');
            exit;
        }
        
    }
    
}

Step 5 - Create master template

create the master template:

/var/www/flexycash/FlexyCash/templates/master.html

- our simple example is this. - just put the header text in there, and the outputBody():h call.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
  <title>FlexyCash - {title}</title>
  <style> </style>
</head>
<body>

{outputBody():h}
    
</body>
</html>

Step 6 - Create Welcome page

Create the welcome page in the file

/var/www/flexycash/FlexyCash/templates/welcome.html

again with some simple contents

Hello  World <BR/>
root= {rootURL} <BR/>
base= {baseURL}

Step 7 - Test it

Test if it's working - go to
http://localhost/flexycash/cash.php

You may get this message - which tells you that magic quotes must be turned off!

magic quotes is enabled add the line
php_value magic_quotes_gpc 0
to your .htaccess file
(Apache has to be configured to "AllowOverride Options AuthConfig" for the directory)

to fix it, follow the instructions, or modify you php.ini to turn off magic_quotes.

If you are lucky, you get this message displayed.
Hello World
root= /flexycash
base= /flexycash/cash.php

Step 8 - Create the DataObjects

Assuming you have designed your database in Mysql Query Browser, or similar.
create a file (somewhere outside of the web directory) eg.
/tmp/create_flexycash.ini

[DB_DataObject]

database    = mysql://user:@localhost/gnucash
schema_location = /var/www/flexycash/FlexyCash/DataObjects
class_location  = /var/www/flexycash/FlexyCash/DataObjects
require_prefix  = FlexyCash/DataObjects/
class_prefix    = FlexyCash_DataObjects_
debug = 1

run createTables on it.

php  -d include_path=/var/www/flexycash/pear \
   /var/www/flexycash/pear/DB/DataObject/createTables.php /tmp/create_flexycash.ini

This should generate all the dataobjects for your project

Step 9 - Create some code to use the database

In the base class, I have added a method loadAccounts()
It loads all the accounts to be displayed as a tree on the right of the web page. -It's defined as a method here, so that other pages can call it in their get() methods.
Note: I dont have a constructor to do this automagically, as I like each Action class to be reasonably self contained when explaining how it builds the page.
Note: We also do the bulk of the work inside the extended dataobject, as this code may be usefull elsewhere in the future...

    // from class FlexyCash
    // in get() method:
	$this->loadAccounts();

    var $accountsArray;
    
    function loadAccounts()
    {
        $ac = DB_DataObject::factory('account');
        $this->accountsArray = $ac->loadAccountsTree();

Create the code in the DataObject. - this creates a nested array of dataobjects showing the tree of the accounts. (only works on PHP5, as object now get passed by reference, rather than by copy)

    function loadAccountsTree()
    {
        $this->orderBy('name');
        $this->find();
        $ar = array();
        while ($this->fetch()) {
            if (!isset($parents[$this->parent])) {
                $parents[$this->parent] = array();
            }
            $parents[$this->parent][] = clone($this);
        }
        foreach($parents[0] as $id => $obj) {
            $this->buildTree($obj, $parents);
        }
        return $parents[0];
    }
    public $children;
    function buildTree($obj, $parents)
    {
        $obj->children = !empty($parents[$obj->id]) ? $parents[$obj->id] : array();
        foreach($obj->children as $id => $sobj) {
            $this->buildTree($sobj, $parents);
        }
    }

Step 10 - add code in template to dump the tree.

Normally, I dont allow the PHP code to generate HTML, but tree's tend to be an exception, as there is no clean way of doing it purely using a template.
So to dump the tree that we have built I changed the welcome template to use this:

 <ul class="account-list">
   <li flexy:foreach="accountsArray,account">
       {account.toHtmlLi(baseURL):h} 
    </li>
  </ul>

Step 11 - provide a method to dump tree nodes.

In the dataobject, we provide a simple recursive method to output the tree data with some urls.

function toHtmlLi($baseurl)
    {
        $ret = '<a href="'. htmlspecialchars($baseurl). '/Account/'. $this->id . '.html">' .
                htmlspecialchars($this->name) . '</a>';
        if (empty($this->children)) {
            return $ret;
        }
        $ret .= '<ul>';
        foreach($this->children as $c) {
            $ret .= '<li>'. $c->toHtmlLi($baseurl) . "</li>\n";
        }
        
        return $ret . '</ul>';
        
         
    }

Now we can visit the home page again and see a list of the accounts as a unordered list.

What's here