* @version 0.0.0 * @copyright Copyright (c) 2007 - 2009 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 . */ class WebFormHelper extends BaseWebHelper implements HelpableTemplate { /** * 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 form tag is enabled (default: true) */ private $formEnabled = true; // Class Constants const EXCEPTION_FORM_NAME_INVALID = 0x120; const EXCEPTION_CLOSED_FORM = 0x121; const EXCEPTION_OPENED_FORM = 0x122; const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0x123; /** * Protected constructor * * @return void */ protected function __construct () { // Call parent constructor parent::__construct(__CLASS__); } /** * 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) * @param $withForm Wether include the form tag * @return $helperInstance A preparedf instance of this helper */ public final static function createWebFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false, $withForm = true) { // Get new instance $helperInstance = new WebFormHelper(); // Set template instance $helperInstance->setTemplateInstance($templateInstance); // Is the form id not set? if ($formId === false) { // Use form id from form name $formId = $formName; } // END - if // Set form name $helperInstance->setFormName($formName); // A form-less field may say "false" here... if ($withForm === true) { // Create the form $helperInstance->addFormTag($formName, $formId); } else { // Disable form $helperInstance->enableForm(false); } // 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) * @todo Add some unique PIN here to bypass problems with some browser and/or extensions */ public function addFormTag ($formName = false, $formId = false) { // When the form is not yet opened at least form name must be valid if (($this->formOpened === false) && ($formName === false)) { // Thrown an exception throw new InvalidFormNameException ($this, self::EXCEPTION_FORM_NAME_INVALID); } // END - if // Close the form is default $formContent = ""; // Check wether we shall open or close the form if (($this->formOpened === false) && ($this->formEnabled === true)) { // Add HTML code $formContent = sprintf("
getConfigInstance()->readConfig('base_url'), $this->getConfigInstance()->readConfig('form_action'), $this->getConfigInstance()->readConfig('form_method'), $this->getConfigInstance()->readConfig('form_target') ); // Add form id as well $formContent .= sprintf(" id=\"%s_form\'', $formId ); // Add close bracket $formContent .= ">"; // Open the form and remeber the form name $this->formOpened = true; // Add it to the content $this->addHeaderContent($formContent); } else { // Add the hidden field required to identify safely this form $this->addInputHiddenField('form', $this->getFormName()); // Is a group open? if ($this->ifGroupOpenedPreviously()) { // Then automatically close it here $this->addFormGroup(); } // END - if // Simply close it $this->formOpened = false; // Add it to the content $this->addFooterContent($formContent); } } /** * Add a text 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 $fieldValue Input default value (default: empty) * @return void * @throws FormClosedException If the form is not yet opened */ public function addInputTextField ($fieldName, $fieldValue = '') { // Is the form opened? if (($this->formOpened === false) && ($this->formEnabled === true)) { // Throw an exception throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM); } // END - if // Generate the content $inputContent = sprintf("", $fieldName, $fieldName, $fieldValue ); // And add it maybe with a "li" tag $this->addContentToPreviousGroup($inputContent); } /** * Add a text input tag to the form with pre-loaded default value * * @param $fieldName Input field name * @return void */ public function addInputTextFieldWithDefault ($fieldName) { // Get the value from instance $fieldValue = $this->getValueField($fieldName); //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."
\n"; // Add the text field $this->addInputTextField($fieldName, $fieldValue); } /** * Add a password 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 $fieldValue Input default value (default: empty) * @return void * @throws FormClosedException If the form is not yet opened */ public function addInputPasswordField ($fieldName, $fieldValue = '') { // Is the form opened? if (($this->formOpened === false) && ($this->formEnabled === true)) { // Throw an exception throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM); } // END - if // Generate the content $inputContent = sprintf("", $fieldName, $fieldName, $fieldValue ); // And add it $this->addContentToPreviousGroup($inputContent); } /** * Add a hidden 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 $fieldValue Input default value (default: empty) * @return void * @throws FormClosedException If the form is not yet opened */ public function addInputHiddenField ($fieldName, $fieldValue = '') { // Is the form opened? if (($this->formOpened === false) && ($this->formEnabled === true)) { // Throw an exception throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM); } // END - if // Generate the content $inputContent = sprintf("", $fieldName, $fieldValue ); // And add it $this->addContentToPreviousGroup($inputContent); } /** * Add a hidden input tag to the form with pre-loaded default value * * @param $fieldName Input field name * @return void */ public function addInputHiddenFieldWithDefault ($fieldName) { // Get the value from instance $fieldValue = $this->getValueField($fieldName); //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."
\n"; // Add the text field $this->addInputHiddenField($fieldName, $fieldValue); } /** * Add a hidden input tag to the form with configuration value * * @param $fieldName Input field name * @param $prefix Prefix for configuration without trailing _ * @return void */ public function addInputHiddenConfiguredField ($fieldName, $prefix) { // Get the value from instance $fieldValue = $this->getConfigInstance()->readConfig("{$prefix}_{$fieldName}"); //* DEBUG: */ echo __METHOD__.":".$fieldName."=".$fieldValue."
\n"; // Add the text field $this->addInputHiddenField($fieldName, $fieldValue); } /** * Add a checkbox 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 $fieldChecked Wether the field is checked (defaut: checked) * @return void * @throws FormClosedException If the form is not yet opened */ public function addInputCheckboxField ($fieldName, $fieldChecked = true) { // Is the form opened? if (($this->formOpened === false) && ($this->formEnabled === true)) { // Throw an exception throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM); } // END - if // Set wether the check box is checked... $checked = " checked=\"checked\''; if ($fieldChecked === false) $checked = " "; // Generate the content $inputContent = sprintf("", $fieldName, $fieldName, $checked ); // And add it $this->addContentToPreviousGroup($inputContent); } /** * Add a reset 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 $buttonText Text displayed on the button * @return void * @throws FormClosedException If the form is not yet opened */ public function addInputResetButton ($buttonText) { // Is the form opened? if (($this->formOpened === false) && ($this->formEnabled === true)) { // Throw an exception throw new FormClosedException (array($this, "reset"), self::EXCEPTION_CLOSED_FORM); } // END - if // Generate the content $inputContent = sprintf("", $this->getFormName(), $buttonText ); // And add it $this->addContentToPreviousGroup($inputContent); } /** * Add a reset 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 $buttonText Text displayed on the button * @return void * @throws FormClosedException If the form is not yet opened */ public function addInputSubmitButton ($buttonText) { // Is the form opened? if (($this->formOpened === false) && ($this->formEnabled === true)) { // Throw an exception throw new FormClosedException (array($this, "submit"), self::EXCEPTION_CLOSED_FORM); } // END - if // Generate the content $inputContent = sprintf("", $this->getFormName(), $this->getFormName(), $buttonText ); // And add it $this->addContentToPreviousGroup($inputContent); } /** * Add a form group or close an already opened and open a new one * * @param $groupId Name of the group or last opened if empty * @param $groupText Text including HTML to show above this group * @return void * @throws FormClosedException If no form has been opened before * @throws EmptyVariableException If $groupId is not set */ public function addFormGroup ($groupId = '', $groupText = '') { // Is a form opened? if (($this->formOpened === false) && ($this->formEnabled === true)) { // Throw exception here throw new FormClosedException(array($this, $groupId), self::EXCEPTION_CLOSED_FORM); } // END - if // At least the group name should be set if ((empty($groupId)) && ($this->ifGroupOpenedPreviously() === false)) { // Throw exception here throw new EmptyVariableException(array($this, 'groupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING); } elseif (empty($groupId)) { // Close the last opened $groupId = $this->getPreviousGroupId(); } // Same group to open? if (($this->ifGroupOpenedPreviously() === false) && ($groupId === $this->getPreviousGroupId())) { // Abort here silently return false; } // END - if // Initialize content with closing div by default $content = " \n"; // Is this group opened? if ($this->ifGroupOpenedPreviously() === false) { // Begin the div/span blocks $content = sprintf("
%s
", $groupId, $groupId, $groupId, $groupText, $groupId ); // Switch the state $this->openGroupByIdContent($groupId, $content, "div"); } else { // Is a sub group opened? if ($this->ifSubGroupOpenedPreviously()) { // Close it here $this->addFormSubGroup(); } // END - if // Get previous group id $prevGroupId = $this->getPreviousGroupId(); // Switch the state $this->closePreviousGroupByContent($content); // All call it again if group name is not empty if ((!empty($groupId)) && ($groupId != $prevGroupId)) { //* DEBUG: */ echo $groupId."/".$prevGroupId."
\n"; $this->addFormGroup($groupId, $groupText); } // END - if } } /** * Add a form sub group or close an already opened and open a new one or * throws an exception if no group has been opened before or if sub group * name is empty. * * @param $subGroupId Name of the group or last opened if empty * @param $subGroupText Text including HTML to show above this group * @return void * @throws FormFormClosedException If no group has been opened before * @throws EmptyVariableException If $subGroupId is not set */ public function addFormSubGroup ($subGroupId = '', $subGroupText = '') { // Is a group opened? if ($this->ifGroupOpenedPreviously() === false) { // Throw exception here throw new FormFormClosedException(array($this, $subGroupId), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP); } // END - if // At least the sub group name should be set if ((empty($subGroupId)) && ($this->ifSubGroupOpenedPreviously() === false)) { // Throw exception here throw new EmptyVariableException(array($this, 'subGroupId'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING); } elseif (empty($subGroupId)) { // Close the last opened $subGroupId = $this->getPreviousSubGroupId(); } // Same sub group to open? if (($this->ifSubGroupOpenedPreviously() === false) && ($subGroupId == $this->getPreviousSubGroupId())) { // Abort here silently return false; } // END - if // Initialize content with closing div by default $content = "
\n
"; // Is this group opened? if ($this->ifSubGroupOpenedPreviously() === false) { // Begin the span block $content = sprintf("
%s
", $subGroupId, $subGroupId, $subGroupId, $subGroupText, $subGroupId ); // Switch the state and remeber the name $this->openSubGroupByIdContent($subGroupId, $content, "div"); } else { // Get previous sub group id $prevSubGroupId = $this->getPreviousSubGroupId(); // Switch the state $this->closePreviousSubGroupByContent($content); // All call it again if sub group name is not empty if ((!empty($subGroupId)) && ($subGroupId != $prevSubGroupId)) { $this->addFormSubGroup($subGroupId, $subGroupText); } // END - if } } /** * Add text surrounded by a span block when there is a group opened before * or else by a div block. * * @param $fieldName Field name * @param $fieldText Text for the field * @return void * @throws FormClosedException If the form is not yet opened */ public function addFieldText ($fieldName, $fieldText) { // Is the form opened? if (($this->formOpened === false) && ($this->formEnabled === true)) { // Throw an exception throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM); } // END - if // Set the block type $block = "div"; if ($this->ifGroupOpenedPreviously()) $block = "span"; // Generate the content $inputContent = sprintf(" <%s id=\"%s_text\"> %s ", $block, $fieldName, $fieldText, $block ); // And add it $this->addContentToPreviousGroup($inputContent); } /** * Add text (notes) surrounded by a div block. Still opened groups or sub * groups will be automatically closed. * * @param $noteId Id for this note * @param $formNotes The form notes we shell addd * @return void * @throws FormClosedException If the form is not yet opened */ public function addFormNote ($noteId, $formNotes) { // Is the form opened? if (($this->formOpened === false) && ($this->formEnabled === true)) { // Throw an exception throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM); } // END - if // Generate the content $inputContent = sprintf("
%s
", $noteId, $formNotes ); // And add it $this->addContentToPreviousGroup($inputContent); } /** * Adds a selection box as a sub group to the form. Do not box this into * another sub group. Sub-sub groups are not (yet) supported. * * @param $selectId Id of the selection box * @param $firstEntry Content to be added as first non-selectable entry * @return void * @throws FormClosedException If the form is not yet opened */ public function addInputSelectField ($selectId, $firstEntry) { // Is the form group opened? if (($this->formOpened === false) && ($this->formEnabled === true)) { // Throw an exception throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM); } // END - if // Shall we close or open the sub group? if (($this->ifSubGroupOpenedPreviously() === false) && ($this->getPreviousSubGroupId() !== $selectId)) { // Initialize first entry (which might be non-selectable if content is provided if (!empty($firstEntry)) { // Add selection around it $firstEntry = sprintf("\n", $firstEntry ); } // END - if // Construct the opening select tag $content = sprintf(""); } } /** * Adds a non-selectable sub option to a previously added selection box. * This method does *not* validate if there is already a sub option added * with the same name. We need to finish this here! * * @param $subName Name of the sub action * @param $subValue Value of the sub action * @return void * @throws HelperNoPreviousOpenedSubGroupException If no previously opened sub group was found * @todo Add checking if sub option is already added */ public function addSelectSubOption ($subName, $subValue) { // Is there a sub group (shall be a selection box!) if ($this->ifSubGroupOpenedPreviously() === false) { // Then throw an exception here throw new HelperNoPreviousOpenedSubGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED); } // END - if // Render the content $content = sprintf("\n", $subName, $subValue ); // Add the content to the previously opened sub group $this->addContentToPreviousGroup($content); } /** * Adds a selectable option to a previously added selection box. This method * does *not* validate if there is already a sub option added with the same * name. We need to finish this here! * * @param $optionName Name of the sub action * @param $optionValue Value of the sub action * @return void * @throws HelperNoPreviousOpenedSubGroupException If no previously opened sub group was found * @todo Add checking if sub option is already added */ public function addSelectOption ($optionName, $optionValue) { // Is there a sub group (shall be a selection box!) if ($this->ifSubGroupOpenedPreviously() === false) { // Then throw an exception here throw new HelperNoPreviousOpenedSubGroupException(array($this, $content), self::EXCEPTION_NO_PREVIOUS_SUB_GROUP_OPENED); } // END - if // Render the content $content = sprintf("\n", $optionName, $optionName, $optionValue ); // Add the content to the previously opened sub group $this->addContentToPreviousGroup($content); } /** * Adds a pre-configured CAPTCHA * * @return void */ public function addCaptcha () { // Get last executed pre filter $extraInstance = Registry::getRegistry()->getInstance('extra'); // Get a configured instance $captchaInstance = ObjectFactory::createObjectByConfiguredName($this->getFormName().'_captcha', array($this, $extraInstance)); // Initiate the CAPTCHA $captchaInstance->initiateCaptcha(); // Render the CAPTCHA code $captchaInstance->renderCode(); // Get the content and add it to the helper $this->addContentToPreviousGroup($captchaInstance->renderContent()); } /** * Enables/disables the form tag usage * * @param $formEnabled Wether form is enabled or disabled * @return void */ public final function enableForm ($formEnabled = true) { $this->formEnabled = (bool) $formEnabled; } /** * Setter for form name * * @param $formName Name of this form * @return void */ public final function setFormName ($formName) { $this->formName = (string) $formName; } /** * Getter for form name * * @return $formName Name of this form */ public final function getFormName () { return $this->formName; } /** * Checks wether the registration requires a valid email address * * @return $required Wether the email address is required */ public function ifRegisterRequiresEmailVerification () { $required = ($this->getConfigInstance()->readConfig('register_requires_email') === "Y"); return $required; } /** * Checks wether profile data shall be asked * * @return $required Wether profile data shall be asked */ public function ifRegisterIncludesProfile () { $required = ($this->getConfigInstance()->readConfig('register_includes_profile') === "Y"); return $required; } /** * Checks wether this form is secured by a CAPTCHA * * @return $isSecured Wether this form is secured by a CAPTCHA */ public function ifFormSecuredWithCaptcha () { $isSecured = ($this->getConfigInstance()->readConfig($this->getFormName().'_captcha_secured') === "Y"); return $isSecured; } /** * Flushs the content out (not yet secured against open forms, etc.!) or * close the form automatically * * @return void * @throws FormOpenedException If the form is still open */ public function flushContent () { // Is the form still open? if (($this->formOpened === true) && ($this->formEnabled === true)) { // Close the form automatically $this->addFormTag(); } elseif ($this->formEnabled === false) { if ($this->ifSubGroupOpenedPreviously()) { // Close sub group $this->addFormSubGroup(); } elseif ($this->ifGroupOpenedPreviously()) { // Close group $this->addFormGroup(); } } // Send content to template engine //* DEBUG: */ echo __METHOD__.": form=".$this->getFormName().", size=".strlen($this->renderContent())."
\n"; $this->getTemplateInstance()->assignVariable($this->getFormName(), $this->renderContent()); } } // [EOF] ?>