Read Me

Festa Tools Readme
Release Version 0.2
Written By: Mike Festa (C) 2011 FestaTech
-------------------------------------------------------------------------------

Welcome to Festa Tools, an object oriented PHP Framework. This code is still in
development and future changes may conflict with this current release, so use
with caution!

This release version is in alpha and is not intended for use by the general
public. Feel free to use this code, but understand that it is a work in
progress and there is currently very little documentation. 


-------------------------------------------------------------------------------
OVERVIEW
-------------------------------------------------------------------------------

Festa Tools can be used to better organize a database driven website. These
tools do not currently represent a functional Content Management System (CMS),
but they can be used to create your own.

One of the key components is the class FT_DB_Table. It can be extended to
create an object that is represented in a MySQL database, without manually
creating the table or entries. A simple example demonstrates the power of this
class:

//EXAMPLE

$newUser = new MY_User(0);	//MY_User class extends ft_user (an FT_DB_Table)
$newUser->constructDB();	//Creates the table `my_user`

//Insert a User
$newUser->userName = "mfesta";
$newUser->password = "BadPassword";
$newUser->save();		//Record inserted into the database table `my_user`
$userID = $newUser->id;	//Primary Key, generated when the record is inserted.

//Load a user
$existingUser = new MY_User($userID);	//Data auto-loaded from database.
echo $existingUser->username;			//This will print mfesta.

//END OF EXAMPLE


-------------------------------------------------------------------------------
INSTALLATION
-------------------------------------------------------------------------------

The FestaTools folder should be placed in the root directory of your website.

Each page that uses the framework must have these lines of code:
session_start(); 	//Sessions are used to maintain presence between pages.
require_once("FestaTools/core/FestaTools.php");		//FestaTools Framework

It is recommended that you configure your .htaccess file to redirect all pages
to index.php with the appropriate variables passed to the $_GET array.

Standard Directory Structure: (root website)
/action/			Place all backend php scripts here
/classes/			Place all custom classes here, one class per file
/css/				Place all custom css style sheets here
/css/img/			Place images loaded by style sheets here
/FestaTools/		Copy from Festa Tools Distribution
/flash/				Place all custom flash (swf) content here
/img/				Place your images here
/js/				Place your javascript files here
/pages/				Place your .php web pages here
.htaccess			Configure to redirect all requests to index.php
index.php			Generates all pages for your website


-------------------------------------------------------------------------------
NAMING CONVENTIONS
-------------------------------------------------------------------------------
FT_{class name}		Used for all Festa Tools classes
APP_{class name} 	Replace APP with a 2 to 4 letter name for your project
ft_user				Classes with all lower case names extend FT_DB_Table
APP_PageContent		Uppercase first letter for each word of other classes
$variableName		Variables start with a lowercase letter
$_protectedVar		Protected variables inside your class

Class names inside the /classes/ directory must match their file names for the
autoloader to work with: 

new APP_Class();	//The name of your custom class.

Protected variables, such as $_protectedVar can be read outside the class.

$item = new APP_Item();
$item->protectedVar;

They can only be set from outside the class if a setter is defined in the class

class APP_Item extends genericFestaTool{
	protected $_protectedVar;
...
	//Setters
	public function set_protectedVar($input){
		//Validation can be performed here.
		$this->_protectedVar = $input;
	}
}


-------------------------------------------------------------------------------
EXAMPLE
-------------------------------------------------------------------------------

//.htaccess File:
RewriteEngine on
RewriteRule ^$ index.php?page=home [L]
RewriteRule ^([^/\.]+)$ index.php?page=$1 [L]
RewriteRule ^([^/\.]+)/?([^/\.]+)$ index.php?directory=$1/&page=$2 [L]

//index.php File
<?php
//INPUT
$IN_directory 	= $_GET['directory'];	//(optional) Generated by .htaccess
$IN_page		= $_GET['page'];		//Generated by .htaccess

try{
	session_start(); 	//Sessions are used to maintain presence between pages.
	require_once("FestaTools/core/FestaTools.php");		//FestaTools Framework

	$GLOBALS['APP']	= new APP_Application();	//Extends FT_Application

	if(!file_exists("pages/".$IN_directory.$IN_page.".php")){
		$GLOBALS['APP']->webpage = new ft_webpage("e404");	//404 Error Page
	}
	else{
		$GLOBALS['APP']->webpage = new ft_webpage($IN_directory.$IN_page);
	}
	require_once("pages/".$GLOBALS['APP']->webpage->fileName.".php");
	$GLOBALS['APP']->webpage->drawPage();
} catch (Exception $e) { FT_Core::catchError($e); exit(0);}
?>

//classes/APP_Application.php
<?php
class APP_Application extends FT_Application{
	public function __construct($o) {
		parent::__construct($o);	//Create object from parent
		//Connect to a database
		$this->_database = new FT_Database(	"username",
											"password",
											"server",
											"database");
	}
}
?>


//pages/home.php File
<?php
//Include only the content needed for this page.

$GLOBALS['APP']->titleName = "Home Page";	//Shown in the title bar

//The display of HTML for the page title is handled by this class.
//This makes it easy to reproduce it on other pages.
$pageTitle = new APP_PageTitle("Welcome to my site.");	//Implements FestaTool

$GLOBALS['APP']->webpage->content->addTool($pageTitle);
?>

//classes/APP_PageTitle.php
<?php
class APP_PageTitle extends genericFestaTool{
	protected $_title;

	public function __construct($newTitle){
		$this->_title = $newTitle;
	}
	
	public function getHTML(){
		$div = new FT_HTML_div();		//<div> element
		$div->setClass("pageTitle");	//This name relates to the .css file
		$div->addText($this->_title);	//Adds plain text inside the <div>
		return $div->getHTML();			//<div class="pageTitle">TITLE</div>
	}
}
?>