7分钟阅读时间 (1467个单词)

Joomla! 3.1 标签

四月

Chris Hoefliger

星期一，01 四月 2013

19131 次点击

0 条评论

本文介绍了 Joomla 3.1.0 新的标签功能的用法以及 Joomla! 开发者可用的新工具。

内容

介绍
标签的基本用法（标准字段模式）
字段模式
允许/禁止自定义标签
开发者额外工具
1. AJAX 选择
2. 编写自己的标签字段
工作正在进行中

1. 介绍

你可能已经听说，Joomla 3.1.0 带来了一个新的标签系统。此系统包含以下功能或特性

多语言。
标签的嵌套结构。
集成在 Joomla! 核心（这是 Joomla! 核心中的第一次统一内容模型的实现！）。
可选的标签字段模式（AJAX 或嵌套）。
标签可以“即时”创建。
简单集成到扩展中。

这个功能我个人已经缺失了几年。我一直 wonder why Joomla! 虽然知道内容，但无法通过标签来标记它。

我对这个功能的微小贡献是“AJAX 标签字段”。从另一个相关上下文中开发标签开始，我的要求是

使用 ENTER 键或逗号键插入自己的标签。
使用 chosen jQuery 插件作为标签字段的基础，就像它已经在 Joomla! 核心中集成一样。
无需直接编辑插件或其他核心组件，因此始终可以进行无缝升级（除了翻译）。

本文介绍了新的标签字段以及添加到 Joomla! 3.1.0 的所有新库和开发者工具。

2. 标签的基本用法（标准字段模式）

大多数扩展将使用标准字段模式，因此这里首先描述此方法 - 这将为那些不想阅读整篇文章的人节省阅读时间！

要在任何扩展中应用新的标签系统，只需扩展应用程序的 XML，添加以下内容

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

关键在于这里的 type="tag" 部分。就是这样。在这个位置，根本不需要考虑依赖关系。Joomla! 会处理其余部分。

在输出时，使用 Joomla!

加载 jQuery。
加载所需的插件。
加载 AJAX-chosen 插件。
加载所需的 JavaScript 代码，以便插入标签。

3. 字段模式

为了满足所有需求，我们决定整合所有贡献的代码段，并让用户决定如何使用标签字段。在 com_tag 选项中存在一些参数，允许在 AJAX 和 '嵌套' 之间配置 '字段模式'。

3.1. 自动模式

如果字段模式在标签字段定义中未设置，则标签的行为将由全局 com_tags 参数控制。这里默认是 AJAX 模式。

3.2. AJAX-chosen 模式

在键入的同时显示找到的标签。
在键入三个字符后，AJAX 搜索将在后台开始。
字段还允许通过按写-输入键或写-逗号键插入用户标签。（选项）
所有不存在的标签都将实时添加到字段或数据库中。

要强制执行 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. 允许/禁止自定义标签

有些情况下，虽然允许用户自行设置标签，但不允许添加自定义标签。标签字段包含一个 "custom" 属性，用于允许或禁止添加新标签。注意：目前嵌套模式不允许添加新标签，换句话说，此设置仅适用于 AJAX 模式。

如果未定义 "custom" 模式，则默认允许添加新标签。已添加 "允许" 模式以供未来使用。

可以强制字段允许添加新标签

<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. 为开发者提供的附加工具

为了进行 AJAX 搜索集成，我决定使用由 Ryan LeFevre 创建的 ajax-chosen 插件。我认为这将是一个很酷的附加组件，对于其他扩展甚至核心都适用。我需要做的只是修改和集成自己的标签及其值

在我努力保持所有插件不变（从而实现无缝升级）的过程中，我想将 AJAX-Chosen 库集成到不绑定到标签字段中。

本节解释了如何使用 AJAX-cosen 集成，以及如何构建自己的标签系统。

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 请求键

我还添加了一个选项，通过选择DOM对象来触发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的结果将按照指定返回。

对于标准结果，期望的格式是

[{"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标签系统为例。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