Metainformationen zur Seite

Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Nächste Überarbeitung		Vorhergehende Überarbeitung
en:entwickler:grundlagen_zur_erstellung_eines_plugins [2025/01/23 19:00] – angelegt Braveen:entwickler:grundlagen_zur_erstellung_eines_plugins [2025/01/23 19:36] (aktuell) – Completely translated page Brave
Zeile 1: Zeile 1:
-FIXME **Diese Seite wurde noch nicht vollständig übersetzt. Bitte helfen Sie bei der Übersetzung.**\\ //(diesen Absatz entfernen, wenn die Übersetzung abgeschlossen wurde)// 
- 
 ====== Basics for creating a plugin ====== ====== Basics for creating a plugin ======
  
 {{entwickler:1218019522.png}} {{entwickler:1218019522.png}}
  
-**If you understand how this code works, you can develop a LoxBerry plugin!+**If you understand how this code works, you can develop a LoxBerry plugin!**
  
 Developing LoxBerry plugins is not too difficult for anyone who has ever scripted or programmed anything. Conveniently, there is now the Internet where you can find examples or use them directly. Developing LoxBerry plugins is not too difficult for anyone who has ever scripted or programmed anything. Conveniently, there is now the Internet where you can find examples or use them directly.
  
-Some LoxBerry plugins, for example, have emerged from already existing scripts or programs from the Internet, which primarily required a web interface for the configuration of these scripts. +Some LoxBerry plugins, for example, have emerged from already existing scripts or programs from the Internet, which primarily required a web interface for the configuration of these scripts.
  
 If you are planning a plugin for the first time, break down the development into the following parts: If you are planning a plugin for the first time, break down the development into the following parts:
  
-  * The program that executes the actual function of your plugin. +  * The program that executes the actual function of your plugin.
   * A configuration file from which your program reads the parameters it needs.   * A configuration file from which your program reads the parameters it needs.
  
Zeile 20: Zeile 18:
   * A web interface to read and write the configuration file   * A web interface to read and write the configuration file
   * If necessary, a cronjob to execute your program at intervals   * If necessary, a cronjob to execute your program at intervals
 +
  
 ==== Step 0: Update your LoxBerry to the latest pre-release ==== ==== Step 0: Update your LoxBerry to the latest pre-release ====
Zeile 27: Zeile 26:
 ==== Step 1: Create plugin directory ==== ==== Step 1: Create plugin directory ====
  
-Start by downloading (not installing!) the sample plugin and unpacking it on your PC. It contains Perl or PHP code, but any language can be used for the implementation. Perl and PHP have the advantage that LoxBerry offers an SDK for this, which makes many tasks easier (e.g. creating the web interface or reading the LoxBerry configuration and creating log files).+Start by downloading (not installing!) the sample plugin and unpacking it on your PC. It contains Perl or PHP code, but any language can be used for the implementation. Perl and PHP have the advantage that LoxBerry offers an SDK for this, which makes many tasks easier (e.g. creating the web interface or reading the LoxBerry configuration and creating log files).  ==== Step 2: customize plugin.cfg ====
  
-==== Step 2: customize plugin.cfg ==== +In your copy of the sample plugin, adjust the name of the plugin, author, version number, etc.  By changing this data, it is now **your** plugin.
- +
-In your copy of the sample plugin, adjust the name of the plugin, author, version number, etc. +
- +
-By changing this data, it is now **your** plugin.+
  
 ==== Step 3: Install your plugin ==== ==== Step 3: Install your plugin ====
  
