Class CForm

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 CForm::render() method to get a quick form rendering without writing any HTML code; one can also override CForm::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 CForm::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 CForm::$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.

CComponent

CFormElement

CForm implements ArrayAccess

Package: system\web\form
Copyright: 2008-2013 Yii Software LLC
License: http://www.yiiframework.com/license/
Author: Qiang Xue <qiang.xue@gmail.com>
Since: 1.1
Located at x2engine/framework/web/form/CForm.php

Methods summary
`public`	# `__construct( mixed $config, CModel $model = null, mixed $parent = null )` Constructor. If you override this method, make sure you do not modify the method signature, and also make sure you call the parent implementation. Constructor. If you override this method, make sure you do not modify the method signature, and also make sure you call the parent implementation. Parameters `$config` `mixed` $config 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` $model the model object associated with this form. If it is null, the parent's model will be used instead. `$parent` `mixed` $parent 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. Overrides `CFormElement::__construct()`
`protected`	# `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). 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 boolean`	# `submitted( string $buttonName = 'submit', boolean $loadData = true )` Returns a value indicating whether this form is submitted. Returns a value indicating whether this form is submitted. Parameters `$buttonName` `string` $buttonName the name of the submit button `$loadData` `boolean` $loadData whether to call `CForm::loadData()` if the form is submitted so that the submitted data can be populated to the associated models. Returns `boolean` whether this form is submitted. See `CForm::loadData()`
`public boolean`	# `clicked( string $name )` Returns a value indicating whether the specified button is clicked. Returns a value indicating whether the specified button is clicked. Parameters `$name` `string` $name the button name Returns `boolean` whether the button is clicked.
`public boolean`	# `validate( )` 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. 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. Returns `boolean` whether all models are valid
`public`	# `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. 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. See `CForm::submitted()`
`public CForm`	# `getRoot( )` Returns `CForm` the top-level form object
`public CActiveForm`	# `getActiveFormWidget( )` Returns `CActiveForm` the active form widget associated with this form. This method will return the active form widget as specified by `CForm::$activeForm`. Since 1.1.1
`public CBaseController`	# `getOwner( )` Returns `CBaseController` the owner of this form. This refers to either a controller or a widget by which the form is created and rendered.
`public CModel`	# `getModel( boolean $checkParent = true )` Returns the model that this form is associated with. Returns the model that this form is associated with. Parameters `$checkParent` `boolean` $checkParent whether to return parent's model if this form doesn't have model by itself. Returns `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`	# `setModel( CModel $model )` Parameters `$model` `CModel` $model the model to be associated with this form
`public array`	# `getModels( )` Returns all models that are associated with this form or its sub-forms. Returns all models that are associated with this form or its sub-forms. Returns `array` the models that are associated with this form or its sub-forms.
`public CFormElementCollection`	# `getElements( )` 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`. 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`. Returns `CFormElementCollection` the form elements.
`public`	# `setElements( array $elements )` 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. 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. Parameters `$elements` `array` $elements the elements configurations
`public CFormElementCollection`	# `getButtons( )` 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`. 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`. Returns `CFormElementCollection` the form elements.
`public`	# `setButtons( array $buttons )` 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. 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. Parameters `$buttons` `array` $buttons the button configurations
`public string`	# `render( )` Renders the form. The default implementation simply calls `CForm::renderBegin()`, `CForm::renderBody()` and `CForm::renderEnd()`. Renders the form. The default implementation simply calls `CForm::renderBegin()`, `CForm::renderBody()` and `CForm::renderEnd()`. Returns `string` the rendering result
`public string`	# `renderBegin( )` Renders the open tag of the form. The default implementation will render the open form tag. Renders the open tag of the form. The default implementation will render the open form tag. Returns `string` the rendering result
`public string`	# `renderEnd( )` Renders the close tag of the form. Renders the close tag of the form. Returns `string` the rendering result
`public string`	# `renderBody( )` Renders the body content of this form. This method mainly renders elements and buttons. If `CForm::$title` or `CForm::$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 `CForm::renderBegin()` and `CForm::renderEnd()` to render the open and close tags of the form. You may override this method to customize the rendering of the form. Renders the body content of this form. This method mainly renders elements and buttons. If `CForm::$title` or `CForm::$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 `CForm::renderBegin()` and `CForm::renderEnd()` to render the open and close tags of the form. You may override this method to customize the rendering of the form. Returns `string` the rendering result
`public string`	# `renderElements( )` Renders the elements in this form. Renders the elements in this form. Returns `string` the rendering result
`public string`	# `renderButtons( )` Renders the buttons in this form. Renders the buttons in this form. Returns `string` the rendering result
`public string`	# `renderElement( mixed $element )` Renders a single element which could be an input element, a sub-form, a string, or a button. Renders a single element which could be an input element, a sub-form, a string, or a button. Parameters `$element` `mixed` $element the form element to be rendered. This can be either a `CFormElement` instance or a string representing the name of the form element. Returns `string` the rendering result
`public`	# `addedElement( string $name, CFormElement $element, boolean $forButtons )` This method is called after an element is added to the element collection. This method is called after an element is added to the element collection. Parameters `$name` `string` $name the name of the element `$element` `CFormElement` $element the element that is added `$forButtons` `boolean` $forButtons whether the element is added to the buttons collection. If false, it means the element is added to the elements collection.
`public`	# `removedElement( string $name, CFormElement $element, boolean $forButtons )` This method is called after an element is removed from the element collection. This method is called after an element is removed from the element collection. Parameters `$name` `string` $name the name of the element `$element` `CFormElement` $element the element that is removed `$forButtons` `boolean` $forButtons whether the element is removed from the buttons collection If false, it means the element is removed from the elements collection.
`protected boolean`	# `evaluateVisible( )` 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. 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. Returns `boolean` whether this form is visible. Overrides `CFormElement::evaluateVisible()`
`protected string`	# `getUniqueId( )` Returns a unique ID that identifies this form in the current page. Returns a unique ID that identifies this form in the current page. Returns `string` the unique ID identifying this form
`public boolean`	# `offsetExists( mixed $offset )` Returns whether there is an element at the specified offset. This method is required by the interface ArrayAccess. Returns whether there is an element at the specified offset. This method is required by the interface ArrayAccess. Parameters `$offset` `mixed` $offset the offset to check on Returns `boolean` Implementation of `ArrayAccess::offsetExists()`
`public mixed`	# `offsetGet( integer $offset )` Returns the element at the specified offset. This method is required by the interface ArrayAccess. Returns the element at the specified offset. This method is required by the interface ArrayAccess. Parameters `$offset` `integer` $offset the offset to retrieve element. Returns `mixed` the element at the offset, null if no element is found at the offset Implementation of `ArrayAccess::offsetGet()`
`public`	# `offsetSet( integer $offset, mixed $item )` Sets the element at the specified offset. This method is required by the interface ArrayAccess. Sets the element at the specified offset. This method is required by the interface ArrayAccess. Parameters `$offset` `integer` $offset the offset to set element `$item` `mixed` $item the element value Implementation of `ArrayAccess::offsetSet()`
`public`	# `offsetUnset( mixed $offset )` Unsets the element at the specified offset. This method is required by the interface ArrayAccess. Unsets the element at the specified offset. This method is required by the interface ArrayAccess. Parameters `$offset` `mixed` $offset the offset to unset element Implementation of `ArrayAccess::offsetUnset()`

