class Siteimage extends Object
{
  public $tmp_name;
  public $versions = array();
  
  function Siteimage($id='', $user='', $size='', $type='', $name='', $label='')
  {
    $this->id = $id;
    $this->user = $user;
    $this->size = $size;
    $this->type = $type;
    $this->name = $name;
    $this->label = $label;
  }

  function GetTmpName() { return $this->tmp_name; }
  
  function GetName()
  {
    if ($this->isGhost()) $this->PopulateMe();
    if (empty($this->name))
    {
      list($object_type, $extension) = explode('/', $this->type);
      $this->name = '/' . CodeGenerator::GetCode() . '.' . $extension;
    }
    return $this->name;
  }
  
  function SetFromRequest($file='')
  {
    $this->tmp_name = $file['tmp_name'];
    $this->type = $file['type'];
    $this->size = $file['size'];
  }

  function SaveFile()
  {
    $config = Config::GetInstance();
    $file_path = $config->resource['path'] . $this->GetName();

    if (move_uploaded_file($this->GetTmpName(), $file_path))
    {
      chmod($file_path, 0777);
      return true;
    }
    else
    {
      $this->session = new Session();
      $this->error = new Message('fileupload', "I think there's something wrong saving the file to the folder.");
      return false;
    }      
  }
  
  function DeleteFile()
  {
    $config = Config::GetInstance();
    $this->DeleteVersions();
    unlink($config->resource['path'] . $this->GetName());
    return true;
  }
  
  function DeleteVersions()
  {
    $config = Config::GetInstance();
    foreach ($config->image as $version => $version_details)
    {
      $components = explode('/', $this->GetName());
      $components[count($components)-1] = $version . "_" . $components[count($components)-1];
      $separator = '';
      foreach ($components as $component)
      {
        $this->versions[$version] .= $separator . $component;
        $separator = "/"; 
      }
      
      if (file_exists($config->resource['path'] . $this->versions[$version]))
      {
        unlink($config->resource['path'] . $this->versions[$version]);
      }
    }
  }
}

Validator

class SiteimageValidator extends BaseSiteimageValidator
{
	function SiteimageValidator($post='', $files='') { $this->Initialise($post, $files); }

	function Populate($post='', $files='')
	{
		if (is_a($post, 'Siteimage'))
		{
			$this->id = $post->GetId();
			$this->user = $post->GetUser()->GetId();
			$this->name = $post->GetName();
			$this->label = $post->GetLabel();
		}
		else 
		{
			$this->id = $post['id'];
			$this->user = $post['user'];
			$this->name = $files['name'];
			$this->label = $post['label'];
		}
	}
		
	function Save()
	{
		$siteimage = new Siteimage();
		$siteimage = (empty($this->id)) ? new Siteimage() : $siteimage->GetMapper()->Find(new SiteImage($this->id));
		if ($this->name['error'] != UPLOAD_ERR_NO_FILE) $siteimage->SetFromRequest($this->name);
		$siteimage->SetUser(new User($this->user));
		$siteimage->SetLabel($this->label);
		return ($siteimage->Save()) ? $siteimage : false;
	}
		
	function isValid()
	{
		$this->errors = array();
						
		if (empty($this->label)) $this->errors[] = new Message('label', "You should type a unique label for the image.");
		else if (!$this->IsValidAlphanumeric($this->label)) $this->errors[] = new Message('label', "You can only have hyphens, spaces, letters and numbers in this field.");
		else
		{
			$siteimage_mapper = new Siteimages();
			$siteimage = $siteimage_mapper->FindByLabel($this->label);
				
			if (is_a($siteimage, 'Siteimage') && $siteimage->GetId() != $this->id) $this->errors[] = new Message('label', "Sorry, but that label is already in use for another image.");
		}
			
		if (($this->name['error'] != UPLOAD_ERR_NO_FILE && !empty($this->id)) || empty($this->id))
		{
			$file_error_message = $this->ValidateFile($this->name, array("image/jpeg", "image/jpg", "image/gif", "image/png"));
			if ((string)$file_error_message == "File type is not correct.") $this->errors[] = new Message('name', "You can only upload GIFs, PNGs or JPEGs. ");
			else if ($file_error_message !== true) $this->errors[] = new Message('name', $file_error_message);
		}
		if (!$this->IsValidInt($this->user)) $this->errors[] = new Message('user', "Can't find a user to add the image with.");

		return empty($this->errors);
	}
}

