You are here: start » plugin_tutorial_intro

Plugin Tutorial: Introduction

In the following we'll develop a plugin, that counts the visitors currently online, and displays this information.

We'll call the plugin Visitors_online. It's quite important to stick with the chosen name, as it's necessary to hard-code the name in different places.

So create a folder visitors_online/ in the plugins/ folder of your development installation of CMSimple_XH. Put the following code in a file index.php in the new folder, and save it as UTF-8 without BOM.

<?php
 
define('VISITORS_FILENAME', $pth['folder']['plugins'].'visitors_online/data/online.csv');
define('VISITORS_DURATION', 5*60);
define('VISITORS_TEXT', 'Visitors online');
 
 
function visitors_read() {
    $data = file(VISITORS_FILENAME);
    $res = array();
    foreach ($data as $line) {
	list($ip, $timestamp) = explode("\t", rtrim($line));
	$res[$ip] = $timestamp;
    }
    return $res;
}
 
 
function visitors_write($visits) {
    $o = '';
    foreach ($visits as $ip => $timestamp) {
	$o .= $ip."\t".$timestamp."\n";
    }
    $fh = fopen(VISITORS_FILENAME, 'w');
    fwrite($fh, $o);
    fclose($fh);
}
 
 
function visitors_is_online($visit) {
    return time() - $visit <= VISITORS_DURATION;
}
 
 
function visitors() {
    $visits = visitors_read();
    $visits = array_filter($visits, 'visitors_is_online');
    $visits[$_SERVER['REMOTE_ADDR']] = time();
    visitors_write($visits);
    return '<span id="visitors-online">'.VISITORS_TEXT.': '.count($visits).'</span>'."\n";
}
 
?>

Then you have to create an empty file visitors_online/data/online.csv.

Now find a nice place in your template where the counter should be shown, and insert the following call there:

<?php echo visitors()?>

Finally test it: navigate to the website with your browser. You should see “Visitors online: 1” (I assume you're testing on your local server, so you're probably the only visitor).

Remarks

Most of the code is pretty much self explaining and has not much to do with CMSimple_XH, but some remarks are in order:

  • Plugins are not executed as separate PHP scripts, but rather are include()d by the pluginloader and so have to share the global namespace with CMSimple_XH's core, the pluginloader, the template and other plugins. So you have to take care to avoid name clashes. This might be solved best by prefixing all global indentifiers with the plugin's name or a shortcut. Using a separate namespace for each plugin would be nice, but is generally no option, as namespaces were introduced in PHP 5.3, but CMSimple_XH is expected to run under PHP 4.3 onward.
  • It's good practice not to write output directly to the browser from plugins with echo or print(). In this case it wouldn't have been a problem, but it won't work, when the plugin is called by CMSimple scripting. So it's customary to return the (X)HTML output from the plugin's main function(s).
  • The path to online.csv is not hardcoded in the plugin, but instead it uses $pth['folder']['plugins']. The $pth array is initialized by CMSimple_XH's core in a way, that it contains relative paths that are correct, independent of wether the plugin was called from the main or a secondary language language (or subsite).

« Preface | Internationalization »

 
You are here: start » plugin_tutorial_intro
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