Tutorial für Plugins

[m47h]

Hallo,

gibt es sowas wie eine Anleitung zum erstellen von Plugins? Ich würde gerne welche Programmieren aber ich habe keine Lust mir erstmal bestehende anzuschauen und dann nach meinem Gusto anzupassen.

Gruß
m47h

[laufhannes]

Hallo m47h,

bisher haben wir leider keine Tutorials. Ich versuche mich mal zumindest an den wichtigsten Eckpunkten. Wichtigster Tipp ist aber, eine vernünftige Entwicklungsumgebung mit Code Completion. Dank phpDoc kommt man damit gut zurecht. Ohne die müsste auch ich immer ewig nachschauen, welche Methoden ich gerade nutzen kann.

Dazu noch eine wichtige Frage vorab: Nutzt du die aktuelle SVN-Version oder v1.5? Die SVN-Version hat bereits einige größere Änderungen für v2.0, von denen auch noch einige kommen werden. Wichtigste Änderung ist die neue Datenbank-Klasse DB (bzw PDOforRunalyze) statt Mysql. Ich beziehe mich im Folgenden jeweils auf den aktuellen Entwicklungsstand.

Ordner-/Datei-Struktur
Jedes Plugin liegt in einem eigenen Ordner (bis v1.5 bestanden noch einige ohne eigenen Ordner). Der Name richtet sich danach, ob es ein 'Tool'-, ein 'Panel'- oder ein 'Stat'-Plugin (also ein normales unterhalb des Kalenders) ist.

• /RunalyzePluginTool_NAME/class.RunalyzePluginTool_NAME.php
• /RunalyzePluginPanel_NAME/class.RunalyzePluginPanel_NAME.php
• /RunalyzePluginStat_NAME/class.RunalyzePluginStat_NAME.php

Der Name muss auch in der Klasse ganz oben eingetragen sein als $PLUGINKEY:

Code: Select all

$PLUGINKEY = 'RunalyzePluginPanel_NAME';

Notwendige Methoden

Code: Select all

abstract protected function initPlugin();
abstract protected function getDefaultConfigVars();
abstract protected function displayContent();

// Optional
protected function prepareForDisplay() {}

initPlugin()

Code: Select all

protected function initPlugin() {
	$this->type = Plugin::$PANEL; // oder $STAT oder $TOOL
	$this->name = 'Name ...';
	$this->description = 'Beschreibung ...';
}

Konfiguration
Jedes Plugin kann eigene Konfigurationseinstellungen haben. Das Handling dort bedarf für v2.0 noch ein Refactoring. Derzeit funktioniert es aber noch so:

Code: Select all

protected function getDefaultConfigVars() {
	$config = array();
	$config['option'] = array('type' => 'bool', 'var' => false, 'description' => '...');
	$config['value'] = array('type' => 'int', 'var' => 10, 'description' => '...');
	$config['array'] = array('type' => 'array', 'var' => array(1, 2, 3), 'description' => '...');

	return $config;
}

Auf die Werte kann innerhalb des Plugins mit $this->config['option']['var'] zugegriffen werden.

Ausgabe
prepareForDisplay() kann zum Initialisieren von eigenen Daten aus der Datenbank o.ä. verwendet werden und wird vor displayContent() aufgerufen. In der Methode kann alles Mögliche gemacht werden und die Ausgabe erfolgt direkt per echo.

Weiteres
Ich gehe jetzt noch nicht weiter auf die Übersetzung mit ein, die es für v2.0 geben wird. Das lässt sich problemlos später hinzufügen.

Panels können zusätzlich noch die Methode getRightSymbol() : string haben, um rechts oben in der Leiste Links anzuzeigen. Statistiken können über setSportsNavigation() oder setYearsNavigation() ein paar Standard-Links zur Auswahl nach Sportart/Jahr hinzufügen. Jedes Plugin hat die Eigenschaften $this->sportid, $this->year und $this->dat (Array). Links dafür können auch manuell über getInnerLink($name, $sportid, $year, $dat) erzeugt werden (wobei $dat dort dann z.B. "var=test&value=17" oder so sein könnte).

Außer der eigentlichen Plugin-Klasse können in dem Ordner natürlich beliebig viele andere Dateien liegen, z.B. extra Fenster, die aufgerufen werden können oder zusätzliche Klassen oder Diagramme.

Die phpDoc-Dokumentation gibt es unter http://phpdoc.runalyze.de/packages/Runalyze.html - das ist derzeit nicht ganz die aktuellste Revision, aber basiert schon auf den Änderungen für v2.0. Dort ist zum Beispiel die neue Datenbank-Klasse dokumentiert: http://phpdoc.runalyze.de/classes/PDOforRunalyze.html

