0 follower

CForm

Package	system.web.form
Inheritance	class CForm » CFormElement » CComponent
Implements	ArrayAccess
Since	1.1
Source Code	framework/web/form/CForm.php

CForm represents a form object that contains form input specifications.

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.

Public Properties

Hide inherited properties

Property	Type	Description	Defined By
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

Protected Properties

Hide inherited properties

Property	Type	Description	Defined By
uniqueId	string	Returns a unique ID that identifies this form in the current page.	CForm

Public Methods

Hide inherited methods

Method	Description	Defined By
__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

Protected Methods

Hide inherited methods

Method	Description	Defined By
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

Property Details

action property

public mixed $action;

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.

activeForm property (available since v1.1.1)

public array $activeForm;

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').

activeFormWidget property read-only (available since v1.1.1)

public CActiveForm getActiveFormWidget()

the active form widget associated with this form. This method will return the active form widget as specified by activeForm.

attributes property

public array $attributes;

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.

buttonElementClass property

public string $buttonElementClass;

the name of the class for representing a form button element. Defaults to 'CFormButtonElement'.

buttons property

public CFormElementCollection getButtons()
public void setButtons(array $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.

description property

public string $description;

the description of this form.

elements property

public CFormElementCollection getElements()
public void setElements(array $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.

errorSummaryFooter property

public string|null $errorSummaryFooter;

HTML code to append to the list of errors in the error summary. See CActiveForm::errorSummary().

errorSummaryHeader property

public string|null $errorSummaryHeader;

HTML code to prepend to the list of errors in the error summary. See CActiveForm::errorSummary().

inputElementClass property

public string $inputElementClass;

the name of the class for representing a form input element. Defaults to 'CFormInputElement'.

method property

public string $method;

the submission method of this form. Defaults to 'post'. This property is ignored when this form is a sub-form.

model property

public CModel getModel(boolean $checkParent=true)
public void setModel(CModel $model)

Returns the model that this form is associated with.

models property read-only

public array getModels()

Returns all models that are associated with this form or its sub-forms.

owner property read-only

public CBaseController getOwner()

the owner of this form. This refers to either a controller or a widget by which the form is created and rendered.

root property read-only

public CForm getRoot()

the top-level form object

showErrorSummary property

public boolean $showErrorSummary;

whether to show error summary. Defaults to false.

showErrors property (available since v1.1.14)

public boolean|null $showErrors;

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.

title property

public string $title;

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.

uniqueId property read-only

protected string getUniqueId()

Returns a unique ID that identifies this form in the current page.

Method Details

__construct() method

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.

Source Code: framework/web/form/CForm.php#173 (show)


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.

addedElement() method

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.

Source Code: framework/web/form/CForm.php#560 (show)


public function addedElement($name,$element,$forButtons)
{
}

This method is called after an element is added to the element collection.

clicked() method

public boolean clicked(string $name)
$name	string	the button name
{return}	boolean	whether the button is clicked.

Source Code: framework/web/form/CForm.php#215 (show)


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.

evaluateVisible() method

protected boolean evaluateVisible()
{return}	boolean	whether this form is visible.

Source Code: framework/web/form/CForm.php#581 (show)


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.

getActiveFormWidget() method (available since v1.1.1)

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.

Source Code: framework/web/form/CForm.php#280 (show)


public function getActiveFormWidget()
{
    if($this->_activeForm!==null)
        return $this->_activeForm;
    else
        return $this->getRoot()->_activeForm;
}

getButtons() method

public CFormElementCollection getButtons()
{return}	CFormElementCollection	the form elements.

Source Code: framework/web/form/CForm.php#377 (show)


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.

getElements() method

public CFormElementCollection getElements()
{return}	CFormElementCollection	the form elements.

Source Code: framework/web/form/CForm.php#348 (show)


public function getElements()
{
    if($this->_elements===null)
        $this->_elements=new CFormElementCollection($this,false);
    return $this->_elements;
}

getModel() method

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.

Source Code: framework/web/form/CForm.php#306 (show)


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.

getModels() method

public array getModels()
{return}	array	the models that are associated with this form or its sub-forms.

Source Code: framework/web/form/CForm.php#328 (show)


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.

getOwner() method

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.

Source Code: framework/web/form/CForm.php#292 (show)


public function getOwner()
{
    $owner=$this->getParent();
    while($owner instanceof self)
        $owner=$owner->getParent();
    return $owner;
}

getRoot() method

public CForm getRoot()
{return}	CForm	the top-level form object

Source Code: framework/web/form/CForm.php#267 (show)


public function getRoot()
{
    $root=$this;
    while($root->getParent() instanceof self)
        $root=$root->getParent();
    return $root;
}

getUniqueId() method

protected string getUniqueId()
{return}	string	the unique ID identifying this form

Source Code: framework/web/form/CForm.php#593 (show)


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.

init() method

protected void init()

Source Code: framework/web/form/CForm.php#190 (show)


protected function 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).

loadData() method

public void loadData()

Source Code: framework/web/form/CForm.php#244 (show)


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 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.

Source Code: framework/web/form/CForm.php#571 (show)


public function removedElement($name,$element,$forButtons)
{
}

This method is called after an element is removed from the element collection.

render() method

public string render()
{return}	string	the rendering result

Source Code: framework/web/form/CForm.php#403 (show)


public function render()
{
    return $this->renderBegin() . $this->renderBody() . $this->renderEnd();
}

Renders the form. The default implementation simply calls renderBegin, renderBody and renderEnd.

renderBegin() method

public string renderBegin()
{return}	string	the rendering result

Source Code: framework/web/form/CForm.php#413 (show)


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.

renderBody() method

public string renderBody()
{return}	string	the rendering result

Source Code: framework/web/form/CForm.php#468 (show)


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.

renderButtons() method

public string renderButtons()
{return}	string	the rendering result

Source Code: framework/web/form/CForm.php#513 (show)


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.

renderElement() method

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

Source Code: framework/web/form/CForm.php#527 (show)


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.

renderElements() method

public string renderElements()
{return}	string	the rendering result

Source Code: framework/web/form/CForm.php#501 (show)


public function renderElements()
{
    $output='';
    foreach($this->getElements() as $element)
        $output.=$this->renderElement($element);
    return $output;
}

Renders the elements in this form.

renderEnd() method

public string renderEnd()
{return}	string	the rendering result

Source Code: framework/web/form/CForm.php#446 (show)


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.

setButtons() method

public void setButtons(array $buttons)
$buttons	array	the button configurations

Source Code: framework/web/form/CForm.php#391 (show)


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.

setElements() method

public void setElements(array $elements)
$elements	array	the elements configurations

Source Code: framework/web/form/CForm.php#364 (show)


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.

setModel() method

public void setModel(CModel $model)
$model	CModel	the model to be associated with this form

Source Code: framework/web/form/CForm.php#319 (show)


public function setModel($model)
{
    $this->_model=$model;
}

submitted() method

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.

Source Code: framework/web/form/CForm.php#202 (show)


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 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 void offsetSet(integer $offset, mixed $item)
$offset	integer	the offset to set element
$item	mixed	the element value

public void offsetUnset(mixed $offset)
$offset	mixed	the offset to unset element