README

Travis 状态

1.x 分支:

开发状态:

已弃用

joomla/form包已被弃用。没有进一步的更新计划。

简介

表单包提供了一个简单接口来创建、显示和验证表单。

创建表单及加载数据

要在代码中使用表单包，请包含

use Joomla\Form\Form;

现在您可以通过编程方式或从XML文件中加载表单来创建表单对象。

表单文件结构

表单包需要有效的XML形式的表单。例如，用于定义客户的表单会使用以下XML

<?xml version="1.0" encoding="utf-8"?>
<form>
	<fields>
		<field name="id" type="hidden" label=""/>
		<field name="first_name" type="text" label="First Name" required="true"/>
		<field name="last_name" type="text" label="Last Name" required="true"/>
		<field name="street" type="text" label="Street" required="false"/>
		<field name="suburb" type="text" label="suburb" required="false"/>
		<field name="state" type="list" label="state" required="false">
			<option value="QLD">Queensland</option>
			<option value="NSW">New South Wales</option>
			<option value="ACT">Australian Capital Territory</option>
			<option value="VIC">Victoria</option>
			<option value="TAS">Tasmania</option>
			<option value="SA">South Australia</option>
			<option value="WA">Western Australia</option>
			<option value="NT">Nothern Territory</option>
			<option value="N/A">Outside Australia</option>
		</field>
		<field name="postcode" type="text" label="Postcode" required="false"/>
		<field name="email" type="text" label="Email" validate="email" required="false"/>
		<field name="phone" type="text" label="Phone" validate="tel" required="true" />
	</fields>
</form>

更高级的表单还可以将表单分组到字段集和组中。

此简单表单定义了多个字段作为文本输入，一个列表（以选择框形式显示）和一个隐藏输入用于客户的id字段。

每个元素都有以下必选属性

• name - 字段在表单中和手动加载表单元素时使用的名称。
• type - 将渲染的元素类型。例如，text将生成文本字段，而list将生成选择框。
• label - 应用于元素的标签。

以下可选属性也可用

• required - 元素是否为必填项。
• validate - 运行表单验证时将应用哪些验证规则
• label class - 应应用于标签的任何可选类。这特别有用，如果您想确保您的表单在响应式模板中渲染良好。
• class - 应应用于字段本身的任何可选类。

加载数据表单

创建表单XML后，您需要将其加载到代码中以供使用。

第一步是创建一个表单对象。至少构建一个新表单对象需要命名表单。要创建一个最小表单对象，您可以使用以下代码

use Joomla\Form\Form;

$clientForm = new Form('client');

表单已初始化并准备好使用。目前它没有任何字段或与之关联的数据。

表单类提供了两种加载数据表单的方法

• Form::load - 可以用于使用在SimpleXMLElement中定义的字段加载数据表单。这可能通过编程方式创建或之前加载。
• Form::loadFile - 将XML文件的字符串引用传递给表单。

无论哪种方式，结果都是相同的。您的表单现在加载了字段并准备好使用。

将数据绑定到表单

如果表单用于显示数据，您需要填充表单字段。这可以通过使用 Form::bind() 方法来实现。此方法接受一个数组或一个对象，并使用具有相同名称的键或属性填充表单元素的值。

例如，使用上面定义的客户表单，可以这样填充一个数组

$customer = new array('first_name'=>'John','last_name'=>'Smith', ...);
$clientForm->bind($customer);

如果您在表单中使用组，您需要在父元素下嵌套这些键。

显示您的表单元素

假设您在某个时候想显示表单进行数据输入。要显示表单，有两种方法，具体取决于您对选项位置和布局的控制程度。

选项 1：直接输出元素

这是一个最简单的选项，当您有一个小型、简单的表单或不太关心自定义表单布局时很有用。

使用 Form::getGroup() 方法加载表单字段。这需要一个字符串，表示您想要加载哪个字段组。如果您没有使用字段组，只需传递一个空字符串即可。例如，要从客户表单加载字段，我会使用以下代码

$fields = $customForm->getGroup('');

一旦将字段加载到表单中，您就可以遍历这些字段来显示标签、输入字段以及绑定数据（如果有的话）。

foreach ($fields as $field) {
	echo $field->label;
	echo $field->input;
}

选项 2：显示具有更多控制的表单

如果您想对表单布局有更多控制，可以通过名称访问每个字段。例如，为了加载 first_name 字段的输入和标签，您会使用以下代码

echo $form->getLabel('first_name');
echo $form->getInput('first_name');

用于控制表单显示的附加选项

表单中的每个元素也可以分配属性 class 和 labelclass。这些包含将应用于标签和输入元素的额外类。当使用包含 bootstrap 类的响应式表单设计时，可以使用此功能。

验证您的表单数据

Joomla 表单对象允许轻松验证字段。表单对象提供了一个 validate 方法，该方法将用户输入与在 XML 中定义的验证规则进行测试。

在验证表单数据之前，必须重新加载表单。（参见上面的“加载表单”）。

表单重新加载后，不要将其绑定到数据。这次调用 Form::validate() 方法，传入一个包含您希望验证的数据的数组。例如

$clientForm->validate($_POST);

这将验证存储在 POST 数组中的数据与表单中定义的验证规则。

可以通过使用 Form::getErrors() 函数检索验证错误

$clientForm->getErrors();

目前这将返回一个 RuntimeException 对象数组。

验证规则使用 XML 中的 validate 属性定义。以下规则目前定义如下

• 布尔值 - 测试字段是否为真或假
• 颜色 - 测试字段是否包含有效的十六进制颜色值。（例如，#00000 到 #fffff）。不需要输入 '#'。
• 电子邮件 - 测试字段是否包含电子邮件值。
• 等于 - 测试两个值是否相等。
• 选项 - 确保输入的值是列表中给出的选项之一。
• 电话 - 验证字段是否为电话号码。还可以指定一个可选属性 plan 来定义电话模式。当前选项包括：northamerica、us、International、int、missdn、IETF。
• URL - 验证字段是否为URL。

创建自定义字段

Joomla表单包允许您创建自定义表单字段。为此，您只需要扩展 \Joomla\Form\Field 类。

示例

在文件 "CustomField.php" 中编写

namespace Joomla\Form\Field;

class CustomField extends \Joomla\Form\Field
{
	// Override this function
	public function getInput()
	{
		return 'field\'s html string.';
	}
}

要在您的表单中使用上述字段，请编写

<field type="custom" name="myName" id="myId" />

不同命名空间中的字段

您也可以在Joomla之外的不同命名空间中创建自定义字段。

示例

在文件 "FooField.php" 中编写

namespace Bar\Form\Field;

class FooField extends \Joomla\Form\Field
{
	// Override this function
	public function getInput()
	{
		return 'field\'s html string.';
	}
}

要使用上述字段，只需编写

<field type="bar.foo" name="myName" id="myId" />

子命名空间中的字段

要创建Joomla\Form\Field子命名空间中的字段。

示例

在文件 "FooField.php" 中编写

namespace Joomla\Form\Field\Bar;

class FooField extends \Joomla\Form\Field
{
	// Override this function
	public function getInput()
	{
		return 'field\'s html string.'
	}
}

要使用上述字段，只需编写

<field type="bar\foo" name="myName" id="myId" />

通过Composer安装

将 "joomla/form": "2.0@dev" 添加到 composer.json 中的 require 块，然后运行 composer install。

{
	"require": {
		"joomla/form": "2.0@dev"
	}
}

或者，您可以直接在命令行中运行以下命令

composer require joomla/form "2.0@dev"