Der Artikel beschreibt den Gebrauch der neuen Tag-Funktion in Joomla 3.1.0 und die neuen Tools, welche Joomla! Entwicklern zur Implementierung zur Verfügung stehen.

Inhalt

1. Einführung
2. Grundsätzliche Verwendung (Standard Field Modus) von Tags
3. Field Modus
   
   1. Automatischer Modus
   2. AJAX-chosen Modus
   3. Verschachtelter Modus
4. Erlauben/Verbieten benutzerdefinierter Tags
5. Zusätzlich Werkzeuge für Entwickler
   1. AJAX gewählt
   2. Eigene Tag Felder schreiben
6. Die Arbeiten sind noch im Gang

 1. Einführung

Wie ihr vielleicht bereits gehört habt, kommt Joomla! 3.1.0 mit einem neuen Tag-System. Dieses System beinhaltet folgende Funktionen, bzw. Features:

• Mehrsprachigkeit.
• Verschachtelte Strukturen von Tags.
• Integriert im Joomla! Kern (Dies ist die allererste Implementation des Unified Content Models im Joomla! Kern!).
• Wählbarer Tag Feld Modus (AJAX oder verschachtelt).
• Tags können "On the Fly" kreiert werden.
• Einfache Integration für Entwickler in Erweiterungen.

Diese Funktion habe ich persönlich seit Jahren in Joomla! vermisst. Ich habe mich immer gewundert, wiso Joomla! zwar Inhalt kennt, dessen Kennzeichnung mittels Tags aber nicht zulässt.

Mein kleiner Beitrag zu dieser Funktion war das "AJAX Tag Field". Ausgehend von einer Entwicklung von Tags in einem anderen Zusammenhang waren meine Anforderungen:

• Einfügen von eigenen Tags per ENTER oder der KOMMA Taste.
• Verwendet das ausgewähltehe jQuery plugin als Basis für das Tag Feld, genauso wie es bereits im Kern von Joomla! integriert ist.
• Kein direktes Editieren der Plugins oder etwelchen anderen Kern-Komponenten, sodass nahtloses Upgraden immer möglich bleibt (ausser für Übersetzungen).

Dieser Artikel beschreibt das neue Tag Feld, sowie alle neuen Libraries und Entwickler-Werkzeuge, die zu Joomla! 3.1.0 hinzugefügt worden sind.

 2. Grundsätzliche Verwendung (Standard Field Modus) von Tags

Die meisten Erweiterungen werden vom Standard Field Modus Gebrauch machen, deshalb wird diese Methode hier an erster Stelle beschrieben - dies spart Lesezeit ein für diejenigen, die nicht den ganzen Artikel lesen mögen!

Um das neue Tag-System in einer beliebigen Erweiterung anzuwenden, muss lediglich das XML der Applikation um folgendes erweitert werden:

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

 Der Schlüssel ist hier der type="tag" Teil. Das war's schon. Man muss sich an der Stelle überhaupt keine Gedanken machen über Abhängigkeiten. Joomla! erledigt den Rest.

Bei der Ausgabe wird Joomla!:

1. jQuery laden.
2. Das erforderliche Plugin ladenn.
3. Das AJAX-chosen Plugin laden.
4. Den erforderlichen JavaScript Code laden, um die Tags  einzufügen.

 3. Field Modus

Um allen Wünschen gerecht zu werden, haben wir beschlossen, alle beigetragenen Codesegmente zu integrieren und den Benutzer entscheiden zu lassen, wie das Tag - Feld verwendet werden soll. In den com_tag Optionen sind Parameter vorhanden, die eine Konfiguration des 'Field Mode' zwischen AJAX' und 'verschachtelt' zulassen.

 3.1. Automatischer Modus

Wenn der Feld Modus in der Tag Field Definition nicht gesetzt worden ist, wird das Verhalten der Tags vom globalen com_tags Parameter gesteuert. Vorgegeben ist hier der Modus AJAX.

 3.2. AJAX-chosen Modus

• Bereits während dem Tippen werden gefundene Tags angezeigt.
• Nach drei Zeichen beginnt die AJAX Suche im Hintergrund.
• Das Feld erlaubt ebenfalls ein Einfügen von Benutzer-Tags mittels Schreiben - Eingabetaste bzw. Schreiben - Komma-Taste. (Option)
• Alle nicht-existenten Tags werden ins Feld bzw. in die Datenbank 'On the Fly' hinzugefügt.

Um die AJAX Suche zu erzwingen, muss folgende Definition gemacht werden:

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

 3.3. Verschachtelter Modus

• Anzeige der Tags in einer hierarchischen Struktur, so wie z.B. die Darstellung von Kategorien in anderen Kernkomponenten. 
• Eigene Tag-Felder sind nicht erlaubt

Um das Feld zu zwingen, den verschachtelten Modus zu gebrauchen, muss folgende Definition gemacht werden:

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

 4. Erlauben/Verbieten benutzerdefinierter Tags