Mapper

class Siteimages extends Mapper
{
  function Save(&$object)
  {
    $action_text = ($object->isNew()) ? "insert into " : "update ";
    if (!$object->isNew()) $condition = "where id=" . $object->GetId();
      
    if ($object->GetTmpName() != "")
    {
      if (!$object->isNew())
      {
        $old_file = $object->GetName();
        $object->SetName();
      }
      if (!$object->SaveFile())
      {
        $session = new Session();
        $session->AddMessage(new Message('save', "There was a problem saving the file. "));
        return false;
      }
    }
    
    $sql_string = "
      $action_text  siteimages
      set        user    =" . $object->GetUser()->GetId() . ",
              name    ='" . $object->GetName() . "',
              type    ='" . $object->GetType() . "',
              size    ='" . $object->GetSize() . "',
              label    ='" . $object->GetLabel() . "'
      $condition
    ";
        
    if ($this->dao->ExecuteQuery($sql_string))
    {
      if (!$object->isNew() && $object->GetTmpName() != "")
      {
        $object->SetName($old_file);
        $object->DeleteFile();
      }
      if ($object->isNew()) $object->SetId(mysql_insert_id($this->dao->conn));
      return true;
    }
    else
    {
      $object->DeleteFile();
      return false;
    }
  }
}

Controller

class SiteimageController extends Controller
{
  function Input()
  {
    $siteimage_mapper = new Siteimages();
    $this->siteimage = $siteimage_mapper->Find(new Siteimage($this->get['id']));
    
    if (empty($this->post))
    {
      $this->form = new SiteimageValidator($this->siteimage);
      if (!is_a($this->siteimage, 'Siteimage')) $this->form->SetUser($this->session->user->GetId());
    }
    else
    {
      $this->form = new SiteimageValidator($this->post, $this->files);
        
      if ($this->form->isValid())
      {
        $siteimage = $this->form->Save();
        if ($siteimage instanceof Siteimage)
        {
          $this->session->AddMessage(new Message("success", "Your picture was saved successfully. "));
          $this->Redirect($this->MakeLink('siteimage', 'all'));
        }
        else
        {
          $this->session->AddMessage(new Message('database_error', "Couldn't save to the database. "));
        }
      }
    }
   
    $this->LoadTemplate("FormSiteimage");
  }
}

Template

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <? $this->LoadComponent('HeadTag'); ?>
  <body>
    <? $this->LoadComponent('AdminHeader'); ?>
    <div class="pod twoCol">
      <h2>Site Image Upload Form</h2>
      <div>
        <br>
        <?=$this->session->PrintMessages()?>
        <?=$this->form->PrintError('user')?>
				
        <form method='post' action='' enctype="multipart/form-data">
          <input type="hidden" class="hidden" name="MAX_FILE_SIZE" value="300000" /> 
          <input type='hidden' class="hidden" name='id' value='<?=$this->form->GetId()?>' />
          <input type='hidden' class="hidden" name='user' value='<?=$this->form->GetUser()?>' />
					
          <label for='label'>Label</label>
          <input type='text' name='label' value="<?=$this->form->GetLabel()?>" id='label' />
          <?=$this->form->PrintError('label')?>
          <br>

          <label for='name'>Image Location</label>
          <input type='file' name='name' value="" id='name' />
          <p>Please choose an image file to upload.</p>
          <?=$this->form->PrintError('name')?>
          <br>

          <? if ($this->siteimage instanceof Siteimage) { ?>
            <label>Current Image</label>
            <img src="<?=$this->siteimage->GetVersion('thumbnail')?>" />
            <br>
            <br>
          <? } ?>
          <label></label>
          <input type='submit' name='submit' value='Save' class='submit' />
        </form>
      </div>
    </div>
    <? $this->LoadComponent('PageFooter'); ?>
  </body>
</html>

<?=$this->config->resource['img']?>
<?=$this->config->resource['css']?>
<?=$this->config->resource['js']?>

helpers

makelink()
Creates an absolute url to a specified action in the site

<?=$this->MakeLink($controller, $function, $params)?>

