<?php
/**
 * A helper for constructing HTML forms
 *
 * @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 HtmlFormHelper extends BaseTemplateHelper {
	/**
	 * Wether the form tag is opened (keep at false or else your forms will
	 * never work!)
	 */
	private $formOpened = false;

	/**
	 * Name of the form
	 */
	private $formName = "";

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

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

	// Class Constants
	const EXCEPTION_FORM_NAME_INVALID = 0xb00;
	const EXCEPTION_CLOSED_FORM       = 0xb01;
	const EXCEPTION_OPENED_FORM       = 0xb02;

	/**
	 * Private constructor
	 *
	 * @return	void
	 */
	protected function __construct () {
		// Call parent constructor
		parent::__construct(__CLASS__);

		// Set part description
		$this->setObjectDescription("HTML-Formularhilfsklasse");
	}

	/**
	 * Creates the helper class with the given template engine instance and form name
	 *
	 * @param	$templateInstance	An instance of a valid template engine
	 * @param	$formName			Name of the form
	 * @param	$formId				Value for "id" attribute (default: $formName)
	 * @return	$helperInstance		A preparedf instance of this class
	 */
	public final static function createHtmlFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false) {
		// Get new instance
		$helperInstance = new HtmlFormHelper();

		// Set template instance
		$helperInstance->setTemplateInstance($templateInstance);

		// Is the form id not set?
		if ($formId === false) {
			// Use form id from form name
			$formId = $formName;
		}

		// Create the form
		$helperInstance->addFormTag($formName, $formId);

		// Return the prepared instance
		return $helperInstance;
	}

	/**
	 * Add the form tag or close it an already opened form tag
	 *
	 * @param	$formName	Name of the form (default: false)
	 * @param	$formId		Id of the form (attribute "id"; default: false)
	 * @return	void
	 * @throws	InvalidFormNameException	If the form name is invalid (=false)
	 */
	public function addFormTag ($formName = false, $formId = false) {
		// When the form is not yet opened at least form name must be valid
		if ((!$this->formOpened) && ($formName === false)) {
			// Thrown an exception
			throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID);
		}

		// Close the form is default
		$formContent = "</form>";

		// Check wether we shall open or close the form
		if (!$this->formOpened) {
			// Add HTML code
			$formContent = sprintf("<form name=\"%s\" action=\"%s\" method=\"%s\" target=\"%s\"",
				$formName,
				$this->getConfigInstance()->readConfig("form_action"),
				$this->getConfigInstance()->readConfig("form_method"),
				$this->getConfigInstance()->readConfig("form_target")
			);

			// Is the form id set?
			if ($formId !== false) {
				// Then add it as well
				$formContent .= sprintf(" id=\"%s\"",
					$formId
				);
			}

			// Add close bracket
			$formContent .= ">";

			// Open the form and remeber the form name
			$this->formOpened = true;
			$this->formName = $formName;
		} else {
			// Add the hidden field required to identify safely this form
			$this->addInputHiddenField("form", $this->formName);

			// @TODO Add some unique PIN here to bypass problems with some browser and/or extensions
			// Simply close it
			$this->formOpened = false;
		}

		// Add it to the content
		$this->addContent($formContent);
	}

	/**
	 * Add an input tag to the form or throw an exception if it is not yet
	 * opened. The field's name will be set as id.
	 *
	 * @param	$fieldName			Input field name
	 * @param	$fieldSize			Input size
	 * @param	$fieldMaxLength		Input max length
	 * @param	$fieldValue			Input default value (default: empty)
	 * @return	void
	 * @throws	FormClosedException		If the form is not yet opened
	 */
	public function addInputTextField ($fieldName, $fieldSize, $fieldMaxLength, $fieldValue = "") {
		// Is the form opened?
		if (!$this->formOpened) {
			// Throw an exception
			throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM);
		}

		// Generate the content
		$inputContent = sprintf("<input type=\"text\" id=\"%s\" name=\"%s\" size=\"%d\" maxlength=\"%d\" value=\"%s\" />",
			$fieldName, $fieldName, $fieldSize, $fieldMaxLength, $fieldValue);

		// And add it
		$this->addContent($inputContent);
	}

	/**
	 * Flushs the content out (not yet secured against open forms, etc.!) or
	 * throw an exception if it is not yet closed
	 *
	 * @return	void
	 * @throws	FormOpenedException		If the form is still open
	 */
	public function flushContent () {
		// Is the form opened?
		if ($this->formOpened) {
			// Throw an exception
			throw new FormOpenedException ($this, self::EXCEPTION_OPENED_FORM);
		}

		// Send content to template engine
		$this->getTemplateInstance()->assignVariable($this->formName, $this->getContent());
	}

	/**
	 * Add a form group or close an already opened and open a new one
	 *
	 * @param	$groupName	Name of the group
	 * @param	$groupText	Text including HTML to show above this group
	 * @return	void
	 * @throws	EmptyVariableException	If $groupName is not set
	 */
	public function addFormGroup ($groupName, $groupText) {
		// At least the group name should be set
		if (empty($groupName)) {
			// Throw exception here
			throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
		}

		// Not fully finished!
		$this->partialStub(__METHOD__);

		// Is this group opened?
		if (!$this->groupOpened) {
			// Switch the state
			$this->groupOpened = true;
		} else {
			// Switch the state
			$this->groupOpened = false;

			// All call it again
			$this->addFormGroup($groupName, $groupText);
		}
	}
}

// [EOF]
?>