diff --git a/doc/manual/de/colab/dev/test.rst b/doc/manual/de/colab/dev/test.rst index abd42087ff8..0efce176fc2 100644 --- a/doc/manual/de/colab/dev/test.rst +++ b/doc/manual/de/colab/dev/test.rst @@ -13,7 +13,7 @@ Zu kann man z.B. prüfen ob das Klicken auf einen Switch den passenden Wert an d wenn das Backend ein Update für den Switch liefert, dieser diesen entsprechend anzeigt. Unittests ----------- +--------- Als Testrunner für die Unittests kommt `Karma `__ zum Einsatz. Ausgeführt werden die Tests über das Kommandozeilen-Tool Grunt. diff --git a/doc/manual/de/colab/index.rst b/doc/manual/de/colab/index.rst index 5954c12b95e..130d769c2c9 100644 --- a/doc/manual/de/colab/index.rst +++ b/doc/manual/de/colab/index.rst @@ -263,6 +263,7 @@ Mithilfe bei der Entwicklung * .. .. toctree:: + :glob: dev/test diff --git a/doc/manual/de/colab/internal.rst b/doc/manual/de/colab/internal.rst new file mode 100644 index 00000000000..e69de29bb2d diff --git a/doc/manual/de/config/url-params.rst b/doc/manual/de/config/url-params.rst index a70e310a051..ac86f82ff4d 100644 --- a/doc/manual/de/config/url-params.rst +++ b/doc/manual/de/config/url-params.rst @@ -153,6 +153,8 @@ funktionieren. Default: 0 (testMode=0) Options: 0 (testMode=0), 1 (testMode=1) +.. _enableCache: + *enableCache* - Caching aktivieren ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/manual/de/devel/index.rst b/doc/manual/de/devel/index.rst new file mode 100644 index 00000000000..9ce47f843be --- /dev/null +++ b/doc/manual/de/devel/index.rst @@ -0,0 +1,176 @@ +**************************** +Informationen für Entwickler +**************************** + +Diese Seite liefert eine Einführung in die internen Zusammenhänge und Hintergründe der CometVisu und richtet sich in +erster Linie an Entwickler. + +Grundlagen der Software +----------------------- + +Die CometVisu ist seit Version 0.11 auf dem `Qooxdoo-Framework `__ aufgebaut. +Das Qooxdoo Framework bietet ein eigenes Objekt-Orientiertes Klassensystem (inkl. erweiterten Features wie: Interfaces +Mixins, Abstakte Klasse, Singletons, einfache Type-Checks für Properties, usw.) mit dem sich ein komplexes und +dennoch strukturiertes Software-System aufbauen lässt. + +Ebenso liefert es eine vollständige Toolchain (Qooxdoo-Generator) mit, die Klassenabhängigkeiten automatisch auflöst und daraus +entweder Entwickler Versionen (source-Version) oder Releases (build-Versionen) baut. + +Unterschiede in der Javascript-Unterstützung der verschiedenen Browser werden automatisch ausgeglichen und der +Generator erstellt für die Releases unterschiedliche Build-Versionen für die 4 wichtigsten Browser-Engines. + +Weitere Qooxdoo-Features die die CometVisu nutzt: + +* `Parts `__: + Teile des Codes, die nicht immer benötigt werden, werden in *Parts* ausgelagert, die bei Bedarf nachgeladen werden. + Die CometVisu nutzt dies für Plugins und die Widget-Pakete (Es gibt zwar momentan nur das *Pure*-Widgetpaket, + weitere sind jedoch möglich). + +Da die CometVisu eigene Widgets liefert inkl. Layout und CSS-basiertem Design, wird der komplette UI Teil von +Qooxdoo nicht benutzt. Dieser liefert eigene Layoutmanager und Widgets mit nicht CSS-basiertem Design. +Es wäre jedoch möglich ein neues auf Qooxdoo-UI basierendes Widgetpaket zu implementieren, welches parallel nutzbar ist. + +Startverhalten +-------------- + +Der Ablauf des Ladens der Visu läuft nach dem CometVisu-Protokoll in folgenden Schritten: + +.. uml:: + :caption: Start-Kommunikation zwischen CometVisu und Backend + :align: center + + autonumber + + CometVisu -> Backend: Lade Konfigurationsdatei + Backend -> CometVisu: Konfigurationsdatei mit optionalen Headern schicken + CometVisu -> Backend: Login + Backend -> CometVisu: Bestätigung des Logins mit optionaler Backend-Konfiguration + CometVisu -> Backend: Lese Werte vom Backend + + +#. Laden der Konfigurationsdatei ``visu_config*.xml`` +#. Der Server kann diese Datei mit 2 optionalen Headern ausliefern, die der CometVisu weitere Informationen + über das Backend zu liefern: + + * ``X-CometVisu-Backend-LoginUrl``: Pfad unter der der Client das Login ausführen kann. + * ``X-CometVisu-Backend-Name``: Der Name des zu verwendenden Backends. +#. Die CometVisu authentifiziert sich beim Backend (zur Zeit implementiert kein Backend eine echte Authenfizierung) +#. Das Backend bestätigt die Authentifizierung und liefert Informationen als JSON zurück: + + ``v``: Ist die Protokollversion + + ``s``: Die Session ID + + ``c``: Die optionale Backend-Konfiguration + + + .. code-block:: json + + { + "v":"0.0.1", + "s":"0", + "c": { + "name":"openhab2", + "transport":"sse", + "baseURL":"/rest/cv/", + "resources": { + "read":"r", + "rrd":"rrdfetch", + "write":"w" + } + } + } +#. Die CometVisu fängt an die Werte vom Backend abzufragen, zunächst initial alle benötigten Werten und im + zweiten Schritt wird nur noch auf Änderungen der Werte gelauscht. + +Transportschichten +------------------ + +Die Transportschichten sind für die Kommunikation zwischen CometVisu und Backend ab dem Moment des erfolgreichen +Logins verantwortlich. Die wesentliche Aufgabe besteht also darin, Werte vom Backend abzufragen (lesende Anfrage) +und Wertänderungen zum Backend zu schicken (schreibende Anfrage). + +Zur Zeit unterstützt die CometVisu zwei unterschiedliche Transportschichten: + +* :ref:`Long polling `: wird vom Default-Backend benutzt +* :ref:`Server sent events `: wird vom openHAB-Backend benutzt + +.. toctree:: + + transport/long-polling + transport/sse + +Caching +------- + +Die CometVisu nutzt eigene Caching Mechanismen um das initiale Laden zu beschleunigen. +Die meiste Zeit wird benötigt um die XML-Konfigurationsdatei vom Server zu laden, dann zu parsen und daraus +den HTML Code zu generieren der die tatsächliche Visu im Browser darstellt. + +Da sich der Inhalt der Konfigurationsdatei in der Regel selten ändert, liegt es Nahe diese nicht jedesmal erneut zu laden und +zu parsen. Daher wird nach dem ersten Parsen der erzeugte HTML und die internen Datenstrukturen im *LocalStorage* des Browsers +abgespeichert. Beim nächsten Laden der Visu werden diese Daten ausgelesen und die Oberfläche sofort dargestellt. +Erst danach fragt die Visu die Konfigurationsdatei vom Server ab und vergleicht ob es Änderungen gegeben hat. +Sofern dies nicht der Fall ist wird die gerade geladenen Datei verworfen, andernfalls der Parse und Speicher-Vorgang erneut +durchgeführt und die Daten aus dem Cache werden verworfen. + +Das Caching kann durch den URL-Parameter :ref:`enableCache` beeinflusst werden. + + +Der NotificationRouter +---------------------- + +Es gibt einen internen ``NotificationRouter`` der für verschiedene Zwecke benutzt wird. +Hauptfunktion dieses Routers ist es Nachrichten entgegenzunehmen und an den richtigen +Empfänger weiterzuleiten. Mögliche Empfänger sind z.B. das ``NotificationCenter`` und der +``PopupHandler``. Beide kümmern sich dann um die Anzeige der Nachricht, entweder in der Nachrichtenzentrale (die am +rechten Rand eingeblendet wird und eine Liste von Nachrichten anzeigt) oder als Popup. + +Eine Nachricht hat immer ein *Topic*, welches der thematischen Zuordnung dient, einen Titel, Text und diverse +Konfigurations-Optionen. + +Folgenden *Topics* werden zur Zeit genutzt: + +* ``cv.error``: Allgemeine Fehler +* ``cv.config.error``: Fehler die beim Einlesen der Config-Datei aufgetreten sind +* ``cv.state.*``: Namespace für alle in den :ref:`Benachrichtigungen ` benutzten Nachrichten + +Ein Nachrichtenempfänger (``NotificationHandler``) kann sich nun für eines oder mehrere solcher Topics registrieren: + +.. code-block:: javascript + + cv.core.notifications.Router.getInstance().registerMessageHandler(this, { + 'cv.config.error': { + type: "error", + icon: "message_attention" + }, + 'cv.error': { + type: "error", + icon: "message_attention" + } + }); + + +Auch Wildcards sind möglich: + +.. code-block:: javascript + + cv.core.notifications.Router.getInstance().registerMessageHandler(this, { + 'cv.*': {} + }); + + +Fehlerbehandlung +---------------- + +Der NotificationRouter wird auch dazu genutzt alle nicht abgefangenen Fehler zur Laufzeit der Visu anzuzeigen. +Diese Fehler werden als Popup angezeigt und ermöglichen es dem Nutzer direkt ein Issue auf Github mit vorausgefüllten +Formular mit den wichtigsten Informationen zu eröffnen. Diese Funktion ist nur +in den Build-Versionen aktiv (also auch in den Releases), während der Entwicklung werden die Fehler weiterhin +auf der Javascript-Konsole des Browsers angezeigt. + +Weitere Fehler werden, je nach Art, entweder als Popup oder als Nachricht in der Nachrichtenzentrale angezeigt. +Als ein wichtiges Beispiel wären hier noch Verbindungsprobleme mit dem Backend zu nennen. Diese werden ebenfalls +als Popup über der Visu angezeigt, solange das Problem besteht. + +Der ``NotificationRouter`` wird ebenfalls für die :ref:`Benachrichtigungen ` genutzt. diff --git a/doc/manual/de/devel/transport/long-polling.rst b/doc/manual/de/devel/transport/long-polling.rst new file mode 100644 index 00000000000..8613f98d4f7 --- /dev/null +++ b/doc/manual/de/devel/transport/long-polling.rst @@ -0,0 +1,25 @@ +.. _long-polling: + +Long polling +^^^^^^^^^^^^ + +Lesende Anfragen +**************** + +Beim Long polling stellt die CometVisu eine Verbindung zum Backend her und lässt diese offen bis das Backend Daten sendet. +Die initiale Anfrage nach allen Werten beantwortet das Backend sofort. Die darauffolgenden Anfragen werden beantwortet, +sobald ein neuer Wert eintrifft. Dieser wird dann an die CometVisu gesendet, worauf die Verbindung geschlossen und sofort +wieder aufgebaut wird. + +.. HINT:: + + Als Besonderheit ist hier noch der interne *Watchdog* zu nennen, welcher eine Long polling Anfrage automatisch + beendet und neu started, wenn innerhalb von 60 Sekunden keine Antwort gekommen ist. + +Schreibende Anfragen +******************** + +Wenn ein neuer Wert an das Backend gesendet werden soll (weil z.B. der Benutzer ein Widget bedient hat), wird +eine neue Anfrage, die vollkommen unabhängig von den lesenden Anfragen ist, an das Backend gesendet. +Hier bestätigt das Backend auch lediglich das erfolgreiche Empfangen der Anfrage, neue Werte werden immer nur über +die lesenden Anfragen gesendet. diff --git a/doc/manual/de/devel/transport/sse.rst b/doc/manual/de/devel/transport/sse.rst new file mode 100644 index 00000000000..8edaa7cb70e --- /dev/null +++ b/doc/manual/de/devel/transport/sse.rst @@ -0,0 +1,25 @@ +.. _sse: + +Server sent events (SSE) +^^^^^^^^^^^^^^^^^^^^^^^^ + +Lesende Anfragen +**************** + +Bei *Server sent events* wird eine einmalige lesende Verbindung aufgebaut. Über diese schickt das Backend +initial einmalig alle angefragten Werte, danach nur noch geänderte Werte. + +.. HINT:: + Der Browser kümmert sich automatisch um die Wiederherstellung der Verbindung bei Abbrüchen. + Daher kommt der interne *Watchdog* bei SSE in der Regel nicht zum Einsatz. + +Der Browser muss diese Technologie jedoch überstützen. +Eine Übersicht der unterstützen Browser liefert `Caniuse `__. + +Schreibende Anfragen +******************** + +Wenn ein neuer Wert an das Backend gesendet werden soll (weil z.B. der Benutzer ein Widget bedient hat), wird +eine neue Anfrage, die vollkommen unabhängig von den lesenden Anfragen ist an das Backend gesendet. +Hier bestätigt das Backend auch lediglich das erfolgreiche Empfangen der Anfrage, neue Werte werden immer nur über +die lesenden Anfragen gesendet. \ No newline at end of file diff --git a/doc/manual/de/index.rst b/doc/manual/de/index.rst index cc82210eb20..f698c2a656e 100644 --- a/doc/manual/de/index.rst +++ b/doc/manual/de/index.rst @@ -96,5 +96,6 @@ oder `hier `__ install/index config/index colab/index + devel/index faq diff --git a/source/resource/visu_config.xsd b/source/resource/visu_config.xsd index 86f760f2483..a939ab9a112 100644 --- a/source/resource/visu_config.xsd +++ b/source/resource/visu_config.xsd @@ -175,7 +175,7 @@ level:expert - Selection of a display variant. See also :ref:'flavour'. + Selection of a display variant. See also :ref:`flavour`. Auswahl der Darstellungsvariante. Siehe auch :ref:`Flavour <flavour>`. diff --git a/utils/docutils/directives/__init__.py b/utils/docutils/directives/__init__.py index 138772eee34..1358a02158f 100644 --- a/utils/docutils/directives/__init__.py +++ b/utils/docutils/directives/__init__.py @@ -20,13 +20,13 @@ import sh import json import os -import ConfigParser +import configparser root_dir = os.path.abspath(os.path.join(os.path.realpath(os.path.dirname(__file__)), '..', '..', '..')) class Version: _source_version = None - config = ConfigParser.ConfigParser() + config = configparser.ConfigParser() config.read(os.path.join(root_dir, 'utils', 'config.ini')) @classmethod