7分钟阅读时间 (1488 字)

Joomla! 3.1.0 标签字段

四月

Roberto Segura

星期一，01 四月 2013

265441 点击

0 评论

本文介绍了如何使用添加到 Joomla! 3.1.0 中的新标签字段以及为 Joomla! 开发者提供的新工具。

摘要

简介
基本用法
字段模式
允许/拒绝自定义标签
其他工具
1. ajax-chosen
2. 自定义标签字段
进行中

1. 简介

正如你们大多数人所知，Joomla! 3.1.0 集成了新的标签系统，具有以下关键特性

多语言。
嵌套标签结构。
集成在所有核心内容中（使用核心中首次看到的第一个统一内容模型方法）。
可选标签字段模式（AJAX 或嵌套）。
动态创建标签。
轻松集成到任何扩展中。

这是我非常期望在 Joomla! 中看到的功能。多年来我一直想知道为什么 Joomla! 有内容但没有标签。

我对系统的小小贡献是 AJAX 标签字段。在经历过其他标签系统后，我对字段的必要条件是

AJAX 标签搜索。
按 ENTER 键或逗号键插入自定义标签。
使用 Chosen jQuery 插件作为字段的基础，因为它已经集成到 Joomla! 核心中。
不要直接编辑 chosen 插件或其他任何库，以保持它们可升级（除了翻译）。

本文描述了新的字段以及添加到 Joomla! 中的所有新库和开发者工具。

2. 基本用法

大多数扩展都将使用标准字段模式，所以让我们先提供这些信息，以节省他们阅读本文的时间。

要在任何扩展中使用新的标签系统，您只需在表单 XML 中定义一个新的字段，如下所示

<field name="tags" type="tag"
    label="JTAG" description="JTAG_DESC"
    class="inputbox span12 small" multiple="true"
/>

关键是 type="tag" 部分。这就是全部。无需担心依赖关系。系统会为您完成剩余的工作。

在渲染表单时，系统将

加载 jQuery。
加载 chosen 插件。
加载 ajax-chosen 插件。
加载自定义JS代码以插入自定义标签。

3. 字段模式

为了能够涵盖所有用户偏好，我们决定利用所有贡献的代码，并让最终用户决定如何使用字段。在com_tag选项中，您将找到一个参数来调整字段模式，在AJAX或嵌套之间。

3.1. 自动模式

如果您在标签字段定义中未指定字段模式，您的字段将根据全局com_tags设置调整其行为。默认模式设置为AJAX。

3.2. AJAX模式

用户在标签字段中输入标签时，字段会搜索标签。
需要至少三个最小字符才能启动第一次后台AJAX搜索。
字段还允许通过输入标签并按ENTER或COMMA键来插入自定义标签。（可选）
在字段中插入的所有不存在的自定义标签都会在数据库中即时创建。

要强制字段使用AJAX模式，您必须这样定义

<field name="tags" type="tag" mode="ajax"
    label="JTAG" description="JTAG_DESC"
    class="inputbox span12 small" multiple="true"
/>

3.3. 嵌套模式

以层次视图显示标签，就像在其他核心组件中的类别选择器一样。
不允许自定义标签

要强制字段使用嵌套模式，您必须这样定义

<field name="tags" type="tag" mode="nested"
    label="JTAG" description="JTAG_DESC"
    class="inputbox span12 small" multiple="true"
/>

4. 允许/拒绝自定义标签

有些情况下，您希望用户选择标签，但又不希望他们能够插入新标签。该字段包含一个额外的“自定义”属性，可以强制字段接受/拒绝新标签。请注意，目前嵌套模式不允许创建自定义标签。因此，此设置仅适用于在AJAX模式下工作的字段。

如果您未指定“自定义”模式，则字段将默认允许它们。添加“允许”模式是为了未来可能添加模式的设置。

要强制字段允许标签

<field name="tags" type="tag" custom="allow"
    label="JTAG" description="JTAG_DESC"
    class="inputbox span12 small" multiple="true"
/>

要强制字段拒绝标签

<field name="tags" type="tag" custom="deny"
    label="JTAG" description="JTAG_DESC"
    class="inputbox span12 small" multiple="true"
/>

您可以在所有核心内容后端管理器中看到允许的自定义值示例。拒绝的自定义值示例可以在标签菜单项中找到。

5. 开发者附加工具

为了实现与chosen的AJAX搜索集成，我决定使用由Ryan LeFevre创建的ajax-chosen插件。我认为它本身就是一个很酷的附加组件，适用于其他扩展或核心组件。我需要做的就是集成并修改它，以允许自定义值。