<?=$this->MakeLink('signup')?>
=> http://westendvip.com/signup

<?=$this->MakeLink('offer', 'search', 'q=Good Offers')?>
=> http://westendvip.com/offer/search.html?q=Good Offers

PrintMessages()
Prints out all the messages in the session

<?=$this->session->PrintMessages($list_tag='', $list_css='', $item_tag='', $item_css)?>

<?=$this->session->PrintErrors('ul', 'list', 'li', 'item')?>
=> <ul class='list'><li class='item'>Message appears here</li></ul>

LoadComponent
If you have a fragment to load into a page use LoadComponent() – you don’t
need the .php extension

<? $this->LoadComponent($component, $param1, $param2, $param3); ?>

<? $this->LoadComponent('PageFooter'); ?>

So from now on when you get a file it’s an object and you access it’s location by calling its name method.

$file = new FileUpload();
$file->SetFromRequest($_FILES);
$file->SetUser(new User());
$file->Save();

The reason for these changes is to a) make file uploading more simple! and b) to make the validating of the file upload more accurate.

In the controller …

if (empty($this->post))
{
  $this->form = new PictureValidator($this->post, $this->files);
  if ($this->form->isValid())
  {
    $user = $this->form->Save();
    if ($user instanceof User)
    {
      $this->session->AddMessage(new Message("success", "Your picture was saved successfully."));
    }
    else
    {
      $this->session->AddMessage(new Message('database_error', "Couldn't save to the database"));
    }
  }
}

The validator has now got two new functions

function Initialise($post='', $files='')
{
  $this->config = new Config();
  $this->files = $files;
  $this->post = $post;
  $this->Populate($this->post, $this->files);
}

function Save()
{
  return $specified_domain_object;
}

function ValidateFile($value, $file_types=array())
{
  switch ($value['error'])
  {
    case UPLOAD_ERR_INI_SIZE: return "The uploaded file exceeds the upload_max_filesize directive in php.ini.";
    case UPLOAD_ERR_FORM_SIZE: return "The uploaded file exceeds the MAX_FILE_SIZE directive that was specified in the HTML form.";
    case UPLOAD_ERR_PARTIAL: return "The uploaded file was only partially uploaded.";
    case UPLOAD_ERR_NO_FILE: return "No file was uploaded.";
    case UPLOAD_ERR_NO_TMP_DIR: return "A server error is preventing file uploads. Please contact the site administrator.";
    case UPLOAD_ERR_CANT_WRITE: return "Failed to write file to disk.";
    case UPLOAD_ERR_EXTENSION: return "File upload stopped by extension.";
  }

  if (!in_array($value['type'], $file_types)) return "File type is not correct.";
  return true;
}

• The Widget Controller
• .htaccess Changes
• The Widget Container Front-End Component
• A _widgets directory
• Your First Widget

Widget Controller

The widget controller is basically a standard controller that then mimics the Loader class and loads the widget screens. It also provides a little support for Ajax links, so that you can put anchor links in your widgets and the response will come back to calling widget only.

// ================================================================================= //		

class WidgetController extends Controller
{
	// ============================================================================= //

	function All() {}
	function Input() {}
	function Delete() {}
	
	// ============================================================================= //
	
	function Run()
	{
		// expecting parameters: -
		//
		//	$this->get['widget'] = 'raketu'
		//	$this->get['screen'] = 'home';
		//
		// this widget would be available on the following URL: -
		//
		//	http://www.blah.com/widget/raketu/home.html
		
		// basically what do we have to do ...
		//
		//	1. get the widget's controller
		require_once "_widgets/" . $this->get['widget'] . "/Controller.php";
		//	2. get the widget 'screen' - basically this is the same as
		//	   running a regular command in Orqi.
		$controller_name = $this->get['widget'] . 'Controller';
		$action_name = $this->get['screen'];
		
		$widget_controller = new $controller_name();
		$widget_controller->Initialise($this->config, $this->session, $this->get, $this->post, $this->files);
		$widget_controller->$action_name();
	}
	
	// ============================================================================= //
	