-Zip the directory and install it on the LoxBerry. Ignore any installation errors - these come from the sample data of the sample plugin and can be corrected later. +Zip the directory and install it on the LoxBerry. Ignore any installation errors - these come from the sample data of the sample plugin and can be corrected later.  You will then find your plugin in the plugin administration.  LoxBerry has created directories corresponding to the name of your plugin on the Raspberry.
- +
-You will then find your plugin in the plugin administration. +
- +
-LoxBerry has created directories corresponding to the name of your plugin on the Raspberry. +
- +
-^Folder                                                    ^Function                                                                                                                                 ^ +
-|/opt/loxberry/webfrontend/htmlauth/plugins///deinplugin///|Directory for your web interface (authentication required)                                                                          | +
-|/opt/loxberry/webfrontend/html/plugins///deinplugin///    |Directory for Websites without authentication                                                                                         | +
-|/opt/loxberry/templates/plugins///deinplugin///           |Especially when using Perl and HTML::Template, you store HTML templates here. The lang subdirectory contains the  Sprachdateien.| +
-|/opt/loxberry/config/plugins///deinplugin///              |Directory for your configuration files                                                                                              | +
-|/opt/loxberry/bin/plugins///deinplugin///                 |Directory for Executable files that should not be accessible from the web                                                        | +
-|/opt/loxberry/log/plugins///deinplugin///                 |Directory for your log files                                                                                                         | +
-|/opt/loxberry/data/plugins///deinplugin///                |Directory for any other data that your plugin requires or generates                                                           |+
  
 +^Folder                                                    ^Function                                                                                                                        ^
 +|/opt/loxberry/webfrontend/htmlauth/plugins///deinplugin///|Directory for your web interface (authentication required)                                                                      |
 +|/opt/loxberry/webfrontend/html/plugins///deinplugin///    |Directory for Websites without authentication                                                                                   |
 +|/opt/loxberry/templates/plugins///deinplugin///           |Especially when using Perl and HTML::Template, you store HTML templates here. The lang subdirectory contains the Language files.|
 +|/opt/loxberry/config/plugins///deinplugin///              |Directory for your configuration files                                                                                          |
 +|/opt/loxberry/bin/plugins///deinplugin///                 |Directory for Executable files that should not be accessible from the web                                                       |
 +|/opt/loxberry/log/plugins///deinplugin///                 |Directory for your log files                                                                                                    |
 +|/opt/loxberry/data/plugins///deinplugin///                |Directory for any other data that your plugin requires or generates                                                             |
  
 ==== Step 4: Implement function ==== ==== Step 4: Implement function ====
Zeile 57: Zeile 47:
 Decide whether the function of your plugin should be triggered time-controlled or via a web call. Decide whether the function of your plugin should be triggered time-controlled or via a web call.
  
-  * Time-controlled: Develop your program in your bin directory  +   * Time-controlled: Develop your program in your bin directory 
-  * Web call: Develop your program in your webfrontend/htmlauth directory +   * Web call: Develop your program in your webfrontend/htmlauth directory 
 + 
 Program your functionality and use a config file in your config directory for everything that should later be customizable by the user on the web. Program your functionality and use a config file in your config directory for everything that should later be customizable by the user on the web.
  
Zeile 68: Zeile 58:
 ==== Step 5: Implementing the web interface ==== ==== Step 5: Implementing the web interface ====
  
-When your functions are running, develop your web interface for them. +When your functions are running, develop your web interface for them.
  
 Use the Perl-Lib LoxBerry::Web or for PHP loxberry_web.php. **Look through the functions of the SDK** and use code from the sample plugin. Use the Perl-Lib LoxBerry::Web or for PHP loxberry_web.php. **Look through the functions of the SDK** and use code from the sample plugin.
Zeile 74: Zeile 64:
 Use readlanguage (Perl, PHP) to offer alternative languages for your plugin. Use readlanguage (Perl, PHP) to offer alternative languages for your plugin.
  
-==== Schritt 6: Installation anpassen ====+==== Step 6: Customize installation ==== 
 + 
 +If your things work reasonably well on the installed LoxBerry, update your plugin package:
  
-Wenn am installierten LoxBerry deine Sachen halbwegs funktionieren, aktualisiere dein Plugin-Paket:+  * Copy the new program files into the directory from which you initially created the ZIP with the modified plugin.cfg. 
 +  * If special steps are required during the installation or during the plugin update, update the install scripts in this directory (e.g. save the config during the update) 
 +  * If special Debian packages are required for your plugin, update the apt file in the apt folder and add the package names there.
  
-  * Kopiere die neuen Programmdateien in das Verzeichnis, wovon du anfangs das ZIP mit der geänderten plugin.cfg erstellt hast. +==== Step 7: Test and continue ====
-  * Wenn während der Installation, oder während des Plugin-Updates spezielle Schritte nötig sind, aktualisiere in diesem Verzeichnis die Install-Scripts (z.B. Sichern der Config während des Updates) +
-  * Wenn spezielle Debian-Pakete für dein Plugin nötig sind, aktualisiere im Ordner apt das apt-File und füge dort die Paketnamen ein.+
  
