Fa_XH – Handbuch

Fa_XH stellt CMSimple_XH Templates, Plugins und dem Content Font Awesome zur Verfügung. Das Plugin wurde aus ähnlichen Gründen wie das jQuery4CMSimple Plugin entwickelt, nämlich um Konflikte zu vermeiden, wenn Font Awesome von mehreren Komponenten verwendet wird. Beispielsweise kann ein Template eine bestimmte Font Awesome Version enthalten, aber ein Plugin eine andere. Wenn alle Komponenten Fa_XH nutzen, dann verwenden alle die gleiche Version.

Weiterhin liefert Fa_XH Editor-Plugins aus, um die Verwendung von Font Awesome Icons im Content zu vereinfachen, wenn dies gewünscht wird. Zur Zeit werden nur TinyMCE 4 und CKEditor unterstützt.

Wichtiger Hinweis

Fa_XH konnte bisher nicht in diversen Umgebungen getestet werden. Es ist ein so genannter Release-Candidate. Vorsicht bei der Verwendung!

Voraussetzungen

Fa_XH ist ein Plugin für CMSimple_XH ≥ 1.6.3. Es benötigt PHP ≥ 5.3.0.

Installation

Die Installation erfolgt wie bei vielen anderen CMSimple_XH-Plugins auch. Im CMSimple_XH Wiki finden sie ausführliche Hinweise.

  1. Sichern Sie die Daten auf Ihrem Server.
  2. Entpacken Sie die ZIP-Datei auf Ihrem Computer.
  3. Laden Sie das gesamte Verzeichnis fa/ auf Ihren Server in das plugins/ Verzeichnis von CMSimple_XH hoch.
  4. Vergeben Sie Schreibrechte für die Unterverzeichnisse css/, config/ und languages/.

Einstellungen

Die Konfiguration des Plugins erfolgt wie bei vielen anderen CMSimple_XH-Plugins auch im Administrationsbereich der Homepage. Wählen Sie unter PluginsFa aus.

Sie können die Original-Einstellungen von Fa_XH in der Konfiguration ändern. Beim Überfahren der Hilfe-Icons mit der Maus werden Hinweise zu den Einstellungen angezeigt.

Die Lokalisierung wird unter Sprache vorgenommen. Sie können die Zeichenketten in Ihre eigene Sprache übersetzen, falls keine entsprechende Sprachdatei zur Verfügung steht, oder sie entsprechend Ihren Anforderungen anpassen.

Das Aussehen von Fa_XH kann unter Stylesheet angepasst werden.

Verwendung

End-Anwender

Wollen Sie Font Awesome Icons im Content verwenden, dann aktivieren Sie einfach die Konfigurationsoption RequireAuto. Prinzipiell genügt das bereits, aber in Hinblick auf WYSIWYG-Editoren kann es sein, dass Sie Font Awesome deren <iframe>s verfügbar machen müssen.

TinyMCE 4

Für TinyMCE 4, der der Standardeditor von CMSimple_XH 1.7 ist, möchten Sie vermutlich das fontawesome Plugin installieren. Also:

  • Kopieren Sie plugins/fa/editors/tinymce4/init_fontawesome.js nach plugins/tinymce4/inits/.
  • Bearbeiten Sie das kopierte init_fontawesome.js und ersetzen Sie alle Vorkommen von %CMSIMPLE_ROOT% mit dem absoluten Pfad des CMSimple_XH Installationsordners. Haben Sie CMSimple_XH direkt im Webroot installiert, verwenden Sie / (ein einziger Schrägstrich); haben Sie es in einem Unterordner namens sub installiert, verwenden Sie /sub/.
  • Konfigurieren Sie den TinyMCE 4, so dass er die fontawesome init nutzt.

Nach diesen Vorbereitungen finden Sie einen neuen Schalter in der Toolbar mit dem Namen Font Awesome, der einen Dialog öffnet, wo Sie das gewünschte Font Awesome Icon auswählen und einfügen können.

