File Source for form.class.php

<?php
// *** Tangra (Application Framework and Tools for PHP)
// $Id$
//
/**
* Contains class Form
*
* @package tangra_lib
* @subpackage form
*/
/**
* Needed for Tangra_Form_Submit_Method::POST and Tangra_Form_Submit_Method::GET
*/
require_once(TANGRA_MAIN_DIR.'core/tangra_form_submit_method.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'form/fields/form_field.class.php');
/**
* Needed for automatic change of form encoding to Form::ENCODING_MULTIPART
*/
require_once(TANGRA_MAIN_DIR.'form/fields/file/form_field_file.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'web_site/web_event_simple.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'exceptions/te_form_field_already_exists.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'exceptions/te_form_field_not_exists.class.php');
/**
* Class Form is used to handle most of the aspects when working with HTML forms
*
* @package tangra_lib
* @subpackage form
*/
class Form extends Tangra_Class {
/**
* Enter description here...
*
*/
const ENCODING_APPLICATION = 'application/x-www-form-urlencoded';
const ENCODING_MULTIPART = 'multipart/form-data';
/**
* Name of the form
*
* @var string
* @internal
*
*/
private $name;
/**
* Method of sending the form Tangra_Form_Submit_Method::POST/Tangra_Form_Submit_Method::GET
*
* @var integer
* @internal
*/
private $method;
/**
* Encoding Form::ENCODING_APPLICATION / Form::ENCODING_MULTIPART
*
* @var unknown_type
* @internal
*/
private $enctype;
/**
* Action - page for action attribute
*
* @var string
* @internal
*/
private $action;
/**
* Fields of the form
*
* @var array
* @internal
*/
protected $fields;
/**
* Status of the submission of the form
*
* @var boolean
* @internal
*/
private $form_ok;
/**
* Constructor
*
* @param string $name Name of the form
* @param string $action Action page
* @param integer $method Tangra_Form_Submit_Method::POST or Tangra_Form_Submit_Method::GET
* @param integer $enctype Form::ENCODING_APPLICATION or Form::ENCODING_MULTIPART
*/
function __construct($name, $action, $method = Tangra_Form_Submit_Method::POST, $enctype = Form::ENCODING_APPLICATION) {
$this->name = $name;
$this->action = $action;
$this->method = $method;
$this->enctype = $enctype;
$this->fields = array();
}
/**
* Gets form name
*
* @return string
*/
public function get_name() {
return $this->name;
}
/**
* Gets method of form submission.
*
* Returned value will Tangra_Form_Submit_Method::POST or Tangra_Form_Submit_Method::GET
*
* @return integer
*/
public function get_method() {
return $this->method;
}
/**
* Gets encoding type
*
* @return unknown
*/
public function get_enctype() {
return $this->enctype;
}
/**
* Gets action property of the form
*
* @return string
*/
public function get_action() {
return $this->action;
}
/**
* Adds field to the form
*
* Please note that if the field is Form_Field_File type, encoding of the form will be automatically changed to Form::ENCODING_MULTIPART (that way form will be submited correctly)
*
* @param Form_Field $field
* @throws TE_Form_Field_Already_Exists
*/
public function add_field(Form_Field $field) {
if (!array_key_exists($field->get_name(), $this->fields)) {
$this->fields[$field->get_name()] = $field;
if ($field instanceof Form_Field_File) {
$this->set_enctype(Form::ENCODING_MULTIPART);
}
} else {
throw new TE_Form_Field_Already_Exists($field->get_name());
}
}
/**
* Sets value of form fiels
*
* @param string $field_name Name of the field
* @param mixed $value Value of the field
* @throws TE_Form_Field_Not_Exists
*/
public function set_field_value($field_name, $value) {
if (array_key_exists($field_name, $this->fields)) {
$this->fields[$field_name]->set_value($value);
} else {
throw new TE_Form_Field_Not_Exists($field_name);
}
}
/**
* Gets Field value
*
* @param string $field_name Name of the field
* @return mixed
* @throws TE_Form_Field_Not_Exists
*/
public function get_field_value($field_name) {
if (array_key_exists($field_name, $this->fields)) {
$ret = $this->fields[$field_name]->get_value();
} else {
throw new TE_Form_Field_Not_Exists($field_name);
}
return $ret;
}
/**
* Gets field HTML value
*
* HTML value is value of the field as sent by HTTP POST/GET.
* It is not intended to be called directly by the user except in vary rare and specific circumstances.
*
* @param unknown_type $field_name
* @return unknown
* @throws TE_Form_Field_Not_Exists
* @internal
*/
public function get_field_html_value($field_name) {
if (array_key_exists($field_name, $this->fields)) {
$ret = $this->fields[$field_name]->get_html_value();
} else {
throw new TE_Form_Field_Not_Exists($field_name);
}
return $ret;
}
/**
* Returns array containing all fields.
*
* @return array
* @internal
*/
public function &get_fields() {
return $this->fields;
}
/**
* Returns field specified by $field_name
*
* @param string $field_name name of the field
* @return Form_Field
* @throws TE_Form_Field_Not_Exists
*/
public function &get_field($field_name) {
if (array_key_exists($field_name, $this->fields)) {
$ret = &$this->fields[$field_name];
} else {
throw new TE_Form_Field_Not_Exists($field_name);
}
return $ret;
}
/**
* Translates HTML values of the fields to "application" values.
* @internal
*
*/
public function translate_values_html2app() {
foreach ($this->fields as $key => $value) {
$this->fields[$key]->translate_value_html2app();
}
}
/**
* Performs value check on all fields
*
* Cycles all fields and call theirs basic_check method
*
* @return boolean
* @internal
*/
public function basic_check() {
$status = false;
reset($this->fields);
foreach ($this->fields as $key => $val) {
$status |= $this->fields[$key]->basic_check();
}
if ($status == false) {
$this->form_ok = true;
} else {
$this->form_ok = false;
}
return $this->form_ok;
}
/**
* Returns status of the form
*
* Status of the form is the state of the last submission. If all fields are OK then status is true, otherwise - false
*
* @return unknown
*/
public function is_form_ok() {
return $this->form_ok;
}
/**
* Returns name of the submit button
*
* Name of the submit button contains form name and "_submit" suffix
*
* @return string
* @internal
*/
public function get_submit_name() {
return $this->get_name().'_submit';
}
/**
* Returns name of the submit button with "_x" suffix
*
* When submit button is image, browsers return submit name plus _x and _y suffixes (position of the click in the image)
*
* @return string
* @internal
*/
public function get_submit_x_name() {
return $this->get_name().'_submit_x';
}
/**
* Returns name of the submit button with "_y" suffix
*
* When submit button is image, browsers return submit name plus _x and _y suffixes (position of the click in the image)
*
* @return string
* @internal
*/
public function get_submit_y_name() {
return $this->get_name().'_submit_y';
}
/**
* Transfers values from $_POST or $_GET into html_value ofd each field
*
* @param Context $context
* @internal
*/
public function capture_submit(Context $context) {
if ($this->method == Tangra_Form_Submit_Method::POST) {
$submit_array = $context->get_var('POST');
} else {
if ($this->method == Tangra_Form_Submit_Method::GET) {
$submit_array = $context->get_var('GET');
}
}
$submit_array = array_merge($submit_array, array('_FILES' => $_FILES));
foreach ($this->fields as $field) {
$field->capture_submit($this->get_name(), $submit_array);
}
}
/**
* Cycles all fields and calls their accept_submit method
*
* @internal
*/
public function accept_submit() {
foreach ($this->fields as &$field) {
$field->accept_submit();
}
}
/**
* Checks if form is receiving submit, i.e. submit_name is present in $_POST or $_GET
*
* @param Context $context
* @return boolean
* @internal
*/
public function is_receiving_submit(Context $context) {
$ret = false;
if ($this->get_method() == Tangra_Form_Submit_Method::POST) {
$var_func = 'exists_in_post';
} else {
$var_func = 'exists_in_get';
}
//first listening for normal submit button capture
if ($context->$var_func($this->get_submit_name(), $context)) {
$ret = true;
} else {
//second: for image submit button capture
if ($context->$var_func($this->get_submit_x_name(), $context)) {
$ret = true;
}
}
return $ret;
}
/**
* Sets field error.
*
* Each form field may have potential errors. Most of them are built-in,
* for example - 'mandatory_missing" which means that field is mandatory, but POST/GET
* does not contain value for it.
* Each field may have custom errors that are not set during basic_check. In this
* case, if error condition is true, application have to call set_field_error to tell the
* field that it is in error.
*
* @param string $field_name Name of the field
* @param string $potential_error_name Name of the error
* @see Form_Field
*/
public function set_field_error($field_name, $potential_error_name) {
if (array_key_exists($field_name, $this->fields)) {
$this->fields[$field_name]->set_error($potential_error_name);
} else {
throw new TE_Form_Field_Not_Exists($field_name);
}
}
/**
* Returns field erros (if any)
*
* @param string $field_name Name of the field
* @return array
*/
public function get_field_errors($field_name) {
if (array_key_exists($field_name, $this->fields)) {
$ret = $this->fields[$field_name]->get_errors();
} else {
throw new TE_Form_Field_Not_Exists($field_name);
}
return $ret;
}
/**
* Returns event of form submission
*
* @return Web_Event_Simple
*/
public function get_submit_event() {
$ret = $this->create_submit_event($this->get_submit_name());
return $ret;
}
/**
* Returns events of form submission both for <input type="submit" and <input type="image"
*
* @return arrray Simple array of Web_Event_Simple elements
*/
public function get_submit_events() {
$ret[] = $this->get_submit_event();
$ret[] = $this->create_submit_event($this->get_submit_x_name());
return $ret;
}
/**
* Creates submit event with capture specified by $submit_name
*
* @param string $submit_name
* @return Web_Event_Simple
*/
private function create_submit_event($submit_name) {
switch ($this->get_method()) {
case Tangra_Form_Submit_Method::POST:
$type = Tangra_Parameter_Method::POST;
break;
case Tangra_Form_Submit_Method::GET:
$type = Tangra_Parameter_Method::GET;
break;
}
$ret = new Web_Event_Simple($submit_name, $type, $submit_name);
return $ret;
}
/**
* Sets the name of the form
*
* Name of the form must be alphanumeric (underscore is allowed), starting with letter, 50 characters max.
* Please note that $name will be converted to lowercase.
*
* @param string $name
* @throws Tangra_Exception
* @internal
*/
protected function set_name($name) {
if (ereg("^[a-z]{1}[a-z0-9_]{1,50}$", $name)) {
$this->name = strtolower($name);
} else {
throw new Tangra_Exception('Invalid form name. Must be alphanumeric (underscore allowed), starting with letter, 50 characters max.');
}
}
/**
* Sets the method of submission
*
* Must be either Tangra_Form_Submit_Method::POST or Tangra_Form_Submit_Method::GET
*
* @param integer $method
* @throws Tangra_Exception
* @internal
*/
protected function set_method($method) {
switch ($method) {
case Tangra_Form_Submit_Method::POST:
case Tangra_Form_Submit_Method::GET:
$this->method = $method;
break;
default:
throw new Tangra_Exception('Invalid form method.');
break;
}
}
/**
* Sets encoding type.
*
* Must be either Form::ENCODING_APPLICATION or Form::ENCODING_MULTIPART
*
* @param integer $enctype
* @throws Tangra_Exception
* @internal
*/
protected function set_enctype($enctype) {
switch ($enctype) {
case Form::ENCODING_APPLICATION:
case Form::ENCODING_MULTIPART:
$this->enctype = $enctype;
break;
default:
throw new Tangra_Exception('Invalid encoding type. Must be either Form::ENCODING_APPLICATION or Form::ENCODING_MULTIPART');
break;
}
}
}

Source for file form.class.php