CForm

'elements'=>array(
    'username'=>array('type'=>'text', 'maxlength'=>80),
    'password'=>array('type'=>'password', 'maxlength'=>80),
)

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)

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)

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)

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()

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()

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

getButtons() method

public CFormElementCollection getButtons()

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()

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.

getModel() method

public CModel getModel(boolean $checkParent=true)

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()

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()

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

getRoot() method

public CForm getRoot()

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

getUniqueId() method

protected string getUniqueId()

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()

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()

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.

offsetExists() method

public boolean offsetExists(mixed $offset)

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.

offsetGet() method

public mixed offsetGet(integer $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.

offsetSet() method

public void offsetSet(integer $offset, mixed $item)

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.

offsetUnset() method

public void offsetUnset(mixed $offset)

public function offsetUnset($offset)
{
    $this->getElements()->remove($offset);
}

Unsets the element at the specified offset. This method is required by the interface ArrayAccess.

removedElement() method

public void removedElement(string $name, CFormElement $element, boolean $forButtons)

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

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

render() method

public string render()

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()

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()

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()

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)

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()

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()

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)

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)

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)

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

submitted() method

public boolean submitted(string $buttonName='submit', boolean $loadData=true)

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.

validate() method

public boolean validate()

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.