CForm
| 包 | system.web.form |
|---|---|
| 继承 | class CForm » CFormElement » CComponent |
| 实现 | ArrayAccess |
| 可用自 | 1.1 |
| 源码 | framework/web/form/CForm.php |
The main purpose of introducing the abstraction of form objects is to enhance the reusability of forms. In particular, we can divide a form in two parts: those that specify each individual form inputs, and those that decorate the form inputs. A CForm object represents the former part. It relies on the rendering process to accomplish form input decoration. Reusability is mainly achieved in the rendering process. That is, a rendering process can be reused to render different CForm objects.
A form can be rendered in different ways. One can call the render method to get a quick form rendering without writing any HTML code; one can also override render to render the form in a different layout; and one can use an external view template to render each form element explicitly. In these ways, the render method can be applied to all kinds of forms and thus achieves maximum reusability; while the external view template keeps maximum flexibility in rendering complex forms.
Form input specifications are organized in terms of a form element hierarchy. At the root of the hierarchy, it is the root CForm object. The root form object maintains its children in two collections: elements and buttons. The former contains non-button form elements (CFormStringElement, CFormInputElement and CForm); while the latter mainly contains button elements (CFormButtonElement). When a CForm object is embedded in the elements collection, it is called a sub-form which can have its own elements and buttons collections and thus form the whole form hierarchy.
Sub-forms are mainly used to handle multiple models. For example, in a user registration form, we can have the root form to collect input for the user table while a sub-form to collect input for the profile table. Sub-form is also a good way to partition a lengthy form into shorter ones, even though all inputs may belong to the same model.
Form input specifications are given in terms of a configuration array which is used to initialize the property values of a CForm object. The elements and buttons properties need special attention as they are the main properties to be configured. To configure elements, we should give it an array like the following:
'elements'=>array(
'username'=>array('type'=>'text', 'maxlength'=>80),
'password'=>array('type'=>'password', 'maxlength'=>80),
)
The above code specifies two input elements: 'username' and 'password'. Note the model
object must have exactly the same attributes 'username' and 'password'. Each element
has a type which specifies what kind of input should be used. The rest of the array elements
(e.g. 'maxlength') in an input specification are rendered as HTML element attributes
when the input field is rendered. The buttons property is configured similarly.
If you're going to use AJAX and/or client form validation with the enabled error summary you have to set $showErrors property to true. Please refer to it's documentation for more details.
For more details about configuring form elements, please refer to CFormInputElement and CFormButtonElement.
公共属性
| 属性 | 类型 | 描述 | 被定义在 |
|---|---|---|---|
| action | mixed | the form action URL (see CHtml::normalizeUrl for details about this parameter. | CForm |
| activeForm | array | the configuration used to create the active form widget. | CForm |
| activeFormWidget | CActiveForm | the active form widget associated with this form. | CForm |
| attributes | array | HTML attribute values for the form tag. | CForm |
| buttonElementClass | string | the name of the class for representing a form button element. | CForm |
| buttons | CFormElementCollection | Returns the button elements of this form. | CForm |
| description | string | the description of this form. | CForm |
| elements | CFormElementCollection | Returns the input elements of this form. | CForm |
| errorSummaryFooter | string|null | HTML code to append to the list of errors in the error summary. | CForm |
| errorSummaryHeader | string|null | HTML code to prepend to the list of errors in the error summary. | CForm |
| inputElementClass | string | the name of the class for representing a form input element. | CForm |
| method | string | the submission method of this form. | CForm |
| model | CModel | Returns the model that this form is associated with. | CForm |
| models | array | Returns all models that are associated with this form or its sub-forms. | CForm |
| owner | CBaseController | the owner of this form. | CForm |
| parent | mixed | the direct parent of this element. | CFormElement |
| root | CForm | the top-level form object | CForm |
| showErrorSummary | boolean | whether to show error summary. | CForm |
| showErrors | boolean|null | whether error elements of the form attributes should be rendered. | CForm |
| title | string | the title for this form. | CForm |
| visible | boolean | Returns a value indicating whether this element is visible and should be rendered. | CFormElement |
受保护的属性
| 属性 | 类型 | 描述 | 被定义在 |
|---|---|---|---|
| uniqueId | string | Returns a unique ID that identifies this form in the current page. | CForm |
公共方法
| 方法 | 描述 | 被定义在 |
|---|---|---|
| __call() | Calls the named method which is not a class method. | CComponent |
| __construct() | Constructor. | CForm |
| __get() | Returns a property value or an attribute value. | CFormElement |
| __isset() | Checks a property value or an attribute value on existence or not null | CFormElement |
| __set() | Sets value of a property or attribute. | CFormElement |
| __toString() | Converts the object to a string. | CFormElement |
| __unset() | Sets a component property to be null. | CComponent |
| addedElement() | This method is called after an element is added to the element collection. | CForm |
| asa() | Returns the named behavior object. | CComponent |
| attachBehavior() | Attaches a behavior to this component. | CComponent |
| attachBehaviors() | Attaches a list of behaviors to the component. | CComponent |
| attachEventHandler() | Attaches an event handler to an event. | CComponent |
| canGetProperty() | Determines whether a property can be read. | CComponent |
| canSetProperty() | Determines whether a property can be set. | CComponent |
| clicked() | Returns a value indicating whether the specified button is clicked. | CForm |
| configure() | Configures this object with property initial values. | CFormElement |
| detachBehavior() | Detaches a behavior from the component. | CComponent |
| detachBehaviors() | Detaches all behaviors from the component. | CComponent |
| detachEventHandler() | Detaches an existing event handler. | CComponent |
| disableBehavior() | Disables an attached behavior. | CComponent |
| disableBehaviors() | Disables all behaviors attached to this component. | CComponent |
| enableBehavior() | Enables an attached behavior. | CComponent |
| enableBehaviors() | Enables all behaviors attached to this component. | CComponent |
| evaluateExpression() | Evaluates a PHP expression or callback under the context of this component. | CComponent |
| getActiveFormWidget() | Returns the active form widget associated with this form. This method will return the active form widget as specified by activeForm. | CForm |
| getButtons() | Returns the button elements of this form. | CForm |
| getElements() | Returns the input elements of this form. | CForm |
| getEventHandlers() | Returns the list of attached event handlers for an event. | CComponent |
| getModel() | Returns the model that this form is associated with. | CForm |
| getModels() | Returns all models that are associated with this form or its sub-forms. | CForm |
| getOwner() | Returns the owner of this form. This refers to either a controller or a widget by which the form is created and rendered. | CForm |
| getParent() | Returns the direct parent of this element. This could be either a CForm object or a CBaseController object (a controller or a widget). | CFormElement |
| getRoot() | Returns the top-level form object | CForm |
| getVisible() | Returns a value indicating whether this element is visible and should be rendered. | CFormElement |
| hasEvent() | Determines whether an event is defined. | CComponent |
| hasEventHandler() | Checks whether the named event has attached handlers. | CComponent |
| hasProperty() | Determines whether a property is defined. | CComponent |
| loadData() | Loads the submitted data into the associated model(s) to the form. | CForm |
| offsetExists() | Returns whether there is an element at the specified offset. | CForm |
| offsetGet() | Returns the element at the specified offset. | CForm |
| offsetSet() | Sets the element at the specified offset. | CForm |
| offsetUnset() | Unsets the element at the specified offset. | CForm |
| raiseEvent() | Raises an event. | CComponent |
| removedElement() | This method is called after an element is removed from the element collection. | CForm |
| render() | Renders the form. | CForm |
| renderBegin() | Renders the open tag of the form. | CForm |
| renderBody() | Renders the body content of this form. | CForm |
| renderButtons() | Renders the buttons in this form. | CForm |
| renderElement() | Renders a single element which could be an input element, a sub-form, a string, or a button. | CForm |
| renderElements() | Renders the elements in this form. | CForm |
| renderEnd() | Renders the close tag of the form. | CForm |
| setButtons() | Configures the buttons of this form. | CForm |
| setElements() | Configures the input elements of this form. | CForm |
| setModel() | Sets the model to be associated with this form | CForm |
| setVisible() | Sets whether this element is visible and should be rendered. | CFormElement |
| submitted() | Returns a value indicating whether this form is submitted. | CForm |
| validate() | Validates the models associated with this form. | CForm |
受保护的方法
| 方法 | 描述 | 被定义在 |
|---|---|---|
| evaluateVisible() | Evaluates the visibility of this form. | CForm |
| getUniqueId() | Returns a unique ID that identifies this form in the current page. | CForm |
| init() | Initializes this form. | CForm |
属性详情
the form action URL (see CHtml::normalizeUrl for details about this parameter.) Defaults to an empty string, meaning the current request URL. This property is ignored when this form is a sub-form.
the configuration used to create the active form widget. The widget will be used to render the form tag and the error messages. The 'class' option is required, which specifies the class of the widget. The rest of the options will be passed to CBaseController::beginWidget() call. Defaults to array('class'=>'CActiveForm').
the active form widget associated with this form. This method will return the active form widget as specified by activeForm.
HTML attribute values for the form tag. When the form is embedded within another form, this property will be used to render the HTML attribute values for the fieldset enclosing the child form.
the name of the class for representing a form button element. Defaults to 'CFormButtonElement'.
Returns the button elements of this form. Note that the returned result is a CFormElementCollection object, which means you can use it like an array. For more details, see CMap.
the description of this form.
Returns the input elements of this form. This includes text strings, input elements and sub-forms. Note that the returned result is a CFormElementCollection object, which means you can use it like an array. For more details, see CMap.
HTML code to append to the list of errors in the error summary. See CActiveForm::errorSummary().
HTML code to prepend to the list of errors in the error summary. See CActiveForm::errorSummary().
the name of the class for representing a form input element. Defaults to 'CFormInputElement'.
the submission method of this form. Defaults to 'post'. This property is ignored when this form is a sub-form.
Returns the model that this form is associated with.
Returns all models that are associated with this form or its sub-forms.
the owner of this form. This refers to either a controller or a widget by which the form is created and rendered.
the top-level form object
whether to show error summary. Defaults to false.
whether error elements of the form attributes should be rendered. There are three possible
valid values: null, true and false.
Defaults to null meaning that $showErrorSummary will be used as value. This is done mainly to keep
backward compatibility with existing applications. If you want to use error summary with AJAX and/or client
validation you have to set this property to true (recall that CActiveForm::error() should be called
for each attribute that is going to be AJAX and/or client validated).
False value means that the error elements of the form attributes shall not be displayed. True value means that
the error elements of the form attributes will be rendered.
the title for this form. By default, if this is set, a fieldset may be rendered around the form body using the title as its legend. Defaults to null.
Returns a unique ID that identifies this form in the current page.
方法详情
|
public void __construct(mixed $config, CModel $model=NULL, mixed $parent=NULL)
| ||
| $config | mixed | the configuration for this form. It can be a configuration array or the path alias of a PHP script file that returns a configuration array. The configuration array consists of name-value pairs that are used to initialize the properties of this form. |
| $model | CModel | the model object associated with this form. If it is null, the parent's model will be used instead. |
| $parent | mixed | the direct parent of this form. This could be either a CBaseController object (a controller or a widget), or a CForm object. If the former, it means the form is a top-level form; if the latter, it means this form is a sub-form. |
public function __construct($config,$model=null,$parent=null)
{
$this->setModel($model);
if($parent===null)
$parent=Yii::app()->getController();
parent::__construct($config,$parent);
if($this->showErrors===null)
$this->showErrors=!$this->showErrorSummary;
$this->init();
}
Constructor. If you override this method, make sure you do not modify the method signature, and also make sure you call the parent implementation.
|
public void addedElement(string $name, CFormElement $element, boolean $forButtons)
| ||
| $name | string | the name of the element |
| $element | CFormElement | the element that is added |
| $forButtons | boolean | whether the element is added to the buttons collection. If false, it means the element is added to the elements collection. |
public function addedElement($name,$element,$forButtons)
{
}
This method is called after an element is added to the element collection.
|
public boolean clicked(string $name)
| ||
| $name | string | the button name |
| {return} | boolean | whether the button is clicked. |
public function clicked($name)
{
if(strcasecmp($this->getRoot()->method,'get'))
return isset($_POST[$name]);
else
return isset($_GET[$name]);
}
Returns a value indicating whether the specified button is clicked.
|
protected boolean evaluateVisible()
| ||
| {return} | boolean | whether this form is visible. |
protected function evaluateVisible()
{
foreach($this->getElements() as $element)
if($element->getVisible())
return true;
return false;
}
Evaluates the visibility of this form. This method will check the visibility of the elements. If any one of them is visible, the form is considered as visible. Otherwise, it is invisible.
|
public CActiveForm getActiveFormWidget()
| ||
| {return} | CActiveForm | the active form widget associated with this form. This method will return the active form widget as specified by activeForm. |
public function getActiveFormWidget()
{
if($this->_activeForm!==null)
return $this->_activeForm;
else
return $this->getRoot()->_activeForm;
}
|
public CFormElementCollection getButtons()
| ||
| {return} | CFormElementCollection | the form elements. |
public function getButtons()
{
if($this->_buttons===null)
$this->_buttons=new CFormElementCollection($this,true);
return $this->_buttons;
}
Returns the button elements of this form. Note that the returned result is a CFormElementCollection object, which means you can use it like an array. For more details, see CMap.
|
public CFormElementCollection getElements()
| ||
| {return} | CFormElementCollection | the form elements. |
public function getElements()
{
if($this->_elements===null)
$this->_elements=new CFormElementCollection($this,false);
return $this->_elements;
}
Returns the input elements of this form. This includes text strings, input elements and sub-forms. Note that the returned result is a CFormElementCollection object, which means you can use it like an array. For more details, see CMap.
|
public CModel getModel(boolean $checkParent=true)
| ||
| $checkParent | boolean | whether to return parent's model if this form doesn't have model by itself. |
| {return} | CModel | the model associated with this form. If this form does not have a model, it will look for a model in its ancestors. |
public function getModel($checkParent=true)
{
if(!$checkParent)
return $this->_model;
$form=$this;
while($form->_model===null && $form->getParent() instanceof self)
$form=$form->getParent();
return $form->_model;
}
Returns the model that this form is associated with.
|
public array getModels()
| ||
| {return} | array | the models that are associated with this form or its sub-forms. |
public function getModels()
{
$models=array();
if($this->_model!==null)
$models[]=$this->_model;
foreach($this->getElements() as $element)
{
if($element instanceof self)
$models=array_merge($models,$element->getModels());
}
return $models;
}
Returns all models that are associated with this form or its sub-forms.
|
public CBaseController getOwner()
| ||
| {return} | CBaseController | the owner of this form. This refers to either a controller or a widget by which the form is created and rendered. |
public function getOwner()
{
$owner=$this->getParent();
while($owner instanceof self)
$owner=$owner->getParent();
return $owner;
}
|
public CForm getRoot()
| ||
| {return} | CForm | the top-level form object |
public function getRoot()
{
$root=$this;
while($root->getParent() instanceof self)
$root=$root->getParent();
return $root;
}
|
protected string getUniqueId()
| ||
| {return} | string | the unique ID identifying this form |
protected function getUniqueId()
{
if(isset($this->attributes['id']))
return 'yform_'.$this->attributes['id'];
else
return 'yform_'.sprintf('%x',crc32(serialize(array_keys($this->getElements()->toArray()))));
}
Returns a unique ID that identifies this form in the current page.
|
protected void init()
|
Initializes this form. This method is invoked at the end of the constructor. You may override this method to provide customized initialization (such as configuring the form object).
|
public void loadData()
|
public function loadData()
{
if($this->_model!==null)
{
$class=CHtml::modelName($this->_model);
if(strcasecmp($this->getRoot()->method,'get'))
{
if(isset($_POST[$class]))
$this->_model->setAttributes($_POST[$class]);
}
elseif(isset($_GET[$class]))
$this->_model->setAttributes($_GET[$class]);
}
foreach($this->getElements() as $element)
{
if($element instanceof self)
$element->loadData();
}
}
Loads the submitted data into the associated model(s) to the form. This method will go through all models associated with this form and its sub-forms and massively assign the submitted data to the models.
参见
|
public boolean offsetExists(mixed $offset)
| ||
| $offset | mixed | the offset to check on |
| {return} | boolean | |
public function offsetExists($offset)
{
return $this->getElements()->contains($offset);
}
Returns whether there is an element at the specified offset. This method is required by the interface ArrayAccess.
|
public mixed offsetGet(integer $offset)
| ||
| $offset | integer | the offset to retrieve element. |
| {return} | mixed | the element at the offset, null if no element is found at the offset |
public function offsetGet($offset)
{
return $this->getElements()->itemAt($offset);
}
Returns the element at the specified offset. This method is required by the interface ArrayAccess.
|
public void offsetSet(integer $offset, mixed $item)
| ||
| $offset | integer | the offset to set element |
| $item | mixed | the element value |
public function offsetSet($offset,$item)
{
$this->getElements()->add($offset,$item);
}
Sets the element at the specified offset. This method is required by the interface ArrayAccess.
|
public void offsetUnset(mixed $offset)
| ||
| $offset | mixed | the offset to unset element |
public function offsetUnset($offset)
{
$this->getElements()->remove($offset);
}
Unsets the element at the specified offset. This method is required by the interface ArrayAccess.
|
public void removedElement(string $name, CFormElement $element, boolean $forButtons)
| ||
| $name | string | the name of the element |
| $element | CFormElement | the element that is removed |
| $forButtons | boolean | whether the element is removed from the buttons collection If false, it means the element is removed from the elements collection. |
public function removedElement($name,$element,$forButtons)
{
}
This method is called after an element is removed from the element collection.
|
public string render()
| ||
| {return} | string | the rendering result |
public function render()
{
return $this->renderBegin() . $this->renderBody() . $this->renderEnd();
}
Renders the form. The default implementation simply calls renderBegin, renderBody and renderEnd.
|
public string renderBegin()
| ||
| {return} | string | the rendering result |
public function renderBegin()
{
if($this->getParent() instanceof self)
return '';
else
{
$options=$this->activeForm;
if(isset($options['class']))
{
$class=$options['class'];
unset($options['class']);
}
else
$class='CActiveForm';
$options['action']=$this->action;
$options['method']=$this->method;
if(isset($options['htmlOptions']))
{
foreach($this->attributes as $name=>$value)
$options['htmlOptions'][$name]=$value;
}
else
$options['htmlOptions']=$this->attributes;
ob_start();
$this->_activeForm=$this->getOwner()->beginWidget($class, $options);
return ob_get_clean() . "<div style=\"display:none\">".CHtml::hiddenField($this->getUniqueID(),1)."</div>\n";
}
}
Renders the open tag of the form. The default implementation will render the open form tag.
|
public string renderBody()
| ||
| {return} | string | the rendering result |
public function renderBody()
{
$output='';
if($this->title!==null)
{
if($this->getParent() instanceof self)
{
$attributes=$this->attributes;
unset($attributes['name'],$attributes['type']);
$output=CHtml::openTag('fieldset', $attributes)."<legend>".$this->title."</legend>\n";
}
else
$output="<fieldset>\n<legend>".$this->title."</legend>\n";
}
if($this->description!==null)
$output.="<div class=\"description\">\n".$this->description."</div>\n";
if($this->showErrorSummary && ($model=$this->getModel(false))!==null)
$output.=$this->getActiveFormWidget()->errorSummary($model,$this->errorSummaryHeader,$this->errorSummaryFooter)."\n";
$output.=$this->renderElements()."\n".$this->renderButtons()."\n";
if($this->title!==null)
$output.="</fieldset>\n";
return $output;
}
Renders the body content of this form. This method mainly renders elements and buttons. If title or description is specified, they will be rendered as well. And if the associated model contains error, the error summary may also be displayed. The form tag will not be rendered. Please call renderBegin and renderEnd to render the open and close tags of the form. You may override this method to customize the rendering of the form.
|
public string renderButtons()
| ||
| {return} | string | the rendering result |
public function renderButtons()
{
$output='';
foreach($this->getButtons() as $button)
$output.=$this->renderElement($button);
return $output!=='' ? "<div class=\"row buttons\">".$output."</div>\n" : '';
}
Renders the buttons in this form.
|
public string renderElement(mixed $element)
| ||
| $element | mixed | the form element to be rendered. This can be either a CFormElement instance or a string representing the name of the form element. |
| {return} | string | the rendering result |
public function renderElement($element)
{
if(is_string($element))
{
if(($e=$this[$element])===null && ($e=$this->getButtons()->itemAt($element))===null)
return $element;
else
$element=$e;
}
if($element->getVisible())
{
if($element instanceof CFormInputElement)
{
if($element->type==='hidden')
return "<div style=\"display:none\">\n".$element->render()."</div>\n";
else
return "<div class=\"row field_{$element->name}\">\n".$element->render()."</div>\n";
}
elseif($element instanceof CFormButtonElement)
return $element->render()."\n";
else
return $element->render();
}
return '';
}
Renders a single element which could be an input element, a sub-form, a string, or a button.
|
public string renderElements()
| ||
| {return} | string | the rendering result |
public function renderElements()
{
$output='';
foreach($this->getElements() as $element)
$output.=$this->renderElement($element);
return $output;
}
Renders the elements in this form.
|
public string renderEnd()
| ||
| {return} | string | the rendering result |
public function renderEnd()
{
if($this->getParent() instanceof self)
return '';
else
{
ob_start();
$this->getOwner()->endWidget();
return ob_get_clean();
}
}
Renders the close tag of the form.
|
public void setButtons(array $buttons)
| ||
| $buttons | array | the button configurations |
public function setButtons($buttons)
{
$collection=$this->getButtons();
foreach($buttons as $name=>$config)
$collection->add($name,$config);
}
Configures the buttons of this form. The configuration must be an array of button configuration array indexed by button name. Each button configuration array consists of name-value pairs that are used to initialize a CFormButtonElement object.
|
public void setElements(array $elements)
| ||
| $elements | array | the elements configurations |
public function setElements($elements)
{
$collection=$this->getElements();
foreach($elements as $name=>$config)
$collection->add($name,$config);
}
Configures the input elements of this form. The configuration must be an array of input configuration array indexed by input name. Each input configuration array consists of name-value pairs that are used to initialize a CFormStringElement object (when 'type' is 'string'), a CFormElement object (when 'type' is a string ending with 'Form'), or a CFormInputElement object in all other cases.
|
public void setModel(CModel $model)
| ||
| $model | CModel | the model to be associated with this form |
|
public boolean submitted(string $buttonName='submit', boolean $loadData=true)
| ||
| $buttonName | string | the name of the submit button |
| $loadData | boolean | whether to call loadData if the form is submitted so that the submitted data can be populated to the associated models. |
| {return} | boolean | whether this form is submitted. |
public function submitted($buttonName='submit',$loadData=true)
{
$ret=$this->clicked($this->getUniqueId()) && $this->clicked($buttonName);
if($ret && $loadData)
$this->loadData();
return $ret;
}
Returns a value indicating whether this form is submitted.
参见
|
public boolean validate()
| ||
| {return} | boolean | whether all models are valid |
public function validate()
{
$ret=true;
foreach($this->getModels() as $model)
$ret=$model->validate() && $ret;
return $ret;
}
Validates the models associated with this form. All models, including those associated with sub-forms, will perform the validation. You may use CModel::getErrors() to retrieve the validation error messages.