在我保持所有插件未修改和可升级的斗争中，我想将ajax-chosen作为库提供，而无需将其绑定到标签字段。

本节将解释如何使用ajax-chosen集成以及如何构建自定义标签系统。

5.1. ajax-chosen

已向文件中添加了新的ajaxchosen方法

libraries/cms/html/formbehavior.php

其定义是

/**
 * Method to load the AJAX Chosen library
 *
 * If debugging mode is on an uncompressed version of AJAX Chosen is included for easier debugging.
 *
 * @param   JRegistry  $options  Options in a JRegistry object
 * @param   mixed      $debug    Is debugging mode on? [optional]
 *
 * @return  void
 *
 * @since   3.0
 */
public static function ajaxchosen(JRegistry $options, $debug = null)
{
}

JRegistry $options对象接受的选项是标准的AJAX jQuery选项和一些特定的ajax-chosen选项

minTermLength：触发AJAX调用之前必须输入的最小字符数
afterTypeDelay：停止输入后等待多少毫秒才触发AJAX调用
jsonTermKey：用于搜索查询的AJAX请求键（默认为term）

我还添加了一个选择器选项，该选项具有用于初始化为ajax-chosen字段的DOM对象的选择器。例如：#js-myfield

我们可以以文件中的调用为例

libraries/cms/html/tag.php

// Tags field ajax
$chosenAjaxSettings = new JRegistry(
	array(
		'selector'    => $selector,
		'type'        => 'GET',
		'url'         => JURI::root() . 'index.php?option=com_tags&task=tags.searchAjax',
		'dataType'    => 'json',
		'jsonTermKey' => 'like'
	)
);
JHtml::_('formbehavior.ajaxchosen', $chosenAjaxSettings);

非常简单！AJAX结果必须按照ajax-chosen文档中定义的方式返回。

对于标准结果，预期格式为

[{"value": 3, "text": "Ohio"}]

对于分组结果

[{
    group: true,
    text: "Europe",
    items: [
        { "value": "10", "text": "Stockholm" },
        { "value": "23", "text": "London" }
    ]
},
{
    group: true,
    text: "Asia",
    items: [
        { "value": "36", "text": "Beijing" },
        { "value": "20", "text": "Tokyo" }
    ]
}]

5.2. 自定义标签字段

以我们的标签字段定义为基础，构建自己的标签字段很容易。例如，如果我们想在自定义扩展中使用标签字段，但不想从核心标签表中加载数据。

我们将以K2标签系统为例。它使用自己的标签系统，并通过“q”搜索参数使用。

示例标签字段助手可以是

/**
 * This is just a proxy for the formbehavior.ajaxchosen method
 *
 * @param   string   $selector     DOM id of the tag field
 * @param   boolean  $allowCustom  Flag to allow custom values
 *
 * @return  void
 *
 * @since   3.1
 */
public static function k2tagsfield($selector='#jform_tags', $allowCustom = true)
{
	// Tags field ajax
	$chosenAjaxSettings = new JRegistry(
		array(
			'selector'    => $selector,
			'type'        => 'GET',
			'url'         => JURI::root() . 'index.php?option=com_k2&task=item.tags',
			'dataType'    => 'json',
			'jsonTermKey' => 'q'
		)
	);
	JHtml::_('formbehavior.ajaxchosen', $chosenAjaxSettings);
	// Allow custom values ?
	if ($allowCustom)
	{
		JFactory::getDocument()->addScriptDeclaration("
			(function($){
				$(document).ready(function () {
					// Method to add tags pressing enter
					$('" . $selector . "_chzn input').keydown(function(event) {
						// tag is greater than 3 chars and enter pressed
						if (this.value.length >= 3 && (event.which === 13 || event.which === 188)) {
							// Create the option
							var option = $('');
							option.text(this.value).val('#new#' + this.value);
							option.attr('selected','selected');
							// Add the option an repopulate the chosen field
							$('" . $selector . "').append(option).trigger('liszt:updated');
							this.value = '';
							event.preventDefault();
						}
					});
				});
			})(jQuery);
			"
		);
	}
}

当然，K2标签系统应该返回预期格式的标签。

在我们的字段定义中，我们将在getInput方法中添加对助手的调用，如下所示

// Get the field id
$id    = isset($this->element['id']) ? $this->element['id'] : null;
$cssId = '#' . $this->getId($id, $this->element['name']);

// Load the ajax-chosen customised field
JHtml::_('tag.k2tagsfield', $cssId, $this->allowCustom());

您可以查看标签字段定义以查看完整的字段定义

libraries/cms/form/field/tag.php