-==== Schritt 7: Testen und weitermachen ====+//Before you rezip and install your source folder, make sure that all files from the LoxBerry are really in your source on the PC - during the update, all folders on the LoxBerry are deleted in order to recreate them during the installation.//
  
-//Bevor zu deinen Quellordner neu zippst und installierst, stelle sicher, dass wirklich alle Dateien vom LoxBerry in deiner Quelle am PC sind - während des Updates werden alle Ordner am LoxBerry gelöscht, um diese bei der Installation wieder anzulegen.//+You can then test the installation. This usually reveals any errors in the installation scripts. You can then test everything in the same way as it behaves for other users.  
  
-Danach kannst du die Installation testen. Meist kommt man dabei auf etwaige Fehler in den Installationsscripten drauf. Du kannst danach alles so durchtesten, wie es sich dann auch bei anderen Benutzern verhält. +==== Step 8: Get help ====
  
-==== Schritt 8: Hilfe holen ====+Some things are unusual the first time, so don't despair but seek advice.
  
-Manche Sachen sind beim ersten Mal ungewöhnlich, deswegen nicht verzweifeln sondern Rat einholen.+All LoxBerry plugin developers regularly check the LoxForum in the developer area for LoxBerry: [[https://www.loxforum.com/forum/projektforen/loxberry/entwickler]]
  
-Alle LoxBerry-Plugin-Entwickler schauen regelmäßig im LoxForum in den Entwickler-Bereich für LoxBerry: https://www.loxforum.com/forum/projektforen/loxberry/entwickler+We also run a WhatsApp group for LoxBerry developers, where troubleshooting is much faster. Please join with [[https://loxwiki.atlassian.net/wiki/people/6166fb1fc5388b0069f9351f?ref=confluence|Christian Fenzl]] Contact us (incl. name and telephone number).
  
-Außerdem betreiben wir eine WhatsApp-Gruppe für LoxBerry-Entwickler, wo das Troubleshooting viel schneller geht. Bitte dafür mit [[https://loxwiki.atlassian.net/wiki/people/6166fb1fc5388b0069f9351f?ref=confluence|Christian Fenzl]]Kontakt aufnehmen (inkl. Name und Telefonnummer).+==== Step 9: Public test ====
  
-==== Schritt 9: Öffentlicher Test ====+Finally, we would first offer your alpha/beta version in the LoxForum for testing (with a corresponding disclaimer that it is still alpha). Once the major problems have been resolved, you should create and document your new plugin in the LoxWiki. Do it like the other plugin authors do.
  
-Schlussendlich würden wir vorerst deine Alpha/Beta-Version im LoxForum anbieten zum Testen (mit entsprechendem Disclaimer, dass es noch Alpha-Stand ist). Wenn die gröberen Probleme ausgeräumt sind, solltest du im LoxWiki dein neues Plugin anlegen und dokumentieren. Machs so, wie es die anderen Plugin-Autoren machen.+===== Recommendations =====
  
-===== Empfehlungen =====+==== Code management with GitHub ====
  
-==== Codeverwaltung mit GitHub ====+With the Windows software GitHub Desktop, you can host your plugin source directory as a public repository on Github. The advantages are: You have real code management with change tracking and the ability to undo changes. In addition, other developers can support you more easily with problems or errors if they have direct insight into your code.
  
-Mit der Windows-Software GitHub Desktop kannst du dein Plugin-Quellverzeichnis als öffentliches Repository bei Github hosten. Vorteile sind: Du hast eine echte Code-Verwaltung mit Änderungsverfolgung und der Möglichkeit, Änderungen rückgängig zu machen. Außerdem können dich andere Entwickler bei Problemen oder Fehlern leichter unterstützen, wenn sie direkt Einblick in deinen Code bekommen.+LoxBerry's built-in update function for plugins is optimized for GitHub.
  
-Die in LoxBerry eingebaute Update-Funktion für Plugins ist für GitHub optimiert.