Das fontawesome Plugin für TinyMCE 4 unterstützt nur Icons, die als <span> ausgezeichnet sind. Icons, die in der HTML Quellcodeansicht mit dem üblicheren <i> eingefügt werden, werden entfernt!

CKEditor

Sie benötigen zumindest CKEditor 2.2 um das fontawesome Plugin verwenden zu können; dieses wird dann automatisch vom CKEditor geladen.

Verwenden Sie den Toolbar-Schalter Font Awesome einfügen, um das gewünschte Font Awesome Icon auszuwählen, zu manipulieren und einzufügen. Klicken Sie doppelt auf ein bereits eingefügtes Icon, um es zu bearbeiten.

Das fontawesome Plugin für CKEditor unterstützt nur Icons, die als <span> ausgezeichnet sind. Icons, die in der HTML Quellcodeansicht mit dem üblicheren <i> eingefügt werden, werden entfernt!

Template-Designer

Wenn ein Template Font Awesome verwendet, sollten Sie dokumentieren, dass Fa_XH installiert sein muss, und Sie müssen Font Awesome früh im Template ( das heißt vor <?php echo head()?>) erfodern.

<?php fa_require()?>

Wollen Sie es Anwendern, die die Dokumentation nicht lesen, einfacher machen, dann können Sie prüfen, ob diese Funktion verfügbar ist, und andernfalls eine Fehlermeldung ausgeben:

<?php
if (function_exists('fa_require')) {
    fa_require();
} else {
    die('Dieses Template benötigt das Fa_XH Plugin. In der Dokumentation finden Sie Details.');
}
?>

Plugin-Entwickler

Wenn ein Plugin Font Awesome verwendet, sollten Sie dokumentieren, dass Fa_XH installiert sein muss, und Sie müssen Font Awesome erfordern bevor Sie es tatsächlich verwenden. Es ist nicht garantiert, das der Aufruf von fa_require() funktioniert, wenn er von einem anderen Plugin aus erfolgt, da die Funktion unter Umständen noch nicht definiert wurde, so dass sie das RequireCommand direkt ausführen sollten:

<?php
$command = new Fa\RequireCommand;
$command->execute();
?>

Erfodert Ihr Plugin ohnehin PHP 5.4.0 oder höher, können Sie kürzer schreiben:

<?php (new Fa\RequireCommand)->execute()?>

Um zu prüfen, ob Fa_XH installiert ist:

<?php $fa_installed = class_exists('Fa\\RequireCommand')?>

Beschränkungen

Das Font Aweseome Plugin für TinyMCE 4 benötigt einen zeitgemäßen Browser; IE ≤ 8 wird nicht unterstützt.

Lizenz

Fa_XH kann unter Einhaltung der GPLv3 verwendet werden.

© 2017 Christoph M. Becker

Danksagung

Dieses Plugin ist ausgerüstet mit Font Awesome von Dave Gandy. Vielen Dank für die Veröffentlichung dieses großartigen Icon-Font- und CSS-Toolkits unter einer GPL freundlichen Lizenz.

Dieses Plugin enthält eine angepasste Version des TinyMCE-FontAwesome-Plugin von josh18. Danke für die Veröffentlichung dieses TinyMCE Plugins unter MIT Lizenz.

Dieses Plugin enthält eine aktualisierte Version des Font Awesome Plugin für CKEditor von Michael Janea. Danke für die Veröffentlichung unter GPL.

Fa_XH wurde von frase angeregt. Vielen Dank!

Vielen Dank an die Gemeinschaft im CMSimple_XH-Forum für Tipps, Anregungen und das Testen. Besonders möchte ich lck und frase für frühes Testen und Feedback danken, manu für Hilfe bei dem TinyMCE 4 Plugin, und Holger für Hilfe bei dem CKEditor Plugin.

Zu guter Letzt vielen Dank an Peter Harteg, den "Vater" von CMSimple, und allen Entwicklern von CMSimple_XH, ohne die dieses fantastische CMS nicht existieren würde.