Es gibt Fälle, in denen man dem Benutzer zwar erlauben will, Tags selber zu setzen - nicht aber, selber eigene Tags hinzuzufügen. Das Tag-Feld enthält ein "custom" - Attribut zum Zweck, neue Tags zu erlauben bzw. zu verbieten. Bemerkung: Im Moment erlaubt der verschachtelte Modus nicht, neue Tags hinzuzufügen, mit anderen Worten, die Einstellung gilt ausschliesslich für den AJAX Modus.

Wenn der "custom" Modus nicht definiert wurde, sind neue Tags per Voreinstellung erlaubt. Der "erlauben" Modus wurde für zukünftige Verwendungen hinzugefügt.

Das Feld kann gezwungen werden, neue Tags zu erlauben:

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

Das Feld kann gezwungen werden, neue Tags zu verbieten:

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

Beispiele für "erlaubt" bzw. "verboten" können im Backend eingesehen werden, und zwar in allen "Core Content Backend Managers" (für "erlaubt") bzw. in "Tag Menu Items" (für "verboten").

 5. Zusätzliche Werkzeuge für Entwickler

Für die AJAX Such-Integration habe ich mich dazu entschlossen, das ajax-chosen plugin created by Ryan LeFevre zu verwenden. Ich dachte mir, das würde ein cooles Addon sein, auch für andere Extensions, oder sogar für den Kern. Alles, was ich ändern musste, war die Modifikation und Integration der eigenen Tags und ihrer Werte

In Meinem Bestreben, alle Plugins unmodifiziert zu lassen (und damit ein nahtloses Upgraden zu ermöglichen), wollte ich die AJAX-Chosen Library ohne Bindung an das Tag Feld integrieren.

Dieser Abschnitt erklärt, wie die AJAX-cosen Integration gebraucht wird, und wie ein eigenes Tag System aufgebaut werden kann.

 5.1. AJAX-chosen Modus

Eine neue 'ajaxchosen' Methode wurde hinzugefügt:

libraries/cms/html/formbehavior.php

Die Definition ist folgende:

/**
 * 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)
{
}

Die akzeptierten Optionen in JRegistry $options object sind die standard AJAX jQuery options, sowie einige spezifische ajax-chosen Optionen:

• minTermLength: minimale Anzahl Charakter beim Eintippen befor ein AJAX Call stattfindet
• afterTypeDelay: Anzahl ms befor ein AJAX call ausgelöst wird nach dem Tippenl
• jsonTermKey: die AJAX request Taste für die Suche

Ich habe auch eine Option hinzugefügt mit dem Selector des DOM Object um das AJAX-chosen Feld automatisch auszulösen, sobald das DOM geladen ist.
Beispiel: #js-myfield

Wir können als Call dieses Beispiel nehmen:

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);

Ganz einfach! Die AJAX - Ergebnisse üssen wie spezifiziert zurückgemeldet werden.

Für Standard Resultate ist das erwartete Format:

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

und für gruppierte Resultate:

[{
    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. Eigene Tag Felder schreiben

Nimmt man als Basis unsere Tag-Feld Definition, so ist es einfach, eigene Tag-Felder zu schreiben. Wir wollen zum Beispiel ein Tag-Feld in unserer eigenen Extension haben, aber wir möchten nicht die Daten aus den Kern-Tag-Tabellen laden.

Nehmen wir als Beispiel das K2 Tag System. K2 braucht sein eigenes Tag-System mit dem Suchparameter  "q".

Der Tag Field Helper würde zu:

/**
 * 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);
			"
		);
	}
}

Natürlich würde K2 die Tags im erwarteten Format zurückgeben.

In unserer Feld Definition fügen wir einen Call  zur getInput Methode zum Helper ein:

// 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());

Man kann die volle Tag Feld Definition einsehen in:

libraries/cms/form/field/tag.php

6. Die Arbeiten sind noch im Gang

Das heutige Tag-Feld kann und soll noch verbessert werden. Die gegenwärtigen Implementierung tut nur so, wie wenn alle Erfordernisse abgedeckt wären - das allerdings auf einer soliden Basis.

Vorschläge und Beiträge sind willkommen. Hier ist eine kleine Liste über das, was ihr für uns alle tun könnt:

• Verbessern der Wiederverwendbarkeit der ajaxfield Funktion (Entgegennahme der 'chosenAjaxSettings' als Parameter).
• Tags anzeigen als 'list view' in Kern
• Möglichkeit, Tags direkt in 'list views' of the core content hinzuzufügen
• Fixen eines Bugs verbunden mit ENTER-tasten Event Override, was dazu führt, dass Custom Tags hinzugefügt werden anstelle von Hervorhebungen von Tags, wenn mit den Pfeiltasten navigiert wird.
• Hinzufügen von verschachtelten Tags 'On the Fly'. Du tippst "motor/rad/ducati" und der ganze Tag wird hinzugefügt.

Dies ist eine Übersetzung des Artikels von Roberto Segura  im Joomla Magazine April 2013.