* @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 . */ class WebFormHelper extends BaseHelper { /** * Instance to the class which provides field values */ private $valueInstance = null; /** * 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; /** * Name of the sub group */ private $subGroupName = ""; // Class Constants const EXCEPTION_FORM_NAME_INVALID = 0x030; const EXCEPTION_CLOSED_FORM = 0x031; const EXCEPTION_OPENED_FORM = 0x032; const EXCEPTION_UNEXPECTED_CLOSED_GROUP = 0x033; /** * Protected constructor * * @return void */ protected function __construct () { // Call parent constructor parent::__construct(__CLASS__); // Set part description $this->setObjectDescription("Helper class for HTML forms"); // Create unique ID number $this->generateUniqueId(); } /** * 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 createWebFormHelper (CompileableTemplate $templateInstance, $formName, $formId = false) { // 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; } // Create the form $helperInstance->addFormTag($formName, $formId); // Return the prepared instance return $helperInstance; } /** * Pre-fetches field default values from the given registry key instance into this class * * @param $registryKey * @return void * @throws NullPointerException If an instance from registry is null */ public function prefetchFieldValues ($registryKey) { // Get the required instance $this->valueInstance = Registry::getRegistry()->getInstance($registryKey); // Is the instance valid? if (is_null($this->valueInstance)) { // Throw an exception throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER); } // END - if } /** * 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 === 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) { // Add HTML code $formContent = sprintf("
getConfigInstance()->readConfig('base_url'), $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_form\"", $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); // Is a group open? if ($this->groupOpened === true) { // Then automatically close it here $this->addFormGroup("", ""); } // END - if /* @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 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) { // 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->addContent($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 = call_user_func_array(array($this->valueInstance, "getField"), array($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) { // 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->addContent($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) { // 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->addContent($inputContent); } /** * 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) { // 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->addContent($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) { // Throw an exception throw new FormClosedException (array($this, "reset"), self::EXCEPTION_CLOSED_FORM); } // END - if // Generate the content $inputContent = sprintf("", $this->formName, $buttonText ); // And add it $this->addContent($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) { // Throw an exception throw new FormClosedException (array($this, "submit"), self::EXCEPTION_CLOSED_FORM); } // END - if // Generate the content $inputContent = sprintf("", $this->formName, $this->formName, $buttonText ); // And add it $this->addContent($inputContent); } /** * 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 FormClosedException If no form has been opened before * @throws EmptyVariableException If $groupName is not set */ public function addFormGroup ($groupName, $groupText) { // Is a form opened? if ($this->formOpened === false) { // Throw exception here throw new FormClosedException(array($this, $groupName), self::EXCEPTION_CLOSED_FORM); } // END - if // At least the group name should be set if ((empty($groupName)) && ($this->groupOpened === false)) { // Throw exception here throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING); } // END - if // Initialize content with closing div by default $content = " \n"; // Is this group opened? if ($this->groupOpened === false) { // Begin the div/span blocks $content = sprintf("
%s
", $groupName, $groupName, $groupName, $groupText, $groupName ); // Add the content $this->addContent($content); // Switch the state $this->groupOpened = true; } else { // Is a sub group opened? if ($this->subGroupOpened === true) { // Close it here $this->addFormSubGroup("", ""); } // END - if // Add the content $this->addContent($content); // Switch the state $this->groupOpened = false; // All call it again if the group name is not empty if (!empty($groupName)) { $this->addFormGroup($groupName, $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 the sub * group name is empty. * * @param $subGroupName Name of the group * @param $subGroupText Text including HTML to show above this group * @return void * @throws FormGroupClosedException If no group has been opened before * @throws EmptyVariableException If $subGroupName is not set */ public function addFormSubGroup ($subGroupName, $subGroupText) { // Is a group opened? if ($this->groupOpened === false) { // Throw exception here throw new FormGroupClosedException(array($this, $subGroupName), self::EXCEPTION_UNEXPECTED_CLOSED_GROUP); } // END - if // At least the sub group name should be set if ((empty($subGroupName)) && ($this->subGroupOpened === false)) { // Throw exception here throw new EmptyVariableException(array($this, 'groupName'), self::EXCEPTION_UNEXPECTED_EMPTY_STRING); } // END - if // Initialize content with closing div by default $content = "
\n
"; // Is this group opened? if ($this->subGroupOpened === false) { // Begin the span block $content = sprintf("
%s
", $subGroupName, $subGroupName, $subGroupName, $subGroupText, $subGroupName ); // Add the content $this->addContent($content); // Switch the state and remeber the name $this->subGroupOpened = true; $this->subGroupName = $subGroupName; } else { // Add the content $this->addContent($content); // Switch the state $this->subGroupOpened = false; // All call it again if sub group name is not empty if (!empty($subGroupName)) { $this->addFormSubGroup($subGroupName, $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) { // Throw an exception throw new FormClosedException (array($this, $fieldName), self::EXCEPTION_CLOSED_FORM); } // END - if // Set the block type $block = "div"; if ($this->groupOpened === true) $block = "span"; // Generate the content $inputContent = sprintf(" <%s id=\"%s_text\"> %s ", $block, $fieldName, $fieldText, $block ); // And add it $this->addContent($inputContent); } /** * Add text (notes) surrounded by a div block. Still opened groups or sub * groups will be automatically closed. * * @param $formNotes The form notes we shell addd * @return void * @throws FormClosedException If the form is not yet opened */ public function addFormNote ($formNotes) { // Is the form opened? if ($this->formOpened === false) { // Throw an exception throw new FormClosedException (array($this, "form_notes"), self::EXCEPTION_CLOSED_FORM); } // END - if // Is a group open? if ($this->groupOpened === true) { // Then automatically close it here $this->addFormGroup("", ""); } // END - if // Generate the content $inputContent = sprintf("
%s
", $formNotes ); // And add it $this->addContent($inputContent); } /** * 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 shall be asked */ public function ifRegisterIncludesProfile () { $required = ($this->getConfigInstance()->readConfig('register_includes_profile') == "Y"); return $required; } /** * Checks wether personal data shall be asked * * @return $required Wether personal data shall be asked */ public function ifRegisterIncludesPersonaData () { $required = ($this->getConfigInstance()->readConfig('register_personal_data') == "Y"); return $required; } /** * Checks wether email addresses can only be once used * * @return $isUnique */ public function ifEmailMustBeUnique () { $isUnique = ($this->getConfigInstance()->readConfig('register_email_unique') == "Y"); return $isUnique; } /** * Checks wether the specified chat protocol is enabled in this form * * @return $required Wether the specified chat protocol is enabled */ public function ifChatEnabled ($chatProtocol) { $required = ($this->getConfigInstance()->readConfig(sprintf("chat_enabled_%s", $chatProtocol)) == "Y"); return $required; } /** * Checks wether login is enabled or disabled * * @return $isEnabled Wether the login is enabled or disabled */ public function ifLoginIsEnabled () { $isEnabled = ($this->getConfigInstance()->readConfig('login_enabled') == "Y"); return $isEnabled; } /** * Checks wether login shall be done by username * * @return $isEnabled Wether the login shall be done by username */ public function ifLoginWithUsername () { $isEnabled = ($this->getConfigInstance()->readConfig('login_type') == "username"); return $isEnabled; } /** * Checks wether login shall be done by email * * @return $isEnabled Wether the login shall be done by email */ public function ifLoginWithEmail () { $isEnabled = ($this->getConfigInstance()->readConfig('login_type') == "email"); return $isEnabled; } /** * Checks wether guest login is allowed * * @return $isAllowed Wether guest login is allowed */ public function ifGuestLoginAllowed () { $isAllowed = ($this->getConfigInstance()->readConfig('guest_login_allowed') == "Y"); return $isAllowed; } /** * Checks wether the email address change must be confirmed * * @return $requireConfirm Wether email change must be confirmed */ public function ifEmailChangeRequireConfirmation () { $requireConfirm = ($this->getConfigInstance()->readConfig('email_change_confirmation') == "Y"); return $requireConfirm; } /** * Checks wether the rules has been updated * * @return $rulesUpdated Wether rules has been updated */ public function ifRulesHaveChanged () { /* @TODO Implement check if rules have been changed */ return false; } /** * Checks wether email change is allowed * * @return $emailChange Wether changing email address is allowed */ public function ifEmailChangeAllowed () { $emailChange = ($this->getConfigInstance()->readConfig('email_change_allowed') == "Y"); return $emailChange; } /** * 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 still open? if ($this->formOpened === true) { // Throw an exception throw new FormOpenedException ($this, self::EXCEPTION_OPENED_FORM); } // END - if // Send content to template engine $this->getTemplateInstance()->assignVariable($this->formName, $this->getContent()); } /** * Getter for direct field values * * @param $fieldName Name of the field we shall fetch * @return $fieldValue Value from field */ public function getField ($fieldName) { // Get the field value $fieldValue = call_user_func_array(array($this->valueInstance, "getField"), array($fieldName)); // Return it return $fieldValue; } } // [EOF] ?>