Alles weitere hängt dann stark davon ab, was das Plugin können soll. Um zu wissen, welche Daten wo in der Datenbank sind, empfehle ich den Blick über den PhpMyAdmin. Um die Account-ID muss man sich dabei keine Gedanken machen, die wird durch die Datenbank-Klasse automatisch hinzugefügt.

Hier mal ein Beispiel-Plugin (Panel) zum Anfangen:

Code: Select all

<?php
/**
 * This file contains the class of the RunalyzePluginPanel "NAME".
 * @package Runalyze\Plugins\Panels
 */
$PLUGINKEY = 'RunalyzePluginPanel_NAME';
/**
 * Class: RunalyzePluginPanel_NAME
 * @author ...
 * @package Runalyze\Plugins\Panels
 */
class RunalyzePluginPanel_NAME extends PluginPanel {
	/**
	 * Initialize this plugin
	 * @see PluginPanel::initPlugin()
	 */
	protected function initPlugin() {
		$this->type = Plugin::$PANEL;
		$this->name = 'Name ...';
		$this->description = '...';
	}

	/**
	 * Set default config-variables
	 * @see PluginPanel::getDefaultConfigVars()
	 */
	protected function getDefaultConfigVars() {
		$config = array();
		$config['option'] = array('type' => 'bool', 'var' => false, 'description' => '...');
		$config['value'] = array('type' => 'int', 'var' => 10, 'description' => '...');
		$config['array'] = array('type' => 'array', 'var' => array(1, 2, 3), 'description' => '...');

		return $config;
	}

	/**
	 * Display the content
	 * @see PluginPanel::displayContent()
	 */
	protected function displayContent() {
		$Query = '
			SELECT
				`id`, `time`, `sportid`, `distance`, `s`
			FROM `'.PREFIX.'training`
			WHERE
				`time` >= '.(time() - 14*DAY_IN_S);
		$Trainings = DB::getInstance()->query($Query)->fetchAll();
	
		foreach ($Training as $Data) {
			$Sport = new Sport($Data['sportid']);

			echo date('d.m.Y', $Data['time']).': ';
			echo $Sport->name().' - ';
			echo Helper::Unknown(Running::Km($Data['distance']), 'ohne Distanz').', ';
			echo Time::toString($Data['s']).'<br>';
		}

		if (empty($Training))
			echo HTML::warning('Trainiere doch bitte endlich wieder!');
	}
}

Hilft das ein wenig für den Einstieg? Einzelne Klassen bzw. den Zugriff auf die Daten o.ä. erkläre ich gerne genauer, wenn offene Fragen in bestimmte Richtungen bestehen.

Viele Grüße
Hannes

[m47h]

Ja danke, das ist doch schon mal etwas.

Leider habe ich momentan zu wenig Zeit, wenn sich das ändert werde ich mich dran setzen.
Zu deiner Frage, ich benutzte momentan noch v1.4, da ich mir eigene Bilder für die Sportarten gemacht habe und diese ja in der v1.5 anders geladen werden.
Das ist übrigens auch ein Feature Request, dass man eigene Icons für die Sportarten [speziell für neu eingefügte Sportarten] hochladen kann.

Gruß
m47h

[brjbrj]

Hi !

Ich habs mal geschafft, mir eine Entwicklungsumgebung aufzusetzen; ich würde gerne das Plugin für die Körperdaten (zumindest VO2max, SpO2, HRV sowie einige weitere Felder) erweitern, das funktioniert was die Anzeige, das Speichern und die Verlaufsgrafik betrifft ja auch recht einfach; da ich aber dazu die Datenbankstruktur erweitern muss weiss ich derzeit nicht, wo die inkrementellen DB-Updates zu finden sind, damit diese Felder auch bei Bedarf erstellt werden.

Danke für Eure Hilfe, ich werde allerdings noch weitere benötigen, da ich - wie manche ja wissen - aus der DWH-Ecke komme, zwar programmieren kann, mit PHP aber erst anfange

lg
Robert

[mipapo]

Wir freuen uns natürlich über jeden, der mitarbeiten möchte, aber würde ich nicht empfehlen, an den Plugins konkret zu arbeiten.
Wir haben in dem Bereich einiges geplant und man müsste diskutieren, welche Felder wirklich nötig sind und was für Werte sie konkret beinhalten.
Deshalb würde ich empfehlen noch - leider wohl einige Monate - die Füße still zu halten.
Gerne darfst du bei dem zugehörigen Ticket auf Github deine Ideen genauer beschreiben.

