9.4. Textmakros

9.4.1. Einführung

Textmakros sind sozusagen die kleinen Geschwister der Textkonverter (Abschnitt 9.3, „Textkonverter“). Denn wie die Textkonverter sind sie für die Transformation von Text zuständig. Der Unterschied besteht aber darin, dass sie nicht eine komplett eigene Markup-Sprache zur Transformation ganzer Texte definieren, sondern mit einzelnen Befehlen eine einzige (kleine) Aufgabe erledigen sollen.

Wer beispielsweise einen Begriff mit einem Link zur Online-Enzyklopädie Wikipedia erklären will, kann normalerweise den Link nur in HTML oder mit der Markup-Sprache des jeweiligen Textkonverters (Markdown im Beispiel) auszeichnen:

[Toxoplasmose](http://de.wikipedia.org/wiki/Toxoplasmose)

Dies ist aber umständlicher als nötig, da die Links zur Wikipedia immer identisch aufgebaut sind und sich deshalb automatisch erstellen liessen. Hier kommen nun die Textmakros ins Spiel: Sie können diese Aufgabe übernehmen, ohne dass ein bestehender Textkonverter modifiziert respektive ergänzt werden muss. So lässt sich ein Textmakro erstellen, das beispielsweise aus

w:de{Toxoplasmose}

automatisch den richtigen Link erstellt, wodurch man nicht nur weniger tippen, sondern sich auch nicht den Link heraussuchen muss.

Dies funktioniert selbstverständlich nicht nur mit Wikipedia-Artikeln, sondern auch mit Telefonnummern oder ISBN für Bücher, die man beispielsweise mit seinem Amazon-Partnerprogramm verknüpfen kann. Auch lassen sich Badges von irgendwelchen Webdiensten integrieren, sofern sie sich vernünftig in in ein Textmakro verpacken lassen.

Weitere Anwendungsmöglichkeiten sind automatische Transformationen. Beispielsweise die Codierung von Entitäten oder die Entfernung von unerwünschten HTML-Tags.

9.4.2. Verwaltung

Abbildung 9.11. Übersicht über die vorhandenen Textmakros

Übersicht über die vorhandenen Textmakros

Die Übersicht der vorhandenen Textmakros in alphabetischer Reihenfolge bietet neben der Anzeige des Textmakro, Links zum Bearbeiten und Löschen, sowie den Link zum Neu anlegen eines Textmakro.

9.4.3. Anwendung der Textmakros

Textmakros werden wie der Textkonverter von Welcompose überall im Webinterface angeboten, wo sich Inhalte für die jeweiligen Seiten eingeben lassen. Sie können pro Seite, Blog Posting oder Box über eine Checkbox aktiviert werden.

Abbildung 9.12. Textmakros anwenden

Textmakros anwenden

Dies bedeutet, dass entweder alle Textmakros ausgeführt werden können oder gar keine.

Gesteuert werden kann einzig der Anwendungszeitpunkt der Textmakros, wobei das global bei der Aktivierung eines Textmakros geschieht (siehe Abschnitt 9.4.5, „Eigene Textmakros integrieren“).

Die Nutzung der Textmakros bei Blog-Kommentaren o.ä. ist nicht möglich.

9.4.4. Mitgelieferte Textmakros

Welcompose bringt augenblicklich vier Textmakros von Haus aus mit, die für die Bereitstellung von Welcompose-Funktionalität benötigt werden oder/und zusätzliche Funktionaltität bereit zu stellen.

[Warnung] Warnung

Diese mitgelieferten Textmakros dürfen nicht entfernt werden, da sonst die die Auflösung der Syntax sowie der Pfade in Ihren Seiten nicht mehr funktionieren.

9.4.4.1. Bundled Abbreviation Generator

Das Textmakro Bundled Abbreviation Generator kümmert sich um das Setzen der korrespondierenden abbr HTML-Tags und Links zu Glossarseiten. Es ist integrativer Bestandteil von Welcompose und kann daher auch nicht über das Backend gelöscht oder deaktiviert werden.

Es orientiert sich an der Syntax von Smarty-Funktionen, wie sie in Vorlagen verwendet werden:

{get_abbreviation arg1=value1 arg2=value2}

Während get_abbreviation den Namen des Textmakros repräsentiert, sind arg1 respektive arg2 Platzhalter für Argumente, die an den Abkürzung-Generator zur Erzeugung der richtigen Syntax übergeben werden. Die zwei einzig gültigen Argumente sind id und value. Die ID beschreibt die eindeutige Kennung der Abkürzung, mit dem Argument value wird bestimmt, welcher zur Verfügung stehende Feldinhalt der Abkürzung ausgelesen werden soll.

Zur Verfügung stehen: name, lang und long_form. Eine gültige Anweisung kann beispielsweise so aussehen:

{get_abbreviation id="3" value="name"}

oder auch:

{get_abbreviation id="3" value="long_form"}

Anstelle von {get_abbreviation ...} setzt das Textmakro die korrespondierenden Inhalt für die Abkürzung, beispielsweise:

<abbr title="MeineLangform">Meine Abkürzung</abbr>

oder auch:

<abbr title="MeineLangform" lang="de" xml:lang="de">
  <a href="#MeineAbkürzung" title="MeineLangform">Meine Abkürzung</a>
</abbr>
[Anmerkung] Anmerkung

Es in der Regel nicht nötig, selber die Tags für die Integration der Abkürzungen zu schreiben, da dies in Welcompose integrierte Funktionen für den Anwender tun. Lesen Sie hierzu auch Abschnitt 6.8, „Abkürzungen“ und Abschnitt 13.3.2, „Get Glossary“.

9.4.4.2. Bundled Embed Video Generator

Das Textmakro Bundled Embed Video Generator ermöglicht es mit wenigen Zeilen ein Video eines Video Sharing Service in eine Seite einzubinden. Die Art der Einbindung richtet sich nach den bereitgestellten Möglichkeiten der Anbieter.

Es orientiert sich an der Syntax von Smarty-Funktionen, wie sie in Vorlagen verwendet werden:

{embed_video arg1=value1 arg2=value2 arg3=value3 arg4=value4}

Das Textmarkro hat folgende Argument, deren Angabe zwingend erforderlich ist: service, vid, width und height. Der Parameter service ist gleich dem Namen des Anbieters.

Es sind aktuell folgende Anbieter implementiert:

  • Youtube (Parametername: youtube)

  • Vimeo (Parametername: vimeo)

  • DailyMotion (Parametername: dailymotion)

  • Clipfish (Parametername: clipfish)

  • Sevenload (Parametername: sevenload)

  • MyVideo (Parametername: myvideo)

  • Google (Parametername: google)

Der Parameter vid ist die Identifikationsnummer des eingebundenen Films, der vom jeweiligen Anbieter vergeben wird. Die Parameter width und height bestimmen die Anzeigefläche in ihrer Seite.

Somit würde ein gültige Eingabe wie beispielsweise wie folgt ausschauen:

{embed_video service="youtube" vid="4wr3AD8mZy0" width="500" height="408"}
[Tipp] Tipp

Um herauszufinden welche Werte sie konkret für Ihren Film angeben müssen, rufen Sie den Film auf der Seite des jeweiligen Anbieters auf. Dort stehen in der Regel Informationen zu ID des Films, Breite und Höhe des Films zur Verfügung. Oftmals ist bspw. die vid Teil des URL.

9.4.4.3. Bundled Media URL Generator

Das Textmakro Bundled Media URL Generator kümmert sich um das Setzen von Pfaden respektive URLs zu Media-Elementen wie Bildern. Es wird vom in Welcompose integrierten Media Manager verwendet und kann daher auch nicht über das Backend gelöscht oder deaktiviert werden.

Es orientiert sich an der Syntax von Smarty-Funktionen, wie sie in Vorlagen verwendet werden:

{get_media arg1=value1}

Es kennt nur ein einzelnes Argument: id. Diesem wird jeweils die ID des Bildes oder Films übergeben, das respektive der eingebunden werden soll:

{get_media id="3"}

Anstelle von {get_media ...} setzt das Textmakro den Pfad respektive URL zum Media-Element, beispielsweise:

/files/global_files/grafik.jpg

Allerdings ist es in der Regel nicht nötig, selber die Tags für die Integration der Bilder zu schreiben, da dies in Welcompose integrierte Funktionen für den Anwender tun.

9.4.4.4. Bundled URL Generator

Das Textmakro Bundled URL Generator dient zur einfachen Erzeugung von Links zwischen den einzelnen Welcompose-Seiten und wird beispielsweise von den Hilfsfunktionen zum Einfügen interner Hinweise verwendet. Es kann daher auch nicht über das Backend gelöscht oder deaktiviert werden.

Es bietet ein Interface zum URL-Generator, der auch schon innerhalb der Vorlagen zum Einsatz kommt und folgt daher dessen Syntax:

{get_url arg1=value1 arg2=value2}

Während get_url quasi der Name des Textmakros ist, sind arg1 respektive arg2 Platzhalter für Argumente, die an den URL-Generator zur Erzeugung der richtigen URLs übergeben werden. Eine gültige Anweisung kann beispielsweise so aussehen:

{get_url page_id="15" action=ArchiveMonth posting_year_added="2007" posting_month_added="6"}

Anstelle von {get_url ...} wird vom Textmakro der URL zu dem Archiv für den Monat Juni 2007 der Blog-Seite mit der ID 15 gesetzt, beispielsweise:

http://www.example.com/mein-blog/archiv/2007/06/

In der Regel ist es nicht nötig, selber die Tags für den Bundled Media URL Generator zu schreiben, da dies in Welcompose integrierte Funktionen für den Anwender tun.

9.4.5. Eigene Textmakros integrieren

Um eigene Textmakros in Welcompose zu integrieren, müssen zwei Aufgaben erledigt werden:

  1. Die Erstellung des Textmakros.

  2. Die Aktivierung des Textmakros in Welcompose.

9.4.5.1. Erstellung eines Textmakros

[Anmerkung] Anmerkung

Wer ein Textmakros integrieren möchte, sollte mit den Grundlagen objektorientierter Programmierung in PHP 5 vertraut sein.

Textmakros werden in Form von einfachen PHP-Funktionen realisiert, in deren Rahmen man prinzipiell machen kann, was man will. Als Beispiel soll die bereits erwähnte automatische Umwandlung von Links zur Wikipedia realisiert werden.

Die Textmakros werden im Verzeichnis core/plugins/textmacros/ hinterlegt, wobei pro Textmakro eine separate Datei benötigt wird. Die Benennung der Dateien muss einem bestimmten Schema erfolgen, damit die Textmakros von Welcompose gefunden werden. Und zwar müssen die Dateinamen mit wcom_plugin_textmacro_ beginnen, gefolgt vom eigentlichen Textmakro-Namen und der Dateiendung .php. Der Textmakro-Name darf nur kleine Buchstaben, Ziffern und Unterstriche beinhalten. Der Dateiname des Wikipedia-Macros könnte beispielsweise so aussehen: wcom_plugin_textmacro_wikipedia.php.

Der Dateiname dient gleichzeitig (abzüglich des Suffix .php) als Funktionsname, der für den Aufruf des Textmakros verwendet wird.

Die Textmakros erhalten als einziges Argument die Zeichenkette mit den Benutzereingaben, die sie nach der Ausführung retournieren müssen. Der funktionslose Prototyp einer Textmakro-Funktion sieht damit folgendermassen aus:

function wcom_plugin_textmacro_name ($input)
{
	return $input;
}

Welche Aktionen innerhalb des Textmakros ausgeführt werden, bleibt einem selbst überlassen. Meistens wird man wohl mit Hilfe von Regulären Ausdrücken die Eingaben manipulieren. In jedem Fall gilt es, darauf zu achten, dass die Textmakros nicht mit den Textkonvertern in Konflikt geraten, insbesondere wenn sie nach den Textkonvertern ausgeführt werden (mehr dazu in Abschnitt 9.4.5.2, „Textmakros registrieren“).

In dem Wikipedia-Beispiel-Textmakro wird eine ebensolche Text-Transformation mit Hilfe eines Regulären Ausdrucks realisiert. Und zwar sucht die Textmakro-Funtkion wcom_plugin_textmacro_wikipedia() nach allen nach dem Muster w:de{Begriff} (für die deutsche Wikipedia) respektive w:en{Begriff} (für die englische Wikipedia) ausgezeichneten Begriffen. Diese werden dann mit Hilfe der Callback-Funktion wcom_plugin_textmacro_wikipedia_callback() in die Links verwandelt und durch diese ersetzt.

function wcom_plugin_textmacro_wikipedia ($input)
{
	// input check
	if (!is_scalar($input)) {
		trigger_error("Input for parameter input is expected to be scalar", E_USER_ERROR);
	}

	// parse wikipedia tags and replace them with links to the online encyclopedia.
	return preg_replace_callback("=w:(en|de)\{(.*?)\}=",
		'wcom_plugin_textmacro_wikipedia_callback', $input);
}

function wcom_plugin_textmacro_wikipedia_callback ($args)
{
	// input check
	if (!is_array($args)) {
		trigger_error("Input for parameter args is expected to be an array", E_USER_ERROR);
	}

	// encode the article title into wikipedia's special format used in urls
	$article_url_title = urlencode(str_replace(' ', '_', $args[2]));

	// create wikipedia link
	// argument 1 holds the name of the localized wikipedia to use (either en or de)
	// argument 2 is the urlencoded version of the article title
	// argument 3 is the article title as supplied by the user
	return sprintf('<a href="http://%1$s.wikipedia.org/wiki/%2$s">%3$s</a>', $args[1],
		$article_url_title, $args[2]);
}

Sobald das Textmakro unter dem Namen wcom_plugin_textmacro_wikipedia.php im Verzeichnis core/plugins/textmacros/ abgelegt wurde, ist es einsatzbereit und muss nur noch in Welcompose registriert und damit aktiviert werden.

9.4.5.2. Textmakros registrieren

Um ein neu hinzugefügtes Textmakro nutzen zu können, muss es registriert werden. Dies geschieht im Administrationsbereich unter Settings im Unterpunkt Text Macros. Wenn Sie dort auf den Link Add new klicken, gelangen Sie zum Formular zum Anlegen eines neuen Textmakros.

Abbildung 9.13. Textmakro anlegen

Textmakro anlegen

Name

Der Name des Textmakros, der zur Identifizierung des Textmakros dient. Kann frei gewählt werden.

Internal name

Interner Name des Macros. Bei einer Textmakro-Funktion mit dem Namen wcom_plugin_textmacro_name() muss name eingegeben werden, bei wcom_plugin_textmacro_wikipedia() also wikipedia.

Type

Der Typ bestimmt den Zeitpunkt, wann das Textmakro im Verhältnis zu den Textkonvertern ausgeführt werden soll. Und zwar kann man wählen, ob das Textmakro vor (Startup macro, Pre text filter macro) oder nach (Post text filter macro, Shutdown Macro) dem Textkonveter ausgeführt werden soll. Ein Startup macro wird dabei vor einem Pre text filter macro ausgeführt, ein Shutdown macro nach einem Post text filter macro.

Sobald das Formular ausgefüllt und abgesendet wurde, ist das Textmakro aktiv und wird angewendet.