跳至主要内容
版本：5.1

表单操作

简介​

本节描述了Joomla表单API中比之前介绍的更高级的功能，包括以下方面

  • 设置文件路径，以便Joomla在您不遵循Joomla标准的情况下找到您的表单定义。
  • 定义字段分组 - Joomla提供了两种类型，即字段集和字段组。
  • 动态更改表单（在从XML文件加载后）。
  • 反射式方法，允许您从表单结构和数据中提取信息。

本节以一个示例组件结尾，其中包含上述各个方面的示例。

文件路径​

默认情况下，Joomla将在组件的…/forms文件夹中查找表单的XML定义（以及…/models/forms文件夹以保持与Joomla 3的兼容性），如果您的表单显示在前端，则在站点文件中，如果您的表单显示在后端，则在管理员文件中。静态函数addFormPath()允许您向Joomla将搜索的目录列表中添加不同的目录。

（类似地，addFieldPath()允许您为任何自定义表单字段定义定义不同的目录（Joomla 3中的默认值为…/models/fields），并且addRulePath()允许您为任何自定义验证规则定义不同的目录（Joomla 3中的默认值为…/models/rules）。但是，随着Joomla 4中引入的命名空间，更容易向表单添加addfieldprefix和addruleprefix属性，以使Joomla能够找到自定义字段类型和验证规则。）

字段集​

字段集与表单XML定义中的<fieldset name="myfieldset">元素相关联。使用字段集的优点是，在您的布局文件中，您可以使用

$form->renderFieldset("myfieldset");

呈现<fieldset>开始和结束标记内的所有具有<field>元素的字段。这代替了必须为字段集内的每个字段调用renderField()。

字段集可以被视为一组应一起在表单中显示的字段，因此在概念上类似于HTML <fieldset>元素。但是，请注意，renderFieldset()不会输出HTML <fieldset>或相关标签。

字段组​

字段组与表单XML定义中的<fields name="mygroup">元素相关联。这会影响分配给XML表单定义中<fields>开始和结束标记内定义的字段的HTML输入元素的HTML name属性，因此是HTTP POST请求中发送到服务器的参数名称。

如果您在设置表单实例时指定选项"control" => "myform"，则输入字段值将以如下方式作为键发送到HTTP POST请求中：

myform[field1]

myform[field2]

myform[field3]

如果您在XML表单定义中将这些字段包含在<fields name="mygroup">元素中，则POST参数将以如下名称发送：

myform[mygroup][field1]

myform[mygroup][field2]

myform[mygroup][field3]

如果您的组件具有数据库表，并且您将多个参数存储在表中的一列中的json字符串中，则可以将这些参数的HTML输入元素分组到<fields>元素中。如果将字段标签命名为与您的列名匹配，则可以使用Joomla表功能轻松地将POST参数产生的PHP关联数组转换为要存储在数据库中的json字符串。

出现在几个表单API方法中的$group参数指的是表单定义XML中<fields>标签的name属性。

请注意，字段集和字段组是独立的。在表单XML定义中，您可以在<fieldset>元素内包含<fields>元素，以及在<fields>元素内包含<fieldset>元素。

动态更改表单​

如果您已在XML文件中静态定义了表单，则一旦加载，您就可以使用表单API在PHP代码中动态修改它

  • 通过加载另一个表单XML定义来向表单添加更多字段
  • 修改现有字段或字段
  • 删除字段或字段组。

通过表单定义添加字段​

要将来自文件的其他定义包含到表单中，请执行以下操作

$form->loadFile($filename);

传递与主表单定义文件结构相同的XML文件的$filename。

或者，您可以在代码中创建一个包含相同XML的SimpleXMLElement（例如$xml），然后调用

$form->load($xml);

（loadFile()的Joomla代码只是将数据从文件读取到SimpleXMLElement变量中，然后调用load()）。

对于这两个函数，您可以传递其他参数

  • $replace（在load()方法中）/ $reset（在loadFile()方法中） - 这两个具有相同的效果，并且与加载的XML中某个字段的名称与表单中已有的某个字段的名称相同的情况相关。如果设置为true，则新字段将替换旧字段。如果设置为false，则忽略新字段。
  • $xpath - 如果您只想考虑加载的XML结构的一部分，则可以指定xpath来选择要包含的XML的部分或部分。