	function LoadWidget($widget_name='', $screen='', $sendtoscreen=true)
	{
		if (!$sendtoscreen) ob_start();
		 
		switch (true)
		{
			case file_exists("_widgets/" . $widget_name . "/_" . $screen . ".php"):
				require "_widgets/" . $widget_name . "/_" . $screen . ".php";
				break;
			
			default:
				echo "<p>" . $widget_name . "'s' " . $screen . " screen is missing.</p>";
				break;
		}
		
		if (!$sendtoscreen)
		{
			$return_html = ob_get_contents();
			ob_end_clean();
			return $return_html;
		}
		else return false;
	}
	
	// ============================================================================= //
	
	function MakeWidgetLink($widget='', $screen='', $params='', $secure='')
	{
		if (empty($widget) || empty($screen)) return $this->config->app['location'] . '/';
		else
		{
			if ($this->config->app['mod_rewrite'] == false)
			{
				$site_text = (empty($this->config->app['default'])) ? "" : "site=" . $this->config->app['default'] . "&";
				$link_text = $this->config->app['location'] . "/index.php?" . $site_text . "object=widget&action=run&widget=" . $widget . "&screen=" . $screen;
				$separator = "&";
			}
			else
			{
				$site_text = (empty($this->config->app['default'])) ? "" : $this->config->app['default'] . "/";
				$link_text = $this->config->app['location'] . '/' . $site_text ."widget/" . $widget . "/" . $screen . "." . $this->config->app['extension'];
				$separator = "?";
			}
			
			if ($this->config->app['ssl'] == true && (!empty($_SERVER['HTTPS']) || $secure == true))
			{
				$link_text = str_replace('http:', 'https:', $link_text);
			}
			
			if (!empty($params)) $link_text .= $separator . $params;
			return "javascript: rh_" . $widget . ".LoadPart('widget_" . $widget . "', '" . $link_text . "');";
		}
	}
	
	// ============================================================================= //
}

// ================================================================================= //

.htaccess Changes

Put this line in your .htaccess file. You can get by without mod_rewrite, but I’d really recommend it as the urls can get proper tricky.

RewriteRule ^widget/(.*)/(.*).html$ index.php?object=widget&action=run&widget=$1&screen=$2&%{QUERY_STRING} [L]

The Widget Container Front-End Component

This is a work in progress very much meaning I’m not particularly happy with it’s state, but at least it is working. It will load a div with a specified ID and then give you a slice of supporting javascript that will wait for and process ajax instructions on that specified ID only.

<?
	// param1: is the name of the widget
	$separator = "?";
	$extra_parameters = "";
	
	if (!empty($param2))
	{
		$extra_parameters .= $separator . "param1=" . $param2;
		$separator = "&";
	}
	if (!empty($param3)) $extra_parameters .= $separator . "param2=" . $param3;
?>

<script>
	var ResponseHandlerFor_<?=$param1?> = function()
	{
		this.FillWidget = function(request)
		{
			$('widget_<?=$param1?>').innerHTML = request.responseText;
		}
		
		this.Oopslol = function()
		{
			$('widget_<?=$param1?>').innerHTML = "<h3>ooops.</h3><p>there was an error.</p>";
		}
	
		this.PreLoader = function(element_id)
		{
			$(element_id).innerHTML += "<p><img src='/_img/loading_animation.gif'></p>";
			return false;
		}
		
		this.LoadPart = function(element_id, url)
		{
			this.PreLoader(element_id);
			new Ajax.Request(url, {method:'get', onComplete:rh_<?=$param1?>.FillWidget, onFailure:rh_<?=$param1?>.Oopslol});
			return false;
		}
		
		this.PostForm = function(submit_form)
		{
			$(submit_form).request({onComplete:rh_<?=$param1?>.FillWidget, onFailure:rh_<?=$param1?>.Oopslol});
			$('widget_<?=$param1?>').innerHTML = "<h2>LOADING</h2><p>Please wait ...</p><p><img src='/_img/loading_animation.gif'></p>";
		}
		
		this.OnLoadHandler = function()
		{
			this.LoadPart('widget_<?=$param1?>', '/widget/<?=$param1?>/home.html<?=$extra_parameters?>');
		}
	}
	
	var rh_<?=$param1?> = new ResponseHandlerFor_<?=$param1?>();
</script>
<div class="widget" id="widget_<?=$param1?>" style="margin: 0px 5px 5px 0px; float: left; width: 300px; border: 1px dotted #ccc;"></div>
<script>rh_<?=$param1?>.OnLoadHandler();</script>

