You are here: start » plugin_interfaces

Plugin Interfaces

Since CMSimple_XH 1.5 new interfaces for plugins are available. This was done to make CMSimple even more flexible and easier to use.

  • Editors
  • File Browsers
  • Page Managers
  • Script Evaluation

Since CMSimple_XH 1.5.4 the following is available:

  • $bjs
  • XH_ADM
  • Utf8_XH
  • System Check
  • toc()

Editors

Since a long time it was possible to integrate another editor than the default one. The user had to install a file MYEDITOR.php to cmsimple/ and typically a folder MYEDITOR/ to the CMSimple root directory. If the editor was needed from the back-end, CMSimple checked if $cf['editor']['external'] was set, and included 'cmsimple/'.$cf['editor']['external'].'.php' accordingly. The rest was up to the included file.

This has changed since CMSimple_XH 1.5, so it's not possible anymore to use the former method of integrating an external editor. This might seem inconvenient at first, but rather we had in mind ease of use for the user, the integrator of the external editor and authors of plugins, who need an editor for their plugin too. The most basic change is, that editors are now proper CMSimple plugins, so they can be installed easily and the editor integrators can use all amenities of CMSimple plugins, e.g. Plugin Configuration and Language.

But how does it work?

The End-User

The end-user has to install the prefered editor plugin as usual (i.e. upload the plugin folder to plugins/). Then he has to configure editor_external to the name of the plugin. Then he might adjust his preferences in the plugin adminstration. Now the editor is ready to use for editing the CMSimple pages.

The Editor Integrator

Implementing the Editor Interface

The editor integrator has to write a CMSimple plugin. He has to provide a file init.php in the root folder of this plugin, that defines the following three functions (replace “myEditor” with the name of your editor).

void function include_myEditor()

This function has to write all necessary JS scripts to $hjs.

string function myEditor_replace(string $elementID, string $config = '')

This function has to return a JS script element that will replace the textarea with the id specified in $elementID with an instance of the editor. The function is free to interpret the $config parameter in any way it sees fit. So it's up to the editor integrator to document how this parameter can be used. Typically it could be a string in JSON format.

void function init_myEditor(array $elementClasses = array(),  mixed $initFile = FALSE)

This function is the workhorse of the editor integration. It has to write all necessary initialisations to $hjs, so that all textareas with a class given in $elementClasses will be replaced with editor instances. If $elementClasses is empty, it defaults to the class .xh-editor. The parameter $initFile refers to the editors initalisation file. It can be “full”, “medium”, “minimal”, or the path to an additionally supplied one. If $initFile is FALSE, the user's preferences that he specified in the back-end shall be used.

As these functions can be called several times from different plugins, the editor integrator is responsible, that any code that should be executed only once, will be executed only once. This will typically be the case for the JS written to $hjs in include_myEditor().

Guarding your Code

Any code that will be executed through the pluginloader (e.g. the global code in admin.php) has to avoid clashes with other installed editors, so it should be guarded by a check if the editor plugin is called in the plugin administration ($myEditor) resp. by checking $cf['editor']['external']=='myEditor'. OTOH no such guards should be implemented in init.php, as different editors might be used on the same page.

Using a File Browser

To be written …

The Plugin Author

The plugin author, who needs an editor for his plugin, has to call the required interface functions. If he has no special needs about which editor should be used, he should call the editor through the following three general interface functions:

void function include_editor()
string function editor_replace(string $elementID, string $config = '')
void function init_editor(array $elementClasses = array(),  
mixed $initFile = FALSE)

These functions (defined in cmsimple/functions.php) will dispatch to the special interface functions of the editor the user has configured as editor_external. In the simplest case it's enough to put a textarea with class .xh-editor to the (X)HTML output and call init_editor() without any parameter. If the plugin author wants to be sure, that only the minimal version of the editor is shown, he could call init_editor(null, 'minimal'). If he needs two separate editor on a single page, he could output two textareas with different classes (say .teaser-editor and .body-editor) and call init_editor('teaser-editor', 'minimal') and init_editor('body-editor', 'full').

If the plugin author has the need for a special editor, he should document, that the user is required to install this editor. After include_once() the editor's init.php he can call the special interface functions directly.