Um deine Frage bzgl der Erweiterung/Änderung der Tabellene zu beantworten:
- Es muss eine neue "Migration" erstellt werden (https://github.com/Runalyze/Runalyze/tr ... Migrations)
- Es muss die inc/install/structure.sql angepasst werden
- Es muss die jeweilige Entity angepasst werden (https://github.com/Runalyze/Runalyze/tr ... dle/Entity)

Aktuell befinden wir uns noch in der Migrationsphase und da wäre alles, was man bei den Plugins macht doppelte Arbeit.
Zudem haben wir einige interne Pläne, die wir aber leider zeitlich nicht schaffen mal in ein Ticket zu gießen, da sie ziemlich detailiert sind

[brjbrj]

Hmm, also mal Danke für die Antwort, das Erweitern der DB wäre in diesem Fall natürlich sehr einfach.

Was mir bei den Feldern für Körperdaten vorschwebt ist de facto eine Kopie der Werte die ich bei TrainingsPeaks eingeben kann. Ich habe mir dort mal für ein Jahr einen Account genommen, ich bin aber - auch weils mal prinzipiell die Möglichkeit der Mitarbeit gibt - wirklich mehr von Runalyze überzeugt (auch das Layout spricht mich mehr an).

Nur die genauen Körperdaten fürs Tracken würden mir - abgesehen von Radspezifischen Auswertungen - fehlen. Nur sind die Auswertungen aus bereits gespeicherten Daten (also Max Power, Mean Power, Max 1S Power in der Statistik) im Prinzip auch jederzeit im nachhinein dazuprogrammierbar. Nur die Körperdaten muss man halt - mehr oder weniger - gleich erfassen, da diese ja sonst in keinem File gespeichert sind.

Doppelte Arbeit macht - wenn sich so viel bei den Plugins ändert - natürlich keinen Sinn, ich werde also mal stillhalten. Es wäre nur für einen PHP-Newbie natürlich recht leicht gesesen, da etwas zu erweitern.

Solltest Du Vorschläge haben wo man besser einsteigen könnte (bzw. auch hilfreich tätig sein sollte) bitte ich um Mitteilung.

Danke, Robert

[mipapo]

Vielleicht kannst du ja erstmal, um das strukturiert zu beginnen, sagen, welche Felder du gerne hinzufügen würdest.
Ich will dich ja nicht absolut davon abhalten.
Eine 1:1 Kopie von anderen Trainingsplattformen möchten wir halt auch nicht haben.

Hannes wird hier sicherlich auch nochmal antworten.

[brjbrj]

Hi Michael !

Also aus meiner (aber wirklich nur meiner) Sicht wären die 2 folgenden Werte die wichtigsten:

HRV, SpO2 (in %) sowie VO2max (in ml/min/kg)

super wäre zusätzlich auch die Schlafqualität (zusätzlich zur Schlafdauer) sowie die daraus resultierende Müdigkeit

Schlafqualität [Dropdown (fürchterlich, sehr schlecht, schlecht, normal, gut, ausgezeichnet)]
Müdigkeit [Dropdown (keine, sehr wenig, wenig, durchschnittlich, hoch, sehr hoch, extrem)]

Krank [als Checkbox und solche Tage im Kalender vielleicht rot anzeigen]

Das sind - wie gesagt - meiner Meinung nach die Felder, die mir am meisten fehlen; ich trage diese derzeit halt mal als Anmerkung zu den Körperdaten hinzu, nur z.B. bei HRV, SpO2 und VO2max wären natürlich eigenen Felder in der DB und damit die Möglichkeit der Anzeige in der Grafik der Körperdaten richtig toll.

lg
Robert

[mipapo]

Die Felder hören sich soweit erstmal gut an. Bei dem HRV Wert bin ich mir nicht ganz so sicher

Krank [als Checkbox und solche Tage im Kalender vielleicht rot anzeigen]]

Das wollen wir noch anders lösen, deshalb sollte das erstmal weg bleiben.

[laufhannes]

Ich hole mal etwas weiter aus - und das Fazit davon wird vermutlich sein: Aktuell halte ich es nicht für sinnvoll, dort große Änderungen anzustoßen.

Aktueller Zustand: Es können als "Body Values" folgende Werte maximal 1x täglich eingetragen werden:
- Gewicht (+ Analysewerte: Körperfett, Muskelanteil, Wasseranteil)
- Herzfrequenz (Ruhepuls, Maximalpuls)
- Schlafdauer
- Notizen

Als Auswertung gibt es die grafische Aufbereitung von Gewicht/Ruhepuls sowie der Analysewerte. Ansonsten gibt es lediglich die tabellarische Darstellung. Zusätzlich werden aber Ruhepuls und Maximalpuls bei vielen HF-bezogenen Berechnungen verwendet.

Probleme der derzeitigen Felder:
a) Der Maximalpuls ändert sich fast nie und bei den Berechnungen wird in der Regel der aktuelle Maximalpuls verwendet.
b) Der Ruhepuls unterliegt durchaus täglichen Schwankungen, spielt aber für die Anzeigen in %HRreserve eine wichtige Rolle.
c) Wenn ich die Schlafdauer aufzeichnen möchte, sollte ich dies täglich tun. 1x/Woche diese zu notieren bringt nichts. Wiegen halte ich persönlich aber eher 1x/Woche für sinnvoll (zumindest auf lange Dauer gesehen).