A _widgets directory

Create a directory called “_widgets” in your project root. It’s that simple.

Scriptaculous

Ah, yes. Without scriptaculous none of the AJAX stuff will work. Probably best to download it and put it in your “_js” directory. You can include scriptaculous site wide in your _HeadTag.php component.

<script src="<?=$this->config->resource['js']?>/scriptaculous.js" type="text/javascript" language="javascript" charset="utf-8"></script>

Your own widget

Please see the article entitled “Your First Widget” for more information.

Create your controller

For something simple like showing a template with just html, all we need for the controller, a class declaration and a single function containing the template call. If you create a file called “ExampleController.php”, fill it with the sample code below and put it in your “_classes/_app” directory.

class ExampleController extends Controller
{
	function MyFirstPage()
	{
		$this->LoadTemplate("MyFirstPage");
	}
}

Create your template

Because we named our template “MyFirstPage” in the controller, Orqi will be expecting a file in the template directory called “MyFirstPage.php”. So create it, and put the following code inside.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
	"http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>My First Orqi Page</title>
	</head>
	<body>
		<h1>My First Test Page</h1>
		<p>Wow that was so easy, I thought people said MVC
		was heavy handed and stuff? :D</p>
	</body>
</html>

Try it in a browser

Type http://localhost/yoursite/example/myfirstpage.html in to a browser and your should see: -

URLs

Notice the structure of the url. “example” will tell Orqi to call the “ExampleController” and “myfirstpage” will tell Orqi to look for a function within the controller called “myfirstpage”.

http://localhost/yoursite/example/myfirstpage.html

CssController

Create a controller called “CssController.php” in your controller folder “_classes/_app”. You don’t HAVE to call it CssController of course, I’m only doing this because I find Css a memorable name for css stuff :D

class CssController extends Controller
{
	function Dynamic()
	{
		header("Content-type: text/css");
		$this->LoadTemplate("DynamicCSS");
	}
}

CSS Template

OK so we put a file “DynamicCSS.php” in our templates directory “_classes/_ui/_pc” like so …

h1
{
background: url(<?=$this->config->resource['img']?>/header.gif) left top no-repeat;
}
#logo
{
background-image: url(<?=$this->config->resource['img']?>/logo.gif);
}

Your HTML Template

Then in your template you add the link to the stylesheet. Personally i put it in the “_HeadTag.php” component.

<link rel="stylesheet" href="<?=$this->MakeLink('css', 'dynamic')?>" />

In our example, let’s call the directory something like “mywidget”. You will need a Controller class in the directory that extends the WidgetController and you should name it’s file “Controller.php”. The code should look like this: -

class MyWidgetController extends WidgetController
{
	function Home()
	{
		$this->LoadWidget("mywidget", "Home");
	}
}

Every widget controller should have a Home() function in it, as this is looked for and called by Orqi when it tries to run or call a widget.

The LoadWidget() function in the code is the equivalent of the LoadComponent() function in the Controller superclass and you use it to return HTML to the user. It takes in the current widget name and the component name you are calling.

The HTML templates for the widgets should be put in the widget directory with the controller and they should be prefixed with an underscore, much the same as components.

<h3>My Widget</h3>
<p>Example HTML stuff.</p>
<p>You can even say hi to <?=$this->session->user->GetUsername()?>,
if they are logged in</p>

If you copy the above code, create a file called “_Home.php” in your widget directory and put the code in it that’s pretty much all you need to do to have a functioning widget working.

Running the Widget

If you go back to the main project, in any template add the following HTML/PHP

<? $this->LoadComponent("WidgetContainer", "mywidget"); ?>

Linking to screens in widgets

The WidgetController actually provides support for constructing your links in your widget html. If you use MakeWidgetLink() you can provide links for users that will keep them within the bounds of the widget and you can still access MakeLink() if you want to send users to brand new pages altogether.

<p><a href="#" onclick="<?=$this->MakeWidgetLink('mywidget', 'anotherpage')?>">Go to another screen!</a></p>

OK in typical Orqi fashion, for every action we expect to run in a controller there needs to be a function. “mywidget” tells Orqi to look for the “mywidget” directory in the “_widgets” directory and look for “Controller.php”.

