By Chris Hoefliger on Monday, 01 April 2013
Category: April

Joomla! 3.1 Tags

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:

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:

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

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

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:

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:

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

Leave Comments