Probleme von noch nicht vorhandenen Feldern:
d) Sowohl Laufuhren (z.B. fenix3) als auch Fitnesstracker oder entsprechende Smartphone-Apps können das Schlafverhalten aufzeichnen, mit Schlafdauer, -qualität sowie zeitlichem Verlauf. Diese sind dann unabhängig vonirgendwelchen Gewichtsdaten.
e) Es gibt verschiedene Apps zur Kontrolle der Herzrequenzvariabilität. Diese sollte in der Regel morgens nach dem Aufstehen durchgeführt werden, kann aber auch wann anders geschehen. Außerdem gibt es die Möglichkeit, die HRV während der Aktivität aufzuzeichnen (wie es von uns bereits gespeichert wird).
f) Wir haben im Hinterkopf, einen allgemeinen "Körperstatus" aufzeichnen zu können. Dabei soll es die Möglichkeit geben, den eigenen Zustand (hinsichtlich Erkältung/Krankheit, Stimmung/Müdigkeit, Muskeln/Gelenke/etc.) auf einer einfachen Skala (z.B. 0 - 10) bewerten zu können.

Was bedeutet das nun ... Es wird das "Body Values"-Formular irgendwann nicht mehr in dieser Form geben. Stattdessen wird es in mehrere Formulare bzw. Importmöglichkeiten aufgeteilt. Aktuell ist es daher eher eine Ansammlung von irgendwelchen Werten, die man irgendwo auch benötigen könnte, aber von denen man nicht so recht weiß, wie man sie auswerten soll.

Zu deinen Vorschlägen
HRV: Die Herzfrequenzvariabilität ist nicht "ein Wert". Es gibt viele verschiedene Metriken, um die HRV zu bewerten. Und die verschiedenen Apps nutzen unterschiedliche Werte davon (falls sie überhaupt preisgeben, was ihr Wert genau bedeutet). Die HRV wird also zukünftig in der gesonderten Tabelle landen. Für ein neues Feld "HRV" wäre also einerseits fix festzulegen, welche Metrik dort festgelegt wird. Andererseits ist die Wahrscheinlichkeit groß, dass die Spalte bei einem späteren Update komplett gelöscht wird, ohne in die HRV-Tabelle übertragen zu werden.

SpO2 : Könnte man durchaus hinzufügen, ja. Auch wenn ich mir nicht sicher bin, ob der Wert zukünftig dort bleiben wird. Das ist ein weiterer Wert aus der Kategorie "Man kann ihn zu einem beliebigen Zeitpunkt messen und weiß nicht so recht was damit anzufangen".

VO2max: Wie bestimmst du den Wert denn? Der VO2max kann medizinisch im Rahmen einer Leistungsdiagnostik bestimmt werden. Alles andere ist grobe Schätzung. Die Schätzwerte der Garmin-Uhren werden importiert und können in der Kalenderansicht dargestellt werden. Dazu kommt, dass der VO2max nur zusammen mit der Laufökonomie etwas über die Leistungsfähigkeit aussagt. Deswegen schätzt Runalyze für jede Aktivität den VDOT, der - wenn man ihn exakt bestimmen könnte - deutlich mehr über den Leistungszustand aussagt.

Schlafqualität/Müdugikeit: Die Skala hierfür sollte gut überlegt sein, vor allem also auf den von mir angedeuteten "Körperstatus" bezogen. Und bevor man da etwas festlegt, hätte ich am liebsten entweder entsprechende wissenschaftliche Paper, die Begründungen für eine entsprechende Skala liefern, oder zumindest mit einem Sportwissenschaftler gesprochen. Eine solche Aufzeichnung bringt nichts, wenn wir später eine völlig andere Skala nutzen.

Krank: Wie Michael schon schreibt, wollen wir das anders lösen. Wir möchten irgendwann ganz allgemeine "Notizen" im Kalender erlauben, sodass man bestimmte Zeiträume entsprechend markieren kann (Urlaub, Dienstreise, Krankheit, Verletzung, ... was auch immer Einfluss auf die Trainingsmöglichkeiten hat).


Edit: Habe gerade nochmal folgenden Beitrag gefunden, der ja zum Thema passt: viewtopic.php?f=8&t=37&p=1866#p1866