“Anotherpage” tells Orqi to have a look in the controller for a function called “Anotherpage” and in that function we can execute our commands and display view, etc.

function Anotherpage()
{
	$this->LoadWidget("mywidget", "Anotherpagetemplate");
}

As you can see the LoadWidget() function is going to look for a template called “_Anotherpagetemplate.php”. If you create that file and paste the following code into it then you will have a working copy of a widget with links.

Notice that the new screen has a link back to the Home screen.

<h3>My Widget</h3>
<p>Another page</p>
<p><a href="#" onclick="<?=$this->MakeWidgetLink('mywidget', 'home')?>">back home</a></p>

If you try the widget again you will notice that you can now link between the screens.

Quick Word On Forms

Just a quick word on posting forms in widgets. The supporting javascript that is loaded with the widget divs in the “WidgetContainer” component comes with a PostForm function that will submit the request for you without loading an entirely new page.

All you have to remember is the following (see the code below)

• set the onsubmit attribute to “return false;”
• the action should be set to where you would normally post the form to (at the moment you should set it yourself)
• the submit button needs to call the PostForm() function in its onclick attribute

<form
	method="post"
	action="/widget/mywidget/somefunction.html"
	id='mywidget_form'
	onsubmit="return false;">
	
	<button onclick="javascript: rh_mywidget.PostForm('mywidget_form');">Submit</button>
</form>

All domain classes should extend the Mapper superclass so that you can take advantage of the auto functions !

If have a table like this …

