Piwik-Modul und -Plugin für MODx

von Thomas Jakobi am Montag, 22. September 2008 um 20:04 Uhr.

Auf einigen der von mir betreuten Seiten setze ich Piwik als Software für Webstatistiken ein. Mit dem folgendem MODx-Modul (Version 0.6.6a) und dem zugehörigen Plugin werden einige Widgets aus Piwik im MODx-Backend angezeigt und der passende Code für Piwik durch MODx am Ende der Seite eingefügt.

Basis ist eine funktionierende Installation von Piwik.

Zunächst lädt man sich die gepackten Dateien des Moduls herunter und kopiert sie in das Verzeichnis /assets/modules/piwikx der jeweiligen MODx-Installation.

Dann wird der Text aus der folgenden Datei in ein neues Plugin kopiert und dieses mit PiwikX benannt.

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;
}

Nun wird in der Modul-Verwaltung unter dem Namen PiwikX ein neues Modul angelegt und der Text aus der folgenden Datei eingefügt:

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;

Modulkonfiguration

Das Modul kann nun nach dem erneuten Laden des MODx-Managers aufgerufen werden. Da das Modul noch nicht konfiguriert ist, wird eine Übersichtsseite mit der Minimalkonfiguration und der vollständigen Konfiguration angezeigt. Eine dieser Konfigurationen muss im Reiter Konfiguration unter Modul Konfiguration eingefügt und an die jeweilige Piwik-Installation angepasst werden. Als Beispiel wird hier die Minimalkonfiguration aufgeführt: 

&piwikURL=URL Ihrer Piwik-Installation;text;https://ihre.piwik.installation
&piwikSiteId=Piwik Site-ID;text;1
&piwikUsername=Username für Piwik-Widgets;text;
&piwikPassword=md5-verschlüsseltes Passwort für Piwik-Widgets;text

Screenshot des Piwik ModulspiwikURL enthält die URL unter der die Piwik-Installation erreichbar ist.

piwikSiteId ist die ID der Website, die nach dem Anlegen einer neuen zu überwachenden Website (Admin Settings -> Webseiten) in Piwik angezeigt wird.

piwikUsername ist der Benutzername eines neuen in Piwik angelegten Benutzers (Admin Settings -> Benutzer). Diesem Benutzer muss der Ansichts-Zugriff für die zu überwachende Website erlaubt werden. Der Benutzer darf nicht der Piwik-Super-User sein.

piwikPassword ist das md5-verschlüsselte Passwort dieses Benutzers.

piwikActionName enthält den Namen einer Template-Variablen. Der Inhalt dieser Template-Variable wird geparst d.h. es werden darin enthaltene Snippet-Aufrufe ausgeführt und Dokument- bzw. Template-Variablen ersetzt (Snippets müssen gecached '' und Template-Variablen wie im Seitentemplate aufgerufen werden '') und als Tracking-Titel an Piwik übergeben. Wenn diese Option nicht gesetzt ist, wird der kurze Seitentitel als Tracking-Titel benutzt.

piwikUserExclude und piwikGroupExclude können eine kommaseparierte Liste von Benutzernamen bzw. Webgruppen enthalten. Diese MODx-Benutzer/Webgruppen werden (sobald sie im Backend oder Frontend angemeldet sind) vom Piwik-Tracking ausgeschlossen.

Schließlich muss noch in der Modul-Konfiguration die Option gemeinsame Parameter aktiviert werden und unter Abhängigkeiten das PiwikX-Plugin per Plugin hinzufügen zu den Abhängigkeiten hinzu gefügt werden.

Widgets im Backend

Durch das Modul werden nun einige Widgets aus Piwik im MODx-Backend angezeigt. Welche Widgets im Backend dargestellt werden, kann in der Datei <sprache>.managerwidgets.php eingestellt werden.

Die Angaben unter moduleToWidgetize und actionToWidgetize in dieser Datei holt man sich, indem man sich in das Backend von Piwik einloggt und sich unter Widgets ein eigenes Widget zurechtklickt. Aus dem dabei ausgegebenen iframe-Code fügt man dann den Wert für moduleToWidgetize (im folgenden Beispiel VisitorInterest) unter moduleToWidgetize und den Wert für actionToWidgetize (im Beispiel: getNumberOfVisitsPerVisitDuration) unter actionToWidgetize ein.

Für Besuchsdauer sieht das dann so aus:

$piwikWidgets ['Dauer'] = array (
'position' => 'left',
'title' => 'Besuchsdauer im letzten Monat',
'height' => '100',
'module' => 'Widgetize',
'action' => 'iframe',
'columns' => 'nb_visits',
'moduleToWidgetize' => 'VisitorInterest',
'actionToWidgetize' => 'getNumberOfVisitsPerVisitDuration',
'period' => 'month', 
'date' => 'today' );

Dank an Mithrandir aus dem deutschen MODx-Forum für den Text zur Widget-Erstellung.

Der Parameter period kann u.a. auf year, month, week oder day eingestellt werden. Der Parameter date u.a. auf today und yesterday. Weitere mögliche Werte kann man der API-Referenz von Piwik entnehmen.

Konfiguration des Plugins

Zum Schluss muss in der Konfiguration des Plugins unter Importieren von gemeinsamen Parametern die Einstellung PiwikX gewählt werden (eine eigene Pluginkonfiguration muss nicht angelegt werden). Unter Systemereignisse des Plugins wird der Eintrag OnParseDocument aktiviert und das Plugin gespeichert. Nun wird der Piwik-Abschnitt vor dem abschließenden Body-Tag im generierten Quelltext ausgegeben. Da der admin vom Plugin in der Standardkonfiguration vom Tracken ausgeschlossen wird, muss man sich zur Kontrolle aus dem Backend ausloggen oder die Seite kurzfristig in einem anderen Browser (d.h. in einer neuen Session) anzeigen.

Der Piwik-Abschnitt ist in einem DIV mit der Klasse piwik eingeschlossen und kann mit der CSS-Angabe .piwik { display: none } ausgeblendet werden.

Viel Erfolg!

Die Artikelreihe zu den eForm Eventfunktionen umfasst mittlerweile folgende Texte: