包 | system.web.form |
---|---|
继承 | class CForm » CFormElement » CComponent |
实现 | ArrayAccess |
源自 | 1.1 |
版本 | $Id: CForm.php 3426 2011-10-25 00:01:09Z alexander.makarow $ |
源码 |
引入抽象的表单对象主要目的是为了提高表单的可重用性。 特别是,我可以把表单分为两部分: 那些指定的每个个别的表单输入,和那些装饰的表单输入。 一个CForm对象代表前者,它依靠渲染进程来完成表单输入元素的装饰。 可重用性主要体现在渲染的过程中。 也就是说,一个渲染过程可以重复使用来呈现不同的CForm对象。
一个表单可以以不同的方式渲染。一种是可以调用render方法 来快速的渲染一个表单面无需编写任何的HTML代码。 一种是覆盖render方法调用不同布局的来渲染一个表单 还可以是使用一个外部的视图模板来渲染每个表单元素。 从而,render方法可以应用于所有各类的表单,来达到最大的可重用性。 外部的视图模板来渲染复杂的表单,操持了最在的灵活性。
表单的输入元素依据表单输入元素的层级来组织。 根本的层级,是CForm对象, 根表用两个集合来保持它的子女。elements和buttons. 前者包含了非按钮的表单元素(CFormStringElement, CFormInputElement和CForm); 后者主要包括按钮元素(CFormButtonElement).当一个CForm对象嵌入到 elements集合时,它被称为一个子表,它可以拥有它自己的elements 和buttons两个集合从而形成整体的表单层次。
子表主要用于处理多重模型,例如, 一个用户注册表,我们可以用根表来收集用户表的输入。 面子表收集个人资料的输入。 子表是一个较好的方式来把一个长表分割成较短的表。 即便所有的输入都属于同一个模型。
按照配置数组和给定的表单规格, 用来初始化一个CForm对象的属性值。 elements和buttons属性需要特别注意, 它们是主要要配置的属性。配置elements,我们的给定数组如下: the following:
'elements'=>array( 'username'=>array('type'=>'text', 'maxlength'=>80), 'password'=>array('type'=>'password', 'maxlength'=>80), )上面的代码指定了两个输入元素: 'username'和'password'。 注意,模型对象恰好有同样的属性'username'和'password'。 每个表单元素有多种类型可选择使用。 一个指定的输入元素数组中的其它元素(如'maxlength')是当输入元素被渲染时渲染到上面的HTML属性 buttons属性的配置也类似这个。
想了解更多关于表单元素的详细信息, 请参阅CFormInputElement和CFormButtonElement。
公共属性
属性 | 类型 | 描述 | 定义在 |
---|---|---|---|
action | mixed | 表单action的URL (请参阅 CHtml::normalizeUrl来了解更详细的信息) 默认是一个空的字符串,意味着当前请求的URL。 当表单是一个子表单时,此属性会被忽略。 | CForm |
activeForm | array | 用于创建加强型表单挂件的配置。 这个挂件将用于渲染表单元素和错误信息。 'class'选项是必须的,用来指定挂件的类。 其它的选项将传到CBaseController::beginWidget()方法。 默认为array('class'=>'CActiveForm'). | CForm |
activeFormWidget | CActiveForm | 和这个表单有关的挂件。the active form widget associated with this form. | CForm |
attributes | array | 表单标签的HTML属性值。当一个表单被嵌入到另一个表单时, 这个属性将会用于渲染HTML属性值到子表单。 | CForm |
buttonElementClass | string | 代表一个表单按钮的类。默认为'CFormButtonElement'. | CForm |
buttons | CFormElementCollection | 返回表单的按钮元素。 | CForm |
description | string | 表单的描述。 | CForm |
elements | CFormElementCollection | 渲染表单的输入元素。 | CForm |
inputElementClass | string | 代表一个表单输入元素的类。默认为'CFormInputElement'. | CForm |
method | string | 表单的提交方法。默认为'post'。 当表单是一个子表单时,此属性会被忽略。 | CForm |
model | CModel | 返回和这个表单有关的模型 | CForm |
models | array | 返回所有和这个表单有关的模型或者子表单。 | CForm |
owner | CBaseController | 表单的拥有者。 可以引用一个控制器的引用也可以引用一个挂件,在表单创建和渲染时。 | CForm |
parent | mixed | 这个元素的真系父类。它可能是CForm对象,也可能是CBaseController对象。 (控制器或挂件)。 | CFormElement |
root | CForm | 最高阶层的表单对象 | CForm |
showErrorSummary | boolean | 是否显示错误摘要。默认为false。 | CForm |
title | string | 表单的题目。默认情况下,如果设置了这个, 一个自定义的控件可能会被渲染在表单内容的周围,使用题目作为它的说明。默认为null。 | CForm |
visible | boolean | 返回值说明这个元素是否可见并需要渲染。 | CFormElement |
受保护属性
属性 | 类型 | 描述 | 定义在 |
---|---|---|---|
uniqueId | string | 返回当前页这个表单的唯一标识符。 | CForm |
公共方法
方法 | 描述 | 定义在 |
---|---|---|
__call() | 如果类中没有调的方法名,则调用这个方法。 | CComponent |
__construct() | 构造方法。 | CForm |
__get() | 返回属性值。 | CFormElement |
__isset() | 检查一个属性是否为null。 | CComponent |
__set() | 设置属性值。 | CFormElement |
__toString() | 将对象转换为字符串。 | CFormElement |
__unset() | 设置一个组件的属性为null。 | CComponent |
addedElement() | 一个元素被添加到元素集合后该方法被调用。 | CForm |
asa() | 返回这个名字的行为对象。 | CComponent |
attachBehavior() | 附加一个行为到组件。 | CComponent |
attachBehaviors() | 附加一个行为列表到组件。 | CComponent |
attachEventHandler() | 为事件附加一个事件处理程序。 | CComponent |
canGetProperty() | 确定属性是否可读。 | CComponent |
canSetProperty() | 确定属性是否可写。 | CComponent |
clicked() | 返回一个值来表明是否指定的按钮被点击了。 | CForm |
configure() | 根据初始化的值来配置这个对象。 | CFormElement |
detachBehavior() | 从组件中分离一个行为。 | CComponent |
detachBehaviors() | 从组件中分离所有行为。 | CComponent |
detachEventHandler() | 分离一个存在的事件处理程序。 | CComponent |
disableBehavior() | 禁用一个附加行为。 | CComponent |
disableBehaviors() | 禁用组件附加的所有行为。 | CComponent |
enableBehavior() | 启用一个附加行为。 | CComponent |
enableBehaviors() | 启用组件附加的所有行为。 | CComponent |
evaluateExpression() | 计算一个PHP表达式,或根据组件上下文执行回调。 | CComponent |
getActiveFormWidget() | 返回和这个表单有关的挂件。the active form widget associated with this form. 这个方法将按照activeForm挂件来返回一个加强型的表单。 | CForm |
getButtons() | 返回表单的按钮元素。 | CForm |
getElements() | 渲染表单的输入元素。 | CForm |
getEventHandlers() | 返回一个事件的附加处理程序列表。 | CComponent |
getModel() | 返回和这个表单有关的模型 | CForm |
getModels() | 返回所有和这个表单有关的模型或者子表单。 | CForm |
getOwner() | 返回表单的拥有者。 可以引用一个控制器的引用也可以引用一个挂件,在表单创建和渲染时。 | CForm |
getParent() | 返回这个元素的真系父类。它可能是CForm对象,也可能是CBaseController对象。 (控制器或挂件)。 | CFormElement |
getRoot() | 返回最高阶层的表单对象 | CForm |
getVisible() | 返回值说明这个元素是否可见并需要渲染。 | CFormElement |
hasEvent() | 确定一个事件是否定义。 | CComponent |
hasEventHandler() | 检查事件是否有附加的处理程序。 | CComponent |
hasProperty() | 确定属性是否被定义。 | CComponent |
loadData() | 加载提交的数据到相关的表单模型中。 | CForm |
offsetExists() | 返回在指定偏移量上是否存在一个元素。 | CForm |
offsetGet() | 返回指定偏移量上面的元素。 | CForm |
offsetSet() | 在指定偏移量上设置元素。 | CForm |
offsetUnset() | 注销指定偏移量上的元素。 | CForm |
raiseEvent() | 发起一个事件。 | CComponent |
removedElement() | 一个元素从元素集合中被删除后该方法被调用。 | CForm |
render() | 渲染表单。 | CForm |
renderBegin() | 渲染表单的开始标签。 | CForm |
renderBody() | 渲染表单的主体。 | CForm |
renderButtons() | 渲染表单的buttons. | CForm |
renderElement() | 渲染一个单一的元素,它可以是一个输入元素,一个子表单,一个字符串或一个按钮。 | CForm |
renderElements() | 渲染这个表单的elements。 | CForm |
renderEnd() | 渲染表单的结果标签。 | CForm |
setButtons() | 配置表单的按钮。 | CForm |
setElements() | 配置表单的输入元素。 | CForm |
setModel() | 设置和这个表单有关的模型 | CForm |
setVisible() | 设置这个元素是否可见并需要渲染。 | CFormElement |
submitted() | 返回一个值来表明是否表彰被提交了。 | CForm |
validate() | 验证与这个表单相关的模型。 | CForm |
受保护方法
方法 | 描述 | 定义在 |
---|---|---|
evaluateVisible() | 评估这个表单的可见性。 | CForm |
getUniqueId() | 返回当前页这个表单的唯一标识符。 | CForm |
init() | 初始化表单。 | CForm |
属性详细
表单action的URL (请参阅 CHtml::normalizeUrl来了解更详细的信息) 默认是一个空的字符串,意味着当前请求的URL。 当表单是一个子表单时,此属性会被忽略。
用于创建加强型表单挂件的配置。 这个挂件将用于渲染表单元素和错误信息。 'class'选项是必须的,用来指定挂件的类。 其它的选项将传到CBaseController::beginWidget()方法。 默认为array('class'=>'CActiveForm').
和这个表单有关的挂件。the active form widget associated with this form. 这个方法将按照activeForm挂件来返回一个加强型的表单。
表单标签的HTML属性值。当一个表单被嵌入到另一个表单时, 这个属性将会用于渲染HTML属性值到子表单。
代表一个表单按钮的类。默认为'CFormButtonElement'.
返回表单的按钮元素。 注意,返回的结果是一个CFormElementCollection对象, 意味着你可以像使用一个数组那样使用它,请参阅CMap.
表单的描述。
渲染表单的输入元素。 它包括文本字符串,输入元素和子表单。 注意返回的是一个CFormElementCollection对象, which 意味着你可以像使用一个数组那样使用它。更多详细情况请参阅CMap.
代表一个表单输入元素的类。默认为'CFormInputElement'.
表单的提交方法。默认为'post'。 当表单是一个子表单时,此属性会被忽略。
返回和这个表单有关的模型
返回所有和这个表单有关的模型或者子表单。
表单的拥有者。 可以引用一个控制器的引用也可以引用一个挂件,在表单创建和渲染时。
最高阶层的表单对象
是否显示错误摘要。默认为false。
表单的题目。默认情况下,如果设置了这个, 一个自定义的控件可能会被渲染在表单内容的周围,使用题目作为它的说明。默认为null。
返回当前页这个表单的唯一标识符。
方法详细
public void __construct(mixed $config, CModel $model=NULL, mixed $parent=NULL)
| ||
$config | mixed | 这个表单的配置。 它可以是一个配置数组或者是一个返回配置数组的PHP脚本文件的别名。 配置数组由名称-值对组成, 用于初始化这个表单的属性。 |
$model | CModel | 这个表单相关的模型对象,如果是null, 父类的模型来替代。 |
$parent | mixed | 这个表单的直系父类。它可能是一个CBaseController对象, (一个控制器或一个挂件),或者一个CForm对象。 如果是前者,意味着表单是一个顶级的表单;如果是后者,意味着表单是一个子表单。 |
public function __construct($config,$model=null,$parent=null)
{
$this->setModel($model);
if($parent===null)
$parent=Yii::app()->getController();
parent::__construct($config,$parent);
$this->init();
}
构造方法。 如果你覆盖此方法,确保你没有修改方法的特征。 要确保调用父类的实现。
public void addedElement(string $name, CFormElement $element, boolean $forButtons)
| ||
$name | string | 元素的名称 |
$element | CFormElement | 新添加的元素 |
$forButtons | boolean | 元素是否添加到了buttons集合中。 如果是false,意味着一个元素添加到了elements集合中。 |
public function addedElement($name,$element,$forButtons)
{
}
一个元素被添加到元素集合后该方法被调用。
public boolean clicked(string $name)
| ||
$name | string | 按钮名称 |
{return} | boolean | 按钮是否被点击了 |
public function clicked($name)
{
if(strcasecmp($this->getRoot()->method,'get'))
return isset($_POST[$name]);
else
return isset($_GET[$name]);
}
返回一个值来表明是否指定的按钮被点击了。
protected boolean evaluateVisible()
| ||
{return} | boolean | 表单是否可见 |
protected function evaluateVisible()
{
foreach($this->getElements() as $element)
if($element->getVisible())
return true;
return false;
}
评估这个表单的可见性。 这个方法将检查elements的可见性。 如果有任意一个是可见的,表单就被认为是可见的,否则,不可见。
public CActiveForm getActiveFormWidget()
| ||
{return} | CActiveForm | 和这个表单有关的挂件。the active form widget associated with this form. 这个方法将按照activeForm挂件来返回一个加强型的表单。 |
public function getActiveFormWidget()
{
if($this->_activeForm!==null)
return $this->_activeForm;
else
return $this->getRoot()->_activeForm;
}
public CFormElementCollection getButtons()
| ||
{return} | CFormElementCollection | 表单元素 |
public function getButtons()
{
if($this->_buttons===null)
$this->_buttons=new CFormElementCollection($this,true);
return $this->_buttons;
}
返回表单的按钮元素。 注意,返回的结果是一个CFormElementCollection对象, 意味着你可以像使用一个数组那样使用它,请参阅CMap.
public CFormElementCollection getElements()
| ||
{return} | CFormElementCollection | 表单元素。 |
public function getElements()
{
if($this->_elements===null)
$this->_elements=new CFormElementCollection($this,false);
return $this->_elements;
}
渲染表单的输入元素。 它包括文本字符串,输入元素和子表单。 注意返回的是一个CFormElementCollection对象, which 意味着你可以像使用一个数组那样使用它。更多详细情况请参阅CMap.
public CModel getModel(boolean $checkParent=true)
| ||
$checkParent | boolean | 如果表单没有本身的模型,是否返回父类的模型 |
{return} | CModel | 和这个表单有关的模型。如果表单没有一个模型, 将在它的祖先中查找。 |
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;
}
返回和这个表单有关的模型
public array getModels()
| ||
{return} | array | 返回所有和这个表单有关的模型或者子表单。 |
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;
}
返回所有和这个表单有关的模型或者子表单。
public CBaseController getOwner()
| ||
{return} | CBaseController | 表单的拥有者。 可以引用一个控制器的引用也可以引用一个挂件,在表单创建和渲染时。 |
public function getOwner()
{
$owner=$this->getParent();
while($owner instanceof self)
$owner=$owner->getParent();
return $owner;
}
public CForm getRoot()
| ||
{return} | CForm | 最高阶层的表单对象 |
public function getRoot()
{
$root=$this;
while($root->getParent() instanceof self)
$root=$root->getParent();
return $root;
}
protected string getUniqueId()
| ||
{return} | string | 表单的唯一标识符 |
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()))));
}
返回当前页这个表单的唯一标识符。
protected void init()
|
protected function init()
{
}
初始化表单。 这个方法在构造器中被调用。 你可心覆盖此方法来自定义初始化 (比如配置表单对象).
public void loadData()
|
public function loadData()
{
if($this->_model!==null)
{
$class=get_class($this->_model);
if(strcasecmp($this->getRoot()->method,'get'))
{
if(isset($_POST[$class]))
$this->_model->setAttributes($_POST[$class]);
}
else if(isset($_GET[$class]))
$this->_model->setAttributes($_GET[$class]);
}
foreach($this->getElements() as $element)
{
if($element instanceof self)
$element->loadData();
}
}
加载提交的数据到相关的表单模型中。 这个方法将穿过所有和这个表单相关的模型和子表单。 大量的指派提交的数据到模型中。
参见
public boolean offsetExists(mixed $offset)
| ||
$offset | mixed | 指定的偏移量 |
{return} | boolean |
public function offsetExists($offset)
{
return $this->getElements()->contains($offset);
}
返回在指定偏移量上是否存在一个元素。 该方法是ArrayAccess接口所必须的。
public mixed offsetGet(integer $offset)
| ||
$offset | integer | 指定的偏移量 |
{return} | mixed | 在指定偏移量上面的元素,如果在指定偏移量上未找到元素则返回null。 |
public function offsetGet($offset)
{
return $this->getElements()->itemAt($offset);
}
返回指定偏移量上面的元素。 该方法是ArrayAccess接口所必须的。
public void offsetSet(integer $offset, mixed $item)
| ||
$offset | integer | 指定的偏移量 |
$item | mixed | 元素的值 |
public function offsetSet($offset,$item)
{
$this->getElements()->add($offset,$item);
}
在指定偏移量上设置元素。 该方法是ArrayAccess接口所必须的。
public void offsetUnset(mixed $offset)
| ||
$offset | mixed | 指定的偏移量 |
public function offsetUnset($offset)
{
$this->getElements()->remove($offset);
}
注销指定偏移量上的元素。 该方法是ArrayAccess接口所必须的。
public void removedElement(string $name, CFormElement $element, boolean $forButtons)
| ||
$name | string | 元素的名称 |
$element | CFormElement | 被删除的元素 |
$forButtons | boolean | 元素是否从buttons集合中删除 如果是false,意味着元素从elements集合中删除了。 |
public function removedElement($name,$element,$forButtons)
{
}
一个元素从元素集合中被删除后该方法被调用。
public string render()
| ||
{return} | string | 渲染结果 |
public function render()
{
return $this->renderBegin() . $this->renderBody() . $this->renderEnd();
}
渲染表单。 默认仅是调用renderBegin, renderBody和renderEnd。
public string renderBegin()
| ||
{return} | string | 渲染结果 |
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=\"visibility:hidden\">".CHtml::hiddenField($this->getUniqueID(),1)."</div>\n";
}
}
渲染表单的开始标签。 默认是渲染表单的开始标签。
public string renderBody()
| ||
{return} | string | 渲染结果 |
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)."\n";
$output.=$this->renderElements()."\n".$this->renderButtons()."\n";
if($this->title!==null)
$output.="</fieldset>\n";
return $output;
}
渲染表单的主体。 这个方法主要渲染elements和buttons。 如果title或description被指定,它们同样会被渲染。 如果关联模型包含错误,错误摘要会显示。 表单标签将不会被渲染。 请调用renderBegin和renderEnd来渲染表单的开始和结束标签。 你可以覆盖这个方法来自定义表单的渲染。
public string renderButtons()
| ||
{return} | string | 渲染的结果 |
public function renderButtons()
{
$output='';
foreach($this->getButtons() as $button)
$output.=$this->renderElement($button);
return $output!=='' ? "<div class=\"row buttons\">".$output."</div>\n" : '';
}
渲染表单的buttons.
public string renderElement(mixed $element)
| ||
$element | mixed | 要被渲染的表单元素,它可以是一个CFormElement实例, 也可以是一个代表表单元素的字符串。 |
{return} | string | 渲染的结果 |
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=\"visibility:hidden\">\n".$element->render()."</div>\n";
else
return "<div class=\"row field_{$element->name}\">\n".$element->render()."</div>\n";
}
else if($element instanceof CFormButtonElement)
return $element->render()."\n";
else
return $element->render();
}
return '';
}
渲染一个单一的元素,它可以是一个输入元素,一个子表单,一个字符串或一个按钮。
public string renderElements()
| ||
{return} | string | 渲染的结果 |
public function renderElements()
{
$output='';
foreach($this->getElements() as $element)
$output.=$this->renderElement($element);
return $output;
}
渲染这个表单的elements。
public string renderEnd()
| ||
{return} | string | 渲染结果 |
public function renderEnd()
{
if($this->getParent() instanceof self)
return '';
else
{
ob_start();
$this->getOwner()->endWidget();
return ob_get_clean();
}
}
渲染表单的结果标签。
public void setButtons(array $buttons)
| ||
$buttons | array | 按钮的配置 |
public function setButtons($buttons)
{
$collection=$this->getButtons();
foreach($buttons as $name=>$config)
$collection->add($name,$config);
}
配置表单的按钮。 配置必须是一个以按钮名为索引的按钮配置数组。 每个按钮的配置由名称-值对组成, 用于初始化一个CFormButtonElement对象。
public void setElements(array $elements)
| ||
$elements | array | 按钮的配置 |
public function setElements($elements)
{
$collection=$this->getElements();
foreach($elements as $name=>$config)
$collection->add($name,$config);
}
配置表单的输入元素。 配置必须是以输入元素名称为索引的输入元素配置数组。 每个输入元素数组由名称-值对组成, 用于初始化一个CFormStringElement对象(当'type'为'string'时),一个CFormElement对象 (当'type'是以'Form'结尾的字符串时), 或者一个CFormInputElement对象 在所有其它情况下。
public void setModel(CModel $model)
| ||
$model | CModel | 和这个表单有关的模型 |
public function setModel($model)
{
$this->_model=$model;
}
public boolean submitted(string $buttonName='submit', boolean $loadData=true)
| ||
$buttonName | string | 提交按钮的名称 |
$loadData | boolean | 如果表单被提交是否调用loadData 以便提交的数据可以传给相关的模型 |
{return} | boolean | 表单是否被提交了。 |
public function submitted($buttonName='submit',$loadData=true)
{
$ret=$this->clicked($this->getUniqueId()) && $this->clicked($buttonName);
if($ret && $loadData)
$this->loadData();
return $ret;
}
返回一个值来表明是否表彰被提交了。
参见
public boolean validate()
| ||
{return} | boolean | 是否所有的模型都有效 |
public function validate()
{
$ret=true;
foreach($this->getModels() as $model)
$ret=$model->validate() && $ret;
return $ret;
}
验证与这个表单相关的模型。 所有的模型,包括和那些子表单相关的, 都将完验证,你可以使用CModel::getErrors()来 检索错误信息。