Fa_XH – User Manual

Fa_XH provides Font Awesome for CMSimple_XH templates, plugins and content. The plugin has been created for similar reasons as the jQuery4CMSimple plugin, namely to avoid clashes when Font Awesome is used by multiple components. For instance, a template may include a certain Font Awesome version, but a plugin another one. If all components rely on Fa_XH, all will use the same version.

Furthermore Fa_XH delivers editor plugins to ease the use of Font Awesome icons in the content, if this is desired. Currently, only TinyMCE 4 and CKEditor are supported.

Important Notice

Fa_XH couldn't be tested so far in various environments. It is a so called release candidate. Use with caution!

Requirements

Fa_XH is a plugin for CMSimple_XH ≥ 1.6.3. It requires PHP ≥ 5.3.0.

Installation

The installation is done as with many other CMSimple_XH plugins. See the CMSimple_XH wiki for further details.

  1. Backup the data on your server.
  2. Unzip the distribution on your computer.
  3. Upload the whole directory fa/ to your server into CMSimple_XH's plugins directory.
  4. Set write permissions for the subdirectories config/, css/ and languages/.

Settings

The plugin's configuration is done as with many other CMSimple_XH plugins in the website's back-end. Select PluginsFa.

You can change the default settings of Fa_XH under Config. Hints for the options will be displayed when hovering over the help icon with your mouse.

Localization is done under Language. You can translate the character strings to your own language if there is no appropriate language file available, or customize them according to your needs.

The look of Fa_XH can be customized under Stylesheet.

Usage

End Users

If you want to use Font Awesome icons in the content, simply enable the configuration option RequireAuto. Basically, this is sufficient, but with regard to WYSIWYG editors you may have to make Font Awesome available to their <iframe>s.

TinyMCE 4

For TinyMCE 4 which is the default editor of CMSimple_XH 1.7, you'll want to install the fontawesome plugin, so:

  • Copy plugins/fa/editors/tinymce4/init_fontawesome.js into plugins/tinymce4/inits/.
  • Edit the copied init_fontawesome.js and replace all occurances of %CMSIMPLE_ROOT% with the absolute path of the CMSimple_XH installation folder. If you have installed CMSimple_XH directly in the web root, use / (a single slash); if you have installed it in a subfolder named sub, use /sub/.
  • Configure TinyMCE 4 to use the fontawesome init.

After these preparation steps, you find a new toolbar button named Font Awesome which opens a dialog where you can select and insert the desired Font Awesome icon.

The fontawesome plugin for TinyMCE 4 supports only icons marked up as <span>. Icons inserted in the HTML source code view with the more common <i> will be removed!

CKEditor

You need at least CKEditor 2.2 to use the fontawesome plugin, in which case CKEditor loads the plugin automatically.

Use the toolbar button Insert Font Awesome to select, manipulate and insert the desired Font Awesome icon. Double-click an already inserted icon to edit it.

The fontawesome plugin for CKEditor supports only icons marked up as <span>. Icons inserted in the HTML source code view with the more common <i> will be removed!

Template Designers

If a template wants to use Font Awesome, you should document that Fa_XH has to be installed, and you have to require Font Awesome early in the template (that is before <?php echo head()?>):

<?php fa_require()?>

If you want to cater to users who don't read the documentation, you can check whether the function is available, and emit an error message otherwise:

<?php
if (function_exists('fa_require')) {
    fa_require();
} else {
    die('This template requires the Fa_XH plugin. See the documentation for details.');
}
?>

Plugin Developers

If a plugins wants to use Font Awesome, you should document that Fa_XH has to be installed, and you have to require Font Awesome before you're going to actually use it. Simply calling fa_require() is not guaranteed to work when called from a plugin, as the function may not have been defined, so you have to execute the RequireCommand directly:

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

If your plugin requires PHP 5.4.0 or higher anyway, you can shorten:

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

To check whether Fa_XH is installed:

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

Limitations

The TinyMCE 4 Font Awesome plugin requires a contempary browser; IE ≤ 8 is not supported.

License

Fa_XH is licensed under GPLv3.

© 2017 Christoph M. Becker

Credits

This plugin is powered by Font Awesome by Dave Gandy. Many thanks for making this great iconic font and CSS toolkit available under a GPL friendly license.

This plugin contains an adapted version of the TinyMCE-FontAwesome-Plugin by josh18. Thanks for publishing this TinyMCE plugin under MIT license.

This plugin contains an updated version of the Font Awesome plugin for CKEditor by Michael Janea. Thanks for publishing this CKEDitor plugin under GPL.

Fa_XH has been inspired by frase. Many thanks!

Many thanks to the community at the CMSimple_XH forum for tips, suggestions and testing. Especially, I like to thank lck and frase for early testing and feedback, manu for helping with the TinyMCE 4 plugin, and Holger for helping with the CKEditor plugin.

And last but not least many thanks to Peter Harteg, the father of CMSimple, and all developers of CMSimple_XH without whom this amazing CMS wouldn't exist.