Methods inherited from CFormElement
`__get(), __isset(), __set(), __toString(), configure(), getParent(), getVisible(), setVisible()`

Methods inherited from CComponent
`__call(), __unset(), asa(), attachBehavior(), attachBehaviors(), attachEventHandler(), canGetProperty(), canSetProperty(), detachBehavior(), detachBehaviors(), detachEventHandler(), disableBehavior(), disableBehaviors(), enableBehavior(), enableBehaviors(), evaluateExpression(), getEventHandlers(), hasEvent(), hasEventHandler(), hasProperty(), raiseEvent()`

Properties summary
`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. 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.
`public string`	`$description`		# the description of this form. the description of this form.
`public string`	`$method`	`'post'`	# the submission method of this form. Defaults to 'post'. This property is ignored when this form is a sub-form. the submission method of this form. Defaults to 'post'. This property is ignored when this form is a sub-form.
`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. 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.
`public string`	`$inputElementClass`	`'CFormInputElement'`	# the name of the class for representing a form input element. Defaults to 'CFormInputElement'. the name of the class for representing a form input element. Defaults to 'CFormInputElement'.
`public string`	`$buttonElementClass`	`'CFormButtonElement'`	# the name of the class for representing a form button element. Defaults to 'CFormButtonElement'. the name of the class for representing a form button element. Defaults to 'CFormButtonElement'.
`public array`	`$attributes`	`array()`	# 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. 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.
`public boolean`	`$showErrorSummary`	`false`	# whether to show error summary. Defaults to false. whether to show error summary. Defaults to false.
`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 `CForm::$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. 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 `CForm::$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. Since 1.1.14
`public string\|null`	`$errorSummaryHeader`		# HTML code to prepend 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()`.
`public string\|null`	`$errorSummaryFooter`		# HTML code to append to the list of errors in the error summary. See `CActiveForm::errorSummary()`. HTML code to append to the list of errors in the error summary. See `CActiveForm::errorSummary()`.
`public array`	`$activeForm`	`array('class'=>'CActiveForm')`	# 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 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'). Since 1.1.1

Magic properties summary
`public CForm`	`$root`	# The top-level form object. The top-level form object.
`public CActiveForm`	`$activeFormWidget`	# The active form widget associated with this form. This method will return the active form widget as specified by `CForm::$activeForm`. The active form widget associated with this form. This method will return the active form widget as specified by `CForm::$activeForm`.
`public CBaseController`	`$owner`	# The owner of this form. This refers to either a controller or a widget by which the form is created and rendered. The owner of this form. This refers to either a controller or a widget by which the form is created and rendered.
`public CModel`	`$model`	# The model associated with this form. If this form does not have a model, it will look for a model in its ancestors. The model associated with this form. If this form does not have a model, it will look for a model in its ancestors.
`public array`	`$models`	# The models that are associated with this form or its sub-forms. The models that are associated with this form or its sub-forms.
`public CFormElementCollection`	`$elements`	# The form elements. The form elements.
`public CFormElementCollection`	`$buttons`	# The form elements. The form elements.

Magic properties inherited from CFormElement
`$parent, $visible`

Packages

Classes

Class CForm

Parameters

Overrides

Parameters

Returns

See

Parameters

Returns

Returns

See

Returns

Returns

Since

Returns

Parameters

Returns

Parameters

Returns

Returns

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Returns

Returns

Parameters

Returns

Parameters

Parameters

Returns

Overrides

Returns

Parameters

Returns

Implementation of

Parameters

Returns

Implementation of

Parameters

Implementation of

Parameters

Implementation of

Since

Since