<?php
/**
 * A generic helper class with generic methods
 *
 * @author		Roland Haeder <webmaster@ship-simu.org>
 * @version		0.0.0
 * @copyright	Copyright (c) 2007, 2008 Roland Haeder, this is free software
 * @license		GNU GPL 3.0 or any newer version
 * @link		http://www.ship-simu.org
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */
class BaseHelper extends BaseFrameworkSystem {
	/**
	 * Instance to the class which provides field values
	 */
	private $valueInstance = null;

	/**
	 * Rendered content created by the helper class
	 */
	private $content = "";

	/**
	 * Wether the group is opened or not
	 */
	private $groupOpened = false;

	/**
	 * Wether the sub group is opened or not
	 */
	private $subGroupOpened = false;

	/**
	 * Name of the group
	 */
	private $groupName = "";

	/**
	 * Name of the sub group
	 */
	private $subGroupId = "";

	/**
	 * Previously opened group
	 */
	private $previousGroupId = "";

	/**
	 * Previously opened sub group
	 */
	private $previousSubGroupId = "";

	// Exception constants
	const EXCEPTION_XML_PARSER_ERROR  = 0x1e0;
	const EXCEPTION_XML_NODE_UNKNOWN  = 0x1e1;
	const EXCEPTION_XML_NODE_MISMATCH = 0x1e2;
	const EXCEPTION_GROUP_NOT_OPENED  = 0x1e3;

	/**
	 * Protected constructor
	 *
	 * @param	$className	Real name of the class
	 * @return	void
	 */
	protected function __construct ($className) {
		// Call parent constructor
		parent::__construct($className);

		// Clean up a little
		$this->removeNumberFormaters();
		$this->removeSystemArray();
	}

	/**
	 * Add content
	 *
	 * @param	$newContent		New content to add
	 * @return	void
	 */
	protected final function addContent ($newContent) {
		$this->content .= (string) trim($newContent) . "\r\n";
	}

	/**
	 * Getter for content
	 *
	 * @return	$content	The rendered content by this helper
	 */
	protected final function getContent () {
		return $this->content;
	}

	/**
	 *  Assigns a field from the value instance with a template variable
	 *
	 * @param	$fieldName	Name of the field to assign
	 * @return	void
	 */
	public function assignField ($fieldName) {
		// Get the value from value instance
		$fieldValue = $this->getValueField($fieldName);

		// Assign it with a template variable
		$this->getTemplateInstance()->assignVariable('block_' . $fieldName, $fieldValue);
	}

	/**
	 * Assigns a field from the value instance with a template variable but
	 * parses its content through a given filter method of the value instance
	 *
	 * @param	$fieldName		Name of the field to assign
	 * @param	$filterMethod	Method name to call of the value instance
	 * @return	void
	 * @todo	Rewrite this method using a helper class for filtering data
	 */
	public function assignFieldWithFilter ($fieldName, $filterMethod) {
		// Get the value
		$fieldValue = $this->getValueField($fieldName);

		// Now filter it through the value through the filter method
		$filteredValue = call_user_func_array(array($this, 'doFilter' . $this->convertToClassName($filterMethod)), array($fieldValue));

		// Assign it with a template variable
		$this->getTemplateInstance()->assignVariable('block_' . $fieldName, $filteredValue);
	}

	/**
	 * Pre-fetches field default values from the given registry key instance into this class
	 *
	 * @param	$registryKey	Registry key which holds an object with values
	 * @param	$extraKey		Extra value instance key used if registryKey is null
	 * @return	void
	 * @throws	NullPointerException	If recovery of requested value instance failed
	 */
	public function prefetchValueInstance ($registryKey, $extraKey = null) {
		// Get the required instance
		$this->valueInstance = Registry::getRegistry()->getInstance($registryKey);

		// Is the instance valid?
		if (is_null($this->valueInstance)) {
			// Try to create it "from scratch", by first init extra instance
			$extraInstance = null;

			// Shall we get an extra instance?
			if (!is_null($extraKey)) {
				// Get the extra instance.
				$extraInstance = Registry::getRegistry()->getInstance($extraKey);
			} // END - if

			// Get the requested instance
			try {
				$this->valueInstance = ObjectFactory::createObjectByConfiguredName($registryKey . '_class', array($extraInstance));

			} catch (FrameworkException $e) {
				// Okay, nothing found so throw a null pointer exception here
				throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
			}
		} // END - if
	}

	/**
	 * Getter for direct field values
	 *
	 * @param	$fieldName		Name of the field we shall fetch
	 * @return	$fieldValue		Value from field
	 */
	public function getValueField ($fieldName) {
		// Get the field value
		$fieldValue = call_user_func_array(array($this->valueInstance, 'getField'), array($fieldName));

		// Return it
		return $fieldValue;
	}

	/**
	 * Getter for value instance
	 *
	 * @return	$valueInstance	Instance of the class holding our values
	 */
	public final function getValueInstance () {
		return $this->valueInstance;
	}

	/**
	 * Check wether a group was opened previously
	 *
	 * @return	$groupOpened	Wether any group was opened before
	 */
	protected final function ifGroupOpenedPreviously () {
		$groupOpened = (!empty($this->previousGroupId));
		return $groupOpened;
	}

	/**
	 * Check wether a group was opened previously
	 *
	 * @return	$subGroupOpened		Wether any group was opened before
	 */
	protected final function ifSubGroupOpenedPreviously () {
		$subGroupOpened = (!empty($this->previousSubGroupId));
		return $subGroupOpened;
	}

	/**
	 * Getter for previous group id
	 *
	 * @return	$previousGroupId	Id of previously opened group
	 */
	protected final function getPreviousGroupId () {
		return $this->previousGroupId;
	}

	/**
	 * Setter for previous group id
	 *
	 * @param	$previousGroupId	Id of previously opened group
	 * @return	void
	 */
	protected final function setPreviousGroupId ($previousGroupId) {
		$this->previousGroupId = (string) $previousGroupId;
	}

	/**
	 * Getter for previous sub group id
	 *
	 * @return	$previousSubGroupId	Id of previously opened sub group
	 */
	protected final function getPreviousSubGroupId () {
		return $this->previousSubGroupId;
	}

	/**
	 * Setter for previous sub group id
	 *
	 * @param	$previousSubGroupId	Id of previously opened sub group
	 * @return	void
	 */
	protected final function setPreviousSubGroupId ($previousSubGroupId) {
		$this->previousSubGroupId = (string) $previousSubGroupId;
	}
}

// [EOF]
?>