CREATE TABLE `blogcomments` (
  `id` int(11) NOT NULL auto_increment,
  `posts_id` int(11) NOT NULL,
  `name` varchar(255) NOT NULL,
  `email` varchar(255) NOT NULL,
  `timestamp` int(11) NOT NULL,
  `approved` int(11) NOT NULL,
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM AUTO_INCREMENT=1 ;

You should fill in the mapper form like this (explanation to follow) …

The “posts_id” field in the database table is a link to the “posts” table. This means that the BlogComment object being passed into our mapper will most likely have an object as one of it’s members. So this means we need to give it the object’s name as well. Hence “posts_id, post”.

The “name” and “email” values you will notice are surrounded by quotemarks. This is because these fields are text and need surrounding by quote marks in the insert/update sql statements. Putting the quotemarks simply tells Orqi to do this as well.

Hit “Generate” and you will get a fille looking something like this.

// ================================================================================= //		

class BlogComments extends Mapper
{
	// ============================================================================= //

	function BlogComments()
	{
		$this->config = new Config();
		$this->dao = new DAO();
	}
	
	// ============================================================================= //
	
	function GetSelectBoxData()
	{
		$data = array();
		
		$sql_string = "select id as value, name as text from blogcomments order by name asc";
		$recordset = $this->dao->ExecuteQuery($sql_string);
		if ($recordset) while ($record = mysql_fetch_assoc($recordset)) $data[] = $record;
		
		return $data;
	}
	
	// ============================================================================= //
	
	function GetTotalRows()
	{
		$recordset = $this->dao->ExecuteQuery("select count(*) as total_rows from blogcomments");
		$record = mysql_fetch_assoc($recordset);
		return $record['total_rows'];
	}
	
	// ============================================================================= //
	
	function FindAll($page='')
	{
		$data = array();
		$sql_string = "select * from blogcomments order by name";
		
		if (!empty($page))
		{
			$cursor = ($page-1) * $this->config->page['items'];
			$sql_string .= "
				limit		" . $cursor . ", " . $this->config->page['items'] . "
			";
		}

		$recordset = $this->dao->ExecuteQuery($sql_string);
		if ($recordset) while ($record = mysql_fetch_assoc($recordset)) $data[] = Caster::Cast($record, new BlogComment());
		return $data;
	}
	
	// ============================================================================= //
	
	function Save(&$object)
	{
		$action_text = (!$object->GetId()) ? "insert into " : "update ";
		if ($object->GetId()) $condition = "where id=" . $object->GetId();
		
		$obj_post = $object->GetPost();

		$sql_string = "
			$action_text	blogcomments
			set				posts_id=" . $obj_post->GetId() . ",
							name='" . $object->GetName() . "',
							email='" . $object->GetEmail() . "',
							timestamp=" . $object->GetTimestamp() . ",
							approved=" . $object->GetApproved() . "
			$condition
		";

		if ($this->dao->ExecuteQuery($sql_string))
		{
			$this->success = true;
			if (!$object->GetId()) $object->SetId(mysql_insert_id($this->dao->conn));
		}
		else $this->success = false;
		return $this->success;
	}
	
	// ============================================================================= //
}

// ================================================================================= //

Explanation of the functions

Here is a quick explanation of the functions in this class …

Constructor

The constructor just instantiates a couple of class variables that we will need pretty much every funtion. The DAO object is obvious since most mappers have to talk to a database at some point their lives. The Config object is there so we can access stuff like the paging variables.

function BlogComments()
{
	$this->config = new Config();
	$this->dao = new DAO();
}

GetSelectBoxData

This function provides a full list of the table in a value/text pair form.

function GetSelectBoxData()
{
	$data = array();
	
	$sql_string = "select id as value, name as text from blogcomments order by name asc";
	$recordset = $this->dao->ExecuteQuery($sql_string);
	if ($recordset) while ($record = mysql_fetch_assoc($recordset)) $data[] = $record;
	
	return $data;
}

GetTotalRows

Returns the total number of rows in the table.

function GetTotalRows()
{
	$recordset = $this->dao->ExecuteQuery("select count(*) as total_rows from blogcomments");
	$record = mysql_fetch_assoc($recordset);
	return $record['total_rows'];
}

FindAll

This will return either a page of items or if no page parameter is passed, all the items in the table.

function FindAll($page='')
{
	$data = array();
	$sql_string = "select * from blogcomments order by name";
	
	if (!empty($page))
	{
		$cursor = ($page-1) * $this->config->page['items'];
		$sql_string .= "
			limit		" . $cursor . ", " . $this->config->page['items'] . "
		";
	}

	$recordset = $this->dao->ExecuteQuery($sql_string);
	if ($recordset) while ($record = mysql_fetch_assoc($recordset)) $data[] = Caster::Cast($record, new BlogComment());
	return $data;
}

Note: That the Caster is being used to return an object as opposed to just associative mysql array.

Save

This will save the object passed to it. Note that the parameter is passed by reference. This is to try and mimic java a little bit so that back in the calling function we can use the id after an insert easily.

function Save(&$object)
{
	$action_text = (!$object->GetId()) ? "insert into " : "update ";
	if ($object->GetId()) $condition = "where id=" . $object->GetId();
	
	$obj_post = $object->GetPost();

	$sql_string = "
		$action_text	blogcomments
		set				posts_id=" . $obj_post->GetId() . ",
						name='" . $object->GetName() . "',
						email='" . $object->GetEmail() . "',
						timestamp=" . $object->GetTimestamp() . ",
						approved=" . $object->GetApproved() . "
		$condition
	";

	if ($this->dao->ExecuteQuery($sql_string))
	{
		$this->success = true;
		if (!$object->GetId()) $object->SetId(mysql_insert_id($this->dao->conn));
	}
	else $this->success = false;
	return $this->success;
}

Note: Even though there is a validator framework to check for errors, this function may soon have a type check at the start to trap invalid objects being passed …

// something like this (in the example)
if (!is_a($object, 'BlogComment')) return false;

Common Usages

$control = new SelectBox($this->config, "Usergroups", "usergroups_id", "", "", $this->form->GetUsergroupId(), 'level <=' . $this->session->user_usergroup->GetLevel());

List Page

class AdvertController extends Controller
{
	function All()
	{
		$this->object = new Adverts();
		$this->data = $this->object->FindAll($this->page['current']);
		$this->LoadTemplate("ListAdverts");
	}
}		

Saving Stuff

$blogcomments_mapper = new BlogComments();
$blogcomment = new BlogComment();
$blogcomment->SetPost(new Post(1));
$blogcomment->SetName('N E Commenter');
$blogcomment->SetEmail('n.e.commenter@gmail.com');
$blogcomment->SetTimestamp(mktime());
$blogcomment->SetApproved(1);
$blogcomments_mapper->Save($blogcomment);

In Model Classes

class Post extends Object
{
	var $comments = array();
	
	function GetComments()
	{
		if (empty($this->comments))
		{
			$blogcomments_mapper = new BlogComments();
			$this->comments = $blogcomments_mapper->FindByPost($this);
		}
		return $this->comments;
	}
}

$config = new Config();

Page / Paging Variables

Typical values shown …

$config->page['referer']; // set automatically
$config->page['current']; // set automatically
$config->page['items'] = 20;

Database Connection Variables

These are the database details. Typical values shown …

$config->db['host'] = 'localhost';
$config->db['name'] = 'databasenamehere';
$config->db['user'] = 'yourusername';
$config->db['pass'] = 'yourpassword';

Application Variables

These are the application variables. Typical values shown (the telephotos website used as an example in this case) …

$this->app['location'] = "http://telephotos.co.uk";
$this->app['title'] = "Telephotos";
$this->app['author'] = "David George Hamilton";
$this->app['company'] = "Something Easy To Remember Ltd";
$this->app['default_lang'] = "English";
$this->app['mod_rewrite'] = true;
$this->app['unicode'] = true;
$this->app['cookiename'] = "telephotos";
$this->app['extension'] = "html";

Mail Settings

These variables define whether mail is setup on the server and the email address from which notices are sent. Typical values shown (the telephotos website used as an example in this case) …

$this->mail['name'] = "Telephotos";
$this->mail['address'] = "no-reply@telephotos.co.uk";
$this->mail['enabled'] = false;

Project File Location Variables

These variables are used for settings the location of your project files.

$this->classes['path'] = "_classes";
$this->classes['domain'] = $this->classes['path'] . "/_domain";
$this->classes['inf'] = $this->classes['path'] . "/_inf";
$this->classes['app'] = $this->classes['path'] . "/_app";
$this->classes['ui'] = $this->classes['path'] . "/_ui/_" . strtolower($this->app['client']);

Orqi Location Variables

These variables are used for setting the location of the Orqi files.

$this->orqi['path'] = "_orqi";
$this->orqi['domain'] = $this->orqi['path'] . "/_domain";
$this->orqi['app'] = $this->orqi['path'] . "/_app";
$this->orqi['inf'] = $this->orqi['path'] . "/_inf";
$this->orqi['ui'] = $this->orqi['path'] . "/_ui/_" . strtolower($this->app['client']);

Resource Variables

These variables are used for settings the location of front end stuff like images, css and javascript. The first two in the list ‘url’ and ‘path’ are for uploads. ‘path’ is the physical location in the directory structure on the server and ‘url’ is the address you then type into the browser to reach the uploaded file. Typical values shown (the telephotos website used as an example in this case) …

$this->resource['path'] = '/home/htdocs/telephotos.co.uk';
$this->resource['url'] = $this->app['location'];
$this->resource['img'] = $this->app['location'] . '/_img/_' . strtolower($this->app['client']);
$this->resource['css'] = $this->app['location'] . '/_css/_' . strtolower($this->app['client']);

• Table names are simply the plural state of the model class names
• Every table has an id field
  • it should be the primary key
  • it should be an auto_increment field
• Field names should all be in lower case.
• If a field links to another table, its name should be tablename_id
• If a field links to another table, it should be declared as an index

Take a look a the diagram below. It shows a sample table from a project. You will notice: -

• There is an id set as the primary key and setup as an auto increment field
• ajaxadverttypes_id is a link to another table
  • this field respresents the links between the object and the AjaxAdvertType object.
  • you can assume from the field name that there will be a table called ajaxadverttypes
• all the field names are in lowercase.

CREATE TABLE `ajaxadverts` (
  `id` int(11) NOT NULL auto_increment,
  `title` varchar(255) NOT NULL,
  `subtitle` varchar(255) NOT NULL,
  `details` text NOT NULL,
  `image` varchar(255) NOT NULL,
  `bkgimage` varchar(255) NOT NULL,
  `buylink` varchar(255) NOT NULL,
  `infolink` varchar(255) NOT NULL,
  `ajaxadverttypes_id` int(11) NOT NULL,
  `cssname` varchar(255) NOT NULL,
  `usage` varchar(255) NOT NULL,
  PRIMARY KEY  (`id`),
  KEY `AJAXADVERTTYPE` (`ajaxadverttypes_id`)
) ENGINE=MyISAM  AUTO_INCREMENT=1;