除了下面示例代码中的示例之外，您还可以在核心Joomla管理员com_menu代码中找到加载其他XML文件的示例，这与管理员设置站点菜单选项时相关。站点菜单项的基本选项在管理员/com_menus/models/forms中的item.xml文件中指定，但在com_menu模型item.php代码中，这会用XML文件中定义的选项进行补充，该XML文件位于与将要显示的站点页面相关的布局目录中。

动态设置字段​

您可以使用setField()在表单实例中添加或替换单个字段，并使用setFields()添加或替换多个字段。要使用它们，请创建与字段相关的XML，然后将其传递给setField()

$xml = new SimpleXMLElement('<field name="newfield" … />');
$form->setField($xml);

类似地，您可以定义此类XML元素的数组并将它们传递给setFields()，这相当于对每个单独的元素调用setField()。

指定$group和$fieldset参数以将新字段包含在特定字段组和字段集中。

如果$replace参数设置为true，则如果找到具有相同字段组和名称的现有字段，它将被替换。

如果$replace参数设置为false并且找到具有相同字段组和名称的现有字段，则将忽略新字段。

设置字段属性和值​

setFieldAttribute()允许您设置/修改与字段关联的属性。请注意，该属性指的是Joomla字段属性，而不是输入元素的HTML属性。例如，要设置HTML placeholder属性，您必须设置Joomla hint字段属性，并且这仅在表单字段类型支持该属性时才有效。

HTML value属性的处理方式与其他HTML属性略有不同。如表单的工作原理中所述，在Joomla表单实例中，XML表单结构（由表单定义XML文件定义）与表单预填充数据（在bind()方法中传递）分开保存。HTML输入元素的value属性中输出的内容主要是默认的Joomla表单字段属性（如果该字段类型支持），但会被bind()调用中为该字段指定的任何值覆盖。

因此，您可以使用setFieldAttribute()设置默认属性，但要直接在预填充数据中设置字段值，请使用setValue()。

删除字段​

您可以通过调用removeField()删除特定字段或removeGroup()删除指定字段组内的所有字段来从表单定义中删除字段。

反射方法​

有一些方法允许您访问表单实例数据的各个方面。大多数情况下，这些方法都相当容易理解，并且仅在可能不太清楚的情况下才会在下面进行解释。

getData()作为Joomla注册表对象返回已使用表单bind()调用设置的预填充数据。

方法getField()、getFieldset()和getGroup()都返回Joomla FormField对象作为字段，而不是表单实例内部保存的方式。

getFieldsets()返回一个Fieldset对象的数组，其属性反映了表单定义文件中的<fieldset>标签。因此，如果您有

<fieldset name="myfieldset" label="myfieldsetLabel" description="myfieldsetDescription">

那么您可以执行以下操作

$fieldsets = $form->getFieldsets();
echo $fieldsets['myfieldset']->label;   // outputs "myfieldsetLabel"

getFormControl()返回创建表单实例时传递的$options参数中的字符串。如果您在$options数组中使用了Joomla标准的"control" => "jform"，那么getFormControl()将返回字符串“jform”。

getInput()和getLabel()分别返回作为参数传递的字段的<input>标签和<label>的HTML。但是，请注意，如果您有自定义字段，则这两个方法都不起作用。另请注意，这些表单方法与设置某些类型的自定义字段时必须提供的getInput()和getLabel()FormField方法不同。

getValue()返回您作为参数传递的字段的值，从bind()调用中传递的数据中读取此值。它不考虑针对字段设置的默认属性，如果未提供该字段的预填充数据，则该属性将转换为HTML字段值属性。

示例组件代码​

对于本节，您可以下载此组件zip文件并安装它。它演示了本节中描述的几个功能。它不遵循标准的Joomla MVC模式，而是将所有功能都放在单个扩展类中。这是因为它的目的是突出显示与操作表单相关的API。

安装完文件后，导航到您的网站首页，并添加查询参数?option=com_sample_form3来运行组件。这应该会显示表单，并允许您输入数据并提交表单。代码中的注释应该可以清楚地说明正在发生的事情。