<?php
/**
 * Copyright 2011 Peter Monks. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 * 
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 
 * THIS SOFTWARE IS PROVIDED BY PETER MONKS ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL PETER MONKS OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 * 
 * The views and conclusions contained in the software and documentation
 * are those of the authors and should not be interpreted as representing
 * official policies, either expressed or implied, of Peter Monks.
 *
 * @package Template
 */

/** #@+
 * Constants
 */
/**
 * Login requirements
 */
define('LOGIN_REQUIRED', 1);

class Template {
	/**
	 * The before and after content variables determine which and in what
	 * order global template files will be incorporated into the final output
	 * @access private
	 * @var (string)array
	 */
	private $beforeContent = array("header", "contentstart");
	/**
	 * @access private
	 * @var (string)array
	 */
	private $afterContent = array("contentend", "footer");
	/**
	 * The home of this file and its template directory
	 * @access private
	 * @var string
	 */
	private $directoryRoot;
	/**
	 * The directory that templates themselves sit in
	 * @access private
	 * @var string
	 */
	private $templateDirectory;
	/**
	 * The directory that the global template files sit in
	 * @access private
	 * @var string
	 */
	private $globalsDirectory;

	/**
	 * The collection of errors that came from the template processing
	 * @access private
	 * @var (string)array
	 */
	private $error = array();

	/**
	 * Instance variable for the template
	 * @static
	 * @access private
	 * @var Template
	 */
	private static $template = null;

	/**
	 * Storage of variables for use in the template files themselves
	 * @access private
	 * @var array
	 */
	private $variables = array();

	/**
	 * Retrieves the instance variable.  Creates it first if needed
	 * @access private
	 * @static
	 * @return Template
	 */
	private static function getInstance() {
		if (self::$template == null) {
			self::$template = new Template();
		}
		return self::$template;
	}

	/**
	 * Processes a specific template and generates a complete page.
	 *
	 * This is the heavy lifting function.  It takes all of the
	 * options and outputs the completed page, or an error if
	 * there were problems.  If the optional second arg is provided,
	 * instead of outputting, the completed page will instead be
	 * stored in that variable.
	 * @static
	 * @access public
	 * @return boolean
	 * @param string $templateName name of the template to be run
	 * @param (string)array $variables Any variables the templates need
	 * @param mixed &$return variable to store output in
	*/
	public static function process($templateName,
																 $variables = array(),
																 &$return = null) {
		$template = self::getInstance();
		$template->variables = $variables;

		// Look for the noglobals variables.  If they're present, use them,
		// otherwise, just set them to true.
		if (isset($variables['noBeforeGlobals'])) {
			$processBeforeGlobals = $variables['noBeforeGlobals'];
		}
		else {
			$processBeforeGlobals = true;
		}
		if (isset($variables['noAfterGlobals'])) {
			$processAfterGlobals = $variables['noAfterGlobals'];
		}
		else {
			$processAfterGlobals = true;
		}

		// Output the global files for before the content block if necessary
		if ($processBeforeGlobals) {
			ob_start();
			$template->processGlobals($template->beforeContent);
			$before = ob_get_contents();
			ob_end_clean();
		}

		// Output the content itself
		ob_start();
		if (isset($variables['login']) &&
				$variables['login'] == LOGIN_REQUIRED &&
				$template->loginFound() == false) {
			// Retarget the template to load the URL with a redirect to
			// the previous page
			$templateName = "login";
			$protocol = $_SERVER['HTTPS'] == "on" ? "s" : "";
			$url = "http{$protocol}://" .
				$_SERVER['SERVER_NAME'] .
				$_SERVER['REQUEST_URI'];
			$template->variables['templateUrl'] = $url;
		}
		$template->processFile($templateName);
		$content = ob_get_contents();
		ob_end_clean();

		// Output the global files for after the content block
		if ($processAfterGlobals) {
			ob_start();
			$template->processGlobals($template->afterContent);
			$after = ob_get_contents();
			ob_end_clean();
		}

		if (!empty($template->error)) {
			$error = $template->errorBox();
		}
		else {
			$error = "";
		}

		// If the return variable is set, store the output in it.
		// Otherwise, print it out.
		if ($return === null) {
			echo $before, $error, $content, $after;
		}
		else {
			$return = $before . $error . $content . $after;
		}
		return true;
	}

	/**
	 * Processes a list of files from the global template directory
	 * @access private
	 * @param (string)array $globalfiles All files to be processed
	 */
	private function processGlobals($globalfiles = array()) {
		$template = self::getInstance();
		foreach ($globalfiles as $file) {
			$this->loadFile($this->globalsDirectory . $file);
		}
	}

	/**
	 * Includes a standard template file into the output
	 * @access public
	 * @param string $filename Name of file to be processed
	 */
	public function processFile($filename) {
		$template = self::getInstance();
		$this->loadFile($template->templateDirectory . $filename);
	}

	/**
	 * Does the actual work of processing a given file.  When the file is
	 * processed, the Template instance is available to it as $t.  If the
	 * file cannot be loaded, it adds the raised exception to the list of
	 * errors.
	 * @access private
	 * @param string $fullpath The absolute directory path to the file
	 */
	private function loadFile($fullpath) {
		$t = self::getInstance();
		$loadFunction = function() use ($fullpath, $t) {
			if (is_readable($fullpath)) {
				require $fullpath;
			}
			else {
				$t->addError("$fullpath is inaccessible");
			}
		};
		$loadFunction();
	}

	/**
	 * Function for the templates to access the provided variables.
	 *
	 * To help the divide between the controls and the presentation, only
	 * variables that the program has specifically marked will be shown
	 * to the template.  Inside the templates, the Template instance will
	 * be available as <code>$t</code> and <code>$t->vars(varname)</code>
	 * can be used to retrieve those variables that were made available.
	 * @access public
	 * @param string $key The variable to be retrieved
	 * @return string|null If found, the value.  Otherwise null.
	 */
	public function vars($key) {
		if (isset($this->variables[$key])) {
			return $this->variables[$key];
		}
		else {
			return null;
		}
	}

	private function loginFound() {
		// This function is just a stub.  Do whatever to have it check to see
		// if you have a logged in user.  Return true with a valid login, or
		// false without.
		return true;
	}

	/**
	 * Generates some HTML presenting an error box, to avoid problems of
	 * access errors of a template to generate it, because if I try to have
	 * a template to generate the message about template errors, I'll
	 * eventually modify this and lock everything into an endless loop.
	 * @access private
	 * @return string
	 */
	private function errorBox() {
		$template = Template::getInstance();
		$errors = array_map(
												function($err) {
													return "<span class='templateError'>"
														. $err
														. "</span>";
												},
												$template->getError()
												);
		return "<div id=\"templateErrorMessage\">" .
			implode("<br />", $errors) .
			"</div>";
	}
	/**
	 * Registers an error string
	 * @access public
	 * @param string $errorMsg The message to be added
	 */
	public function addError($errorMsg) {
		$template = Template::getInstance();
		array_push($template->error, $errorMsg);
	}
	/**
	 * Returns all of the errors that has been registered
	 * @access public
	 * @returns (string)array
	 */
	public function getError() {
		$template = Template::getInstance();
		return $template->error;
	}

	/**
	 * Constructor sets up {@link $directoryRoot},
	 * {@link $templateDirectory}, and {@link $globalsDirectory}.
	 */
	public function __construct() {
		$this->directoryRoot = dirname(__FILE__);
		$this->templateDirectory = $this->directoryRoot . "/templates/";
		$this->globalsDirectory = $this->templateDirectory . "global/";
	}
}
?>