⇑ top

File Browsers

To be written …

⇑ top

Page Managers

It always was possible to write a page manager such as Menumanager or Pagemanager_XH as plugin, so the user is able to manage the pages of his website in the plugin's back-end. But since CMSimple_XH 1.5 it's possible for the user to call an installed page manager directly from the admin menu.

The direct call from the admin menu will set $f to 'xhpages', so the page manager is informed, that it should take the appropriate actions, e.g. write the initial structure of the site to $o.

To avoid clashes with other installed page managers the plugin has to check if $cf['pagemanager']['external'] is set to it's own name. If not, another pagemanager should take over the job, and the plugin should avoid further processing of the request.

⇑ top

Script Evalution

It's quite common for the user to include CMSimple scripting or the plugin call into his page content, to be able to insert the output of plugins for example. Since CMSimple 1.5 it's possible to use scripting in newsboxes as well. But it's even possible to evaluate scripting in any texts, even if they are stored outside of the content. To do so just call the following function

string function evaluate_scripting(string $text, bool $compat = TRUE)

Just give the text that possibly contains CMSimple scripting or plugin calls as parameter. The result will be the text with the scripting evaluated. If you set the optional parameter $compat to FALSE, even more than one CMSimple scripting will be evaluated.

This should usually be all you need, but if you need more fine tuning about which kind of scripting should be evaluated, you can call one of the following functions directly:

string function evaluate_cmsimple_scripting(string $text, bool $compat = TRUE)
string function evaluate_plugincall(string $text)

All three functions are defined in functions.php.

$bjs

In CMSimple_XH 1.5.4 the global variable $bjs was introduced. It serves a similar purpose as the well-known $hjs, but instead of writing its content to the <head>, the content of $bjs is written to the end of the <body> (just before the closing </body> tag). So now plugins can write suitable JS scripts to $bjs without the need to do initialization in the window.onload or document.ready event and without the browser having to stop processing the DOM. Another advantage: contrary to $hjs, $bjs can be written to from inside the <body> of the template.

If you want your plugin to stay compatible with older version of CMSimple_XH, you can require the user to add the output of $bjs in the template manually:

<?php echo $bjs;?>

(but please point out, that this line has to be removed when updating to CMSimple_XH 1.5.4 or later)

An alternative which is more user friendly (as it doesn't require the user to modify their template), is to use the following technique:

if (isset($bjs)) {
    $bjs .= '<script ... </script>';
} else {
    $hjs .= '<script ... </script>';
}

XH_ADM

CMSimple_XH 1.5.4 introduced the constant XH_ADM. In the long term this should become a replacement for $adm, which could be manipulated by malevolent plugins. The test for $adm still works, but if you want to prepare your plugin for the future, you might test for XH_ADM and add at the beginning of the code:

if (!defined('XH_ADM')) define('XH_ADM', $adm); 

Utf8_XH

Since CMSimple_XH 1.5.4 the plugin Utf8_XH is bundled with the core. This offers various UTF-8 aware alternatives to PHP string functions. The developer version is hosted on SourceForge and comes with extensive documention. For older versions the plugin can be installed separately. If you want to use it from your plugins, make sure to state the requirement for end-users (a runtime check might be best, e.g. by using the system check) and to require_once() all necessary files.

System Check

The system check implemented in CMSimple_XH 1.5.4 can be used by plugins too. How this can be done is explained in the CMSimple forum. If you want to use the system check, but stay compatible with former versions of CMSimple, you can conditionally define XH_systemCheck() in your plugin:

if (!function_exists('XH_systemCheck')) {
    function XH_systemCheck($data)
    {
        // copy the definition from cmsimple/functions.php
    }
} 

Furthermore you have to supply some CSS rules (see css/core.css) and some images have to be put to images/flags/.

toc()

Since CMSimple_XH 1.5.4 an optional $li parameter was added to toc(). This gives template designers some more flexibility for offering alternative navigation menus by adding a replacement for li(), and calling

<?php echo toc(null, null, my_li();?>

instead of

<?php echo toc();?>

⇑ top

 
You are here: start » plugin_interfaces
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
Valid XHTML 1.0 Valid CSS Driven by DokuWiki