Piwik module/plugin for MODx

von Thomas Jakobi am Montag, 9. Februar 2009 um 14:23 Uhr.

On some customer websites I use Piwik as software for web analytics. The following MODx module (version 0.6.6a) displays a few Piwik widgets in the MODx backend and the corresponding plugin inserts the suitable code for Piwik at the end of the html code generated by MODx.

The base of the module/plugin is an separate (!) installation of Piwik. 

First download the packed files of the module and upload them to /assets/modules/piwikx.

Then you have to create a new plugin called PiwikX and paste the following plugin code into it.

piwikx.plugin
Speichern
/*
 * PiwikX simply integrates the <a href='http://www.piwik.org'>Piwik</a> statistic on your site.
 *
 * @package PiwikX
 * @subpackage modx_plugin
 * @link http://www.partout.info/piwik_modx.html
 *
 * @version 0.6.6a <17.05.2010>
 * @author Thomas Jakobi <Bitte Javascript aktivieren!>
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 */
 
/* MODx event
 OnParseDocument
 */
 
$piwikURL = (isset($piwikURL)) ? $piwikURL : '';
$piwikSiteId = (isset($piwikSiteId)) ? $piwikSiteId : 0;
 
if (!isset($modx))
    die();
 
// invoke module
$class_file = MODX_BASE_PATH.'assets/modules/piwikx/piwikx.class.php';
if (!file_exists($class_file))
    $modx->messageQuit(sprintf('Classfile "%s" not found. Did you upload the module files?', $class_file));
require_once ($class_file);
 
// MODx event handling
$e = &$modx->Event;
switch ($e->name) {
    case "OnParseDocument":
        $piwikx_lang = array();
        $PiwikX = new PiwikX($piwikURL, $piwikSiteId, $piwikx_lang);
 
		$PiwikX->piwikUsername = (isset($piwikUsername)) ? $piwikUsername : '';
		$PiwikX->piwikPassword = (isset($piwikPassword)) ? $piwikPassword : '';
		$PiwikX->piwikActionName = (isset($piwikActionName)) ? $piwikActionName : '';
		$PiwikX->piwikJsName = (isset($piwikJsName)) ? $piwikJsName : 'piwik.js';
		$PiwikX->piwikGroupTrack = (isset($piwikGroupTrack)) ? explode(',', $piwikGroupTrack) : array();
		$PiwikX->piwikGroupExclude = (isset($piwikGroupExclude)) ? explode(',', $piwikGroupExclude) : array();
		$PiwikX->piwikUserTrack = (isset($piwikUserTrack)) ? explode(',', $piwikUserTrack) : array();
		$PiwikX->piwikUserExclude = (isset($piwikUserExclude)) ? explode(',', $piwikUserExclude) : array();
 
		$includeChunk = $PiwikX->includeChunk();
		$modx->regClientHTMLBlock($includeChunk);
	break;
 
	default :
		return; // stop here - this is very important. 
	break;
}

Now you have to create a new module and paste the following module code into it.

piwikx.module
Speichern
/*
 * PiwikX simply integrates the <a href='http://www.piwik.org'>Piwik</a> statistic on your site.
 *
 * @package PiwikX
 * @subpackage modx_module
 * @link http://www.partout.info/piwik_modx.html
 *
 * @version 0.6.6a <17.05.2010>
 * @author Thomas Jakobi <Bitte Javascript aktivieren!>
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 */
 
if (!isset($modx))
    die();
 
$piwikURL = (isset($piwikURL)) ? $piwikURL : '';
$piwikSiteId = (isset($piwikSiteId)) ? $piwikSiteId : 0;
 
// manager language setting
$language = $modx->config['manager_language'];
 
// individual user language setting (if set)
$query = 'SELECT setting_name, setting_value FROM '.$modx->getFullTableName('user_settings').' WHERE setting_name=\'manager_language\' AND user='.$modx->getLoginUserID();
$records = $modx->db->query($query);
if ($modx->db->getRecordCount($records) > 0) {
    $record = $modx->db->getRow($records);
    $language = $record['setting_value'];
}
 
// load classfile
$class_file = MODX_BASE_PATH.'assets/modules/piwikx/piwikx.class.php';
if (!file_exists($class_file))
    $modx->messageQuit(sprintf('Classfile "%s" not found. Did you upload the module files?', $class_file));
require_once ($class_file);
 
// load localization
$piwikx_lang = array();
include_once MODX_BASE_PATH.'assets/modules/piwikx/lang/english.inc.php';
 
if ($language != 'english') {
    $lang_file = MODX_BASE_PATH.'assets/modules/piwikx/lang/'.$language.'.inc.php';
    if (file_exists($lang_file)) {
        include_once $lang_file;
    }
}
 
// invoke module
$PiwikX = new PiwikX($piwikURL, $piwikSiteId, $piwikx_lang);
 
$PiwikX->piwikUsername = (isset($piwikUsername)) ? $piwikUsername : '';
$PiwikX->piwikPassword = (isset($piwikPassword)) ? $piwikPassword : '';
$PiwikX->piwikTokenAuth = (isset($piwikTokenAuth)) ? $piwikTokenAuth : '';
$PiwikX->piwikActionName = (isset($piwikActionName)) ? $piwikActionName : '';
$PiwikX->piwikJsName = (isset($piwikJsName)) ? $piwikJsName : 'piwik.js';
$PiwikX->piwikGroupTrack = (isset($piwikGroupTrack)) ? explode(',', $piwikGroupTrack) : array();
$PiwikX->piwikGroupExclude = (isset($piwikGroupExclude)) ? explode(',', $piwikGroupExclude) : array();
$PiwikX->piwikUserTrack = (isset($piwikUserTrack)) ? explode(',', $piwikUserTrack) : array();
$PiwikX->piwikUserExclude = (isset($piwikUserExclude)) ? explode(',', $piwikUserExclude) : array();
echo $PiwikX->displayModule();
return;

Module configuration

The module can be called now after reloading the MODx manager. Since the module is not yet configured, a summary page with the minimal and the complete configuration will be displayed. One of these configurations must be inserted in the module configuration and the settings have to filled according to the corresponding Piwik installation. As an example the minimal configuration is shown here:

&piwikURL=URL to your Piwik installation;text;https://your.piwik.installation
&piwikSiteId=Piwik Site ID;text;1
&piwikUsername=Username to display the Piwik widgets;text;
&piwikPassword=md5 encrypted password to display the Piwik widgets;text;

Screenshot des Piwik ModulspiwikURL contains the url of the Piwik installation.

piwikSiteId contains the id of the website inside of piwik (Piwik -> Admin settings -> Sites).

piwikUsername contains the name of a new user inside of piwik (Piwik -> Admin settings -> Users). This user has to have viewing acces for the website to track. Caution: This user cannot be the piwik super user.

piwikPassword is the md5 encrypted password of this user (Piwik -> Admin settings -> Users).

piwikActionName contains the name of a template variable. The content of this variable will be parsed (contained snippet calls will be executed and document or template variables will be replaced – snippets have to be called cached und template variables should be called as in page templates ) and used as tracking title for Piwik. If this option is not set, the pagetitle will be used as tracking title.

piwikUserExclude and piwikGroupExclude could contain a comma-separated list of user names and/or web groups. These users and/or groups will be excluded from piwik tracking if they are logged into the MODx frontend or backend.

After that you have to enable parameter sharing in the module configuration and add the PiwikX plugin in the dependencies of the module.

Widgets in the backend

The module should display now a few Piwik widgets in the MODx backend. The configuration of these widgets could be set in the file <language>.managerwidgets.php – a small howto for modifications in this file is written in the german documentation.

Plugin configuration

Now you have to select PiwikX in import module shared parameters of the PiwikX plugin configuration and activate OnParseDocument as system event for the plugin. After saving the plugin the Piwik code will be inserted at the end of the html code generated by MODx. Since this code is enclosed in a DIV with the class piwik, it could be hidden by  .piwik { display: none } in the CSS file.

Die Artikelreihe zu den eForm Eventfunktionen umfasst mittlerweile folgende Texte: