Addons erstellen: Unterschied zwischen den Versionen

Aus sourceDESK Wiki
Wechseln zu: Navigation, Suche
(→‎Seiten im Kundenbereich)
(→‎Beispiel-Code)
 
(13 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 6: Zeile 6:
 
== Attribute ==
 
== Attribute ==
 
Jedes Addon benötigt ein String-Attribut ''public static $shortName'', das den Namen des Addon-Verzeichnisses enthält.
 
Jedes Addon benötigt ein String-Attribut ''public static $shortName'', das den Namen des Addon-Verzeichnisses enthält.
 +
 +
== Addon-Informationen ==
 +
Ihr Addon benötigt einen Konstruktor, der die aktuelle Sprache als Attribut nimmt. Der Konstruktor muss einige Infos zum Addon setzen, die in der Administration in der Addon-Verwaltung angezeigt werden:
 +
 +
<source lang="php">
 +
public function __construct($language) {
 +
    $this->name = self::$shortName;
 +
    parent::__construct();
 +
 +
    $this->info = Array(
 +
        'name' => "Modul-Name",
 +
        'version' => "1.0",
 +
        'company' => "sourceWAY.de",
 +
        'url' => "https://sourceway.de/",
 +
    );
 +
}
 +
</source>
  
 
== Einstellungen ==
 
== Einstellungen ==
Zeile 58: Zeile 75:
 
public function clientPages() {
 
public function clientPages() {
 
return Array("dsgvo" => "displayClientPage");
 
return Array("dsgvo" => "displayClientPage");
 +
}
 +
</source>
 +
 +
Die Methode könnte dann zum Beispiel so aussehen:
 +
 +
<source lang="php">
 +
public function displayClientPage() {
 +
    global $pars, $title, $tpl, $var, $lang;
 +
 +
    switch ($pars[0]) {
 +
        case 'av':
 +
            $title = $this->getLang("AV");
 +
            $tpl = __DIR__ . "/templates/av.tpl";
 +
            $var['av'] = false;
 +
            break;
 +
 +
        default:
 +
            $title = $lang['ERROR']['TITLE'];
 +
            $tpl = "error";
 +
            break;
 +
    }
 
}
 
}
 
</source>
 
</source>
  
 
== Seiten in der Administration ==
 
== Seiten in der Administration ==
−
...
+
Auch in der Administration kann ein Addon neue Seiten erstellen:
 +
 
 +
<source lang="php">
 +
public function adminPages() {
 +
return Array("oauth2config" => "admin");
 +
}
 +
</source>
 +
 
 +
Sie können sehr einfach Einträge in das "Addons"-Menü hinzufügen, hierzu ist die Angabe des Link-Namens und der Ziel-Seite erforderlich:
 +
 
 +
<source lang="php">
 +
public function adminMenu() {
 +
return Array("OAuth2" => "oauth2config");
 +
}
 +
</source>
  
 
== Sprachsystem ==
 
== Sprachsystem ==
−
...
+
Sie können eigene Sprachdateien für Ihr Addon nutzen. Dazu erstellen Sie im Addonverzeichnis einen Ordner ''language''. Darin nehmen Sie Sprachdateien für die gewünschten Sprache auf, zum Beispiel eine ''deutsch.php'':
 +
 
 +
<source lang="php">
 +
<?php
 +
$addonlang = Array();
 +
$addonlang['NAME'] = "DSGVO";
 +
$addonlang['AV'] = "Auftragsverarbeitungs-Vertrag";
 +
</source>
 +
 
 +
Die Initialisierung des Sprach-Systems muss anschließend im Konstruktor des Addons erfolgen:
 +
 
 +
<source lang="php">
 +
$this->language = $language;
 +
 
 +
if (!include (__DIR__ . "/language/$language.php")) {
 +
    throw new ModuleException();
 +
}
 +
 
 +
if (!is_array($addonlang) || !isset($addonlang["NAME"])) {
 +
    throw new ModuleException();
 +
}
 +
 
 +
$this->lang = $addonlang;
 +
</source>
 +
 
 +
Anschließend kann eine Methode verwendet werden, um Sprachvariablen zu bekommen. Bei Verwendung des Templatesystems müssen die Sprachvariablen extra übergeben werden.
 +
 
 +
<source lang="php">
 +
$this->getLang("NAME"); // Bestimmte Sprachvariable
 +
$this->getLang();      // Das komplette Sprach-Array
 +
 
 +
$var['l'] = $this->getLang();
 +
</source>
  
 
== Template-Dateien ==
 
== Template-Dateien ==
−
...
+
Sie können das Template-System sowohl für Seiten im Kundenbereich als auch in der Administration verwenden. Hierzu bietet es sich an, im Addon-Verzeichnis einen neuen Ordner ''templates'' zu erstellen.
 +
 
 +
Zur Verwendung des Template-Systems müssen Sie in der Methode für die jeweilige Seite die Variable ''$tpl'' auf den vollständigen Pfad zum gewünschten Template setzen. Beachten Sie hierbei bitte, dass Sie diese Variable erst am Anfang der Methode per <code>global $tpl;</code> freigeben müssen.
  
 
== Hooks ==
 
== Hooks ==
−
...
+
Mit Addons können Sie [[Hooks]] nutzen, um in Systemabläufe von sourceDESK einzugreifen und bei Events informiert zu werden.
  
 
== Widgets ==
 
== Widgets ==
−
...
+
Es ist möglich, mit Ihrem Addon [[Widgets#Widget erstellen|eigene Widgets zu erstellen]], die dann auf der Startseite der Administration angezeigt werden können.
  
 
== Beispiel-Code ==
 
== Beispiel-Code ==
−
...
+
<source lang="php">
 +
<?php
 +
// Addon for monitoring log
 +
 
 +
class LogMonitor extends Addon {
 +
public static $shortName = "log_monitor";
 +
 
 +
public function __construct($language) {
 +
$this->name = self::$shortName;
 +
parent::__construct();
 +
$this->info = Array(
 +
'name' => "Log-Monitor",
 +
'version' => "1.0",
 +
'company' => "sourceWAY.de",
 +
'url' => "https://sourceway.de/",
 +
);
 +
}
 +
 
 +
public function delete() {
 +
return $this->deleteDir(realpath(__DIR__));
 +
}
 +
 
 +
public function hooks() {
 +
return Array(
 +
Array("UserLogEntry", "log", 0),
 +
);
 +
}
 +
 
 +
public function log($params) {
 +
$user = $params['user'];
 +
$log = $params['log'];
 +
 
 +
if ($this->interestingUser($user) || $this->interestingText($log)) {
 +
Telegram::sendMessage($this->buildMsg($user, $log));
 +
}
 +
 
 +
}
 +
 
 +
private function buildMsg($user, $log) {
 +
global $raw_cfg;
 +
if (!($user instanceof User)) {
 +
return false;
 +
}
 +
 
 +
return '<a href="' . $raw_cfg['PAGEURL'] . 'admin/?p=customers&edit=' . $user->get()['ID'] . '">' . htmlentities($user->get()['name']) . '</a>: ' . htmlentities($log);
 +
}
 +
 
 +
private function interestingUser($user) {
 +
if (!($user instanceof User)) {
 +
return false;
 +
}
 +
 
 +
$ex = explode(",", $this->options["user"]);
 +
foreach ($ex as &$v) {
 +
$v = intval(trim($v));
 +
}
 +
 
 +
return in_array($user->get()["ID"], $ex);
 +
}
 +
 
 +
private function interestingText($log) {
 +
$log = trim($log);
 +
 
 +
$ex = explode(",", $this->options["text"]);
 +
foreach ($ex as $v) {
 +
if (strpos($log, trim($v)) !== false && !empty(trim($v))) {
 +
return true;
 +
}
 +
}
 +
 
 +
return false;
 +
}
 +
 
 +
public function getSettings() {
 +
return Array(
 +
"user" => Array("placeholder" => "1,5,7,...", "label" => "Zu &uuml;berwachende Benutzer (mehrere mit Komma trennen)", "type" => "text"),
 +
"text" => Array("placeholder" => "Domain,...", "label" => "Zu &uuml;berwachender Text (mehrere mit Komma trennen)", "type" => "text"),
 +
);
 +
}
 +
}
 +
</source>

Aktuelle Version vom 10. Oktober 2018, 09:43 Uhr

Sie können die Funktionalität von sourceDESK mit Addons erweitern. Diese können Seiten in Kundenbereich sowie Administration erstellen und an verschiedenen Stellen in das System eingreifen.

Dateistruktur

Ein Addon bekommt einen Ordner in modules/addons. Innerhalb dieses Ordners muss eine gleichnamige PHP-Datei mit der Endung .php angelegt werden, die eine Klasse definiert, welche von der Klasse Addon erbt.

Attribute

Jedes Addon benötigt ein String-Attribut public static $shortName, das den Namen des Addon-Verzeichnisses enthält.

Addon-Informationen

Ihr Addon benötigt einen Konstruktor, der die aktuelle Sprache als Attribut nimmt. Der Konstruktor muss einige Infos zum Addon setzen, die in der Administration in der Addon-Verwaltung angezeigt werden: 

public function __construct($language) {
    $this->name = self::$shortName;
    parent::__construct();
 
    $this->info = Array(
        'name' => "Modul-Name",
        'version' => "1.0",
        'company' => "sourceWAY.de",
        'url' => "https://sourceway.de/",
    );
}

Einstellungen

Sie können über die Methode getSettings() definieren, welche Einstellungen der Administrator für das Modul durchführen können soll. Ein Beispiel: 

public function getSettings() {
	return Array(
		"show_warning" => Array("default" => "0", "label" => $this->getLang("SHOWW"), "type" => "checkbox"),
		"exclude_ips" => Array("default" => "", "label" => $this->getLang("INTERNALN"), "type" => "text", "placeholder" => $this->getLang("INTERNALNP")),
	);
}

Auf die definierten Einstellungen können Sie innerhalb der Addon-Klasse bspw. mit dem Aufruf $this->getOption("show_warning") zugreifen.

System-Routinen

Sie können die System-Routinen für die Aktivierung und Deaktivierung eines Addons erweitern. Beispielsweise können Sie eine Tabellen-Spalte hinzufügen und entfernen: 

public function activate() {
	global $CFG, $db;
	parent::activate();
 
	$db->query("ALTER TABLE `" . $CFG['DB']['PREFIX'] . "clients` ADD `dsgvo_av` INT(11) NOT NULL DEFAULT '0';");
}
 
public function deactivate() {
	global $CFG, $db;
	parent::deactivate();
 
	$db->query("ALTER TABLE `" . $CFG['DB']['PREFIX'] . "clients` REMOVE `dsgvo_av`;");
}

Wichtig ist der Aufruf der original De-/aktivierungsfunktion.

Ferner müssen Sie eine Methode definieren, wenn Sie das Löschen des Moduls aus der Administration ermöglichen möchten. Standardmäßig bietet sich folgende Methode an: 

public function delete() {
	return $this->deleteDir(realpath(__DIR__));
}

Natürlich können Sie die Löschfunktion um beliebige Routinen erweitern. Die Löschung eines Addons ist nur im deaktivierten Zustand möglich, sodass Sie sich nicht um das Aufräumen der Datenbank kümmern müssen, wenn Sie dies bereits bei der Deaktivierung machen.

Seiten im Kundenbereich

Ihr Addon kann neue Seiten im Kundenbereich erstellen. Hierzu müssen die zu erstellenden Seite von der Methode clientPages() zurückgegeben werden. Hier muss auch definiert werden, welche Methode einen Aufruf behandeln soll: 

public function clientPages() {
	return Array("dsgvo" => "displayClientPage");
}

Die Methode könnte dann zum Beispiel so aussehen: 

public function displayClientPage() {
    global $pars, $title, $tpl, $var, $lang;
 
    switch ($pars[0]) {
        case 'av':
            $title = $this->getLang("AV");
            $tpl = __DIR__ . "/templates/av.tpl";
            $var['av'] = false;
            break;
 
        default:
            $title = $lang['ERROR']['TITLE'];
            $tpl = "error";
            break;
    }
}

Seiten in der Administration

Auch in der Administration kann ein Addon neue Seiten erstellen: 

public function adminPages() {
	return Array("oauth2config" => "admin");
}

Sie können sehr einfach Einträge in das "Addons"-Menü hinzufügen, hierzu ist die Angabe des Link-Namens und der Ziel-Seite erforderlich: 

public function adminMenu() {
	return Array("OAuth2" => "oauth2config");
}

Sprachsystem

Sie können eigene Sprachdateien für Ihr Addon nutzen. Dazu erstellen Sie im Addonverzeichnis einen Ordner language. Darin nehmen Sie Sprachdateien für die gewünschten Sprache auf, zum Beispiel eine deutsch.php: 

<?php
$addonlang = Array();
$addonlang['NAME'] = "DSGVO";
$addonlang['AV'] = "Auftragsverarbeitungs-Vertrag";

Die Initialisierung des Sprach-Systems muss anschließend im Konstruktor des Addons erfolgen: 

$this->language = $language;
 
if (!include (__DIR__ . "/language/$language.php")) {
    throw new ModuleException();
}
 
if (!is_array($addonlang) || !isset($addonlang["NAME"])) {
    throw new ModuleException();
}
 
$this->lang = $addonlang;

Anschließend kann eine Methode verwendet werden, um Sprachvariablen zu bekommen. Bei Verwendung des Templatesystems müssen die Sprachvariablen extra übergeben werden. 

$this->getLang("NAME"); // Bestimmte Sprachvariable
$this->getLang();       // Das komplette Sprach-Array
 
$var['l'] = $this->getLang();

Template-Dateien

Sie können das Template-System sowohl für Seiten im Kundenbereich als auch in der Administration verwenden. Hierzu bietet es sich an, im Addon-Verzeichnis einen neuen Ordner templates zu erstellen.

Zur Verwendung des Template-Systems müssen Sie in der Methode für die jeweilige Seite die Variable $tpl auf den vollständigen Pfad zum gewünschten Template setzen. Beachten Sie hierbei bitte, dass Sie diese Variable erst am Anfang der Methode per global $tpl; freigeben müssen.

Hooks

Mit Addons können Sie Hooks nutzen, um in Systemabläufe von sourceDESK einzugreifen und bei Events informiert zu werden.

Widgets

Es ist möglich, mit Ihrem Addon eigene Widgets zu erstellen, die dann auf der Startseite der Administration angezeigt werden können.

Beispiel-Code

<?php
// Addon for monitoring log
 
class LogMonitor extends Addon {
	public static $shortName = "log_monitor";
 
	public function __construct($language) {
		$this->name = self::$shortName;
		parent::__construct();
		$this->info = Array(
			'name' => "Log-Monitor",
			'version' => "1.0",
			'company' => "sourceWAY.de",
			'url' => "https://sourceway.de/",
		);
	}
 
	public function delete() {
		return $this->deleteDir(realpath(__DIR__));
	}
 
	public function hooks() {
		return Array(
			Array("UserLogEntry", "log", 0),
		);
	}
 
	public function log($params) {
		$user = $params['user'];
		$log = $params['log'];
 
		if ($this->interestingUser($user) || $this->interestingText($log)) {
			Telegram::sendMessage($this->buildMsg($user, $log));
		}
 
	}
 
	private function buildMsg($user, $log) {
		global $raw_cfg;
		if (!($user instanceof User)) {
			return false;
		}
 
		return '<a href="' . $raw_cfg['PAGEURL'] . 'admin/?p=customers&edit=' . $user->get()['ID'] . '">' . htmlentities($user->get()['name']) . '</a>: ' . htmlentities($log);
	}
 
	private function interestingUser($user) {
		if (!($user instanceof User)) {
			return false;
		}
 
		$ex = explode(",", $this->options["user"]);
		foreach ($ex as &$v) {
			$v = intval(trim($v));
		}
 
		return in_array($user->get()["ID"], $ex);
	}
 
	private function interestingText($log) {
		$log = trim($log);
 
		$ex = explode(",", $this->options["text"]);
		foreach ($ex as $v) {
			if (strpos($log, trim($v)) !== false && !empty(trim($v))) {
				return true;
			}
		}
 
		return false;
	}
 
	public function getSettings() {
		return Array(
			"user" => Array("placeholder" => "1,5,7,...", "label" => "Zu &uuml;berwachende Benutzer (mehrere mit Komma trennen)", "type" => "text"),
			"text" => Array("placeholder" => "Domain,...", "label" => "Zu &uuml;berwachender Text (mehrere mit Komma trennen)", "type" => "text"),
		);
	}
}
Von „https://wiki.sourceway.de/index.php?title=Addons_erstellen&oldid=627“