[FHEM Tablet-UI] Dokumentation (Diskussionsthread)

[Standarduser]

Hallo zusammen!

Es mehren sich die Wünsche nach einer etwas aktuelleren Dokumentation für die Tablet-UI, zu lesen an verschiedenen Stellen und in verschiedenen Kommentaren. Verständlich, sind doch bei weitem nicht alle Funktionen und Attribute dokumentiert. Vieles bekommt man eben nur im "Vorbeigehen" mit.

Dies soll nun der Versuch sein, das Thema etwas voran zu bringen.
In diesem Thread soll es weniger um die technischen Inhalte gehen, als viel mehr darum, das ganze strukturell und organisatorisch zu diskutieren.
Da die Dokumentation schon ziemlich weit ist, dürfen nun auch gern die Inhalte der Dokumentation diskutiert werden.

Ich beginne mit dem Vorschlag von setstate...

Ich wäre für das FHEM Wiki als Hauptdoku. Jeder der ein Problem lösen konnte und sich fragt, warum steht das nirgends, sollte das gleich im Wiki eintragen. Am besten Unterseiten nach Widget getrennt und ein großer Punkt "get started" mit Hinweisen zu Layout, Positionierung, Farben usw. Viel mit Verlinkungen über Schlagworte und Inhaltsverzeichnisse. Und viele Codesnipsel  - nur mit den minimal notwendigen Attributen und Klassen. ...

...und schlage folgenden Aufbau vor:

Code Auswählen Erweitern


+--Hauptseite (Vorstellung des Projektes)
+--Getting Startet (Schnelleinstieg ins Thema, Installation)
+--Layoutvarianten(Grundladen/Möglichkeiten)
| +-Gridster (mit Parametererklärung und grafischen Zusammenhängen)
| +-Flexbox (mit Parametererklärung und grafischen Zusammenhängen) {Ersteller:Kermit20}
| +-Cell/Row (mit Parametererklärung und grafischen Zusammenhängen) {Ersteller:Kermit20}
+--Formatierung (Grundsätzliches zu Symbolen, Farben, groß/klein/dick/dünn/wasauchimmer)
+--Widgets (Ausführliche Beschreibung der Widgets, mit Beispielbildern, Formatierungsmöglichkeiten, usw.)
| +-agenda
| +-button
| +-calview
| +-chart done
| +-checkbox done
| +-circlemenu done
| +-classchanger
| +-clicksound
| +-clock done
| +-colorwheel done
| +-datetimepicker done
| +-departure done
| +-dimmer done
| +-eventmonitor
| +-fullcalview
| +-gds
| +-highchart
| +-highchart3d
| +-homestatus done
| +-html
| +-iframe
| +-image done
| +-input done
| +-itunes_artwork
| +-javascript
| +-joinedlabel
| +-klimatrend done
| +-knob done
| +-kodinowplaying
| +-label done
| +-level done
| +-link done
| +-loading
| +-medialist
| +-meteogram
| +-mpdnowplaying
| +-multistatebutton
| +-notify
| +-pagebutton done
| +-pagetab done
| +-playstream done
| +-popup done
| +-progress done
| +-push done
| +-range done
| +-readingsgroup done
| +-reload
| +-rotor done
| +-screensaver
| +-select done
| +-settimer
| +-simplechart done
| +-slideout
| +-slider done
| +-spinner done
| +-svgplot
| +-swiper
| +-switch done
| +-symbol
| +-thermostat done
| +-tts
| +-uwz
| +-volume done
| +-wakeup
| +-wdtimer
| +-weather done
| +-weekdaytimer
| +-weekprofile
| +-wind_direction done
+--Beispiele
| +-Zeitschaltung done
| +-Datetimepicker done
| +-Webradio done
+--Templates
+--FAQ
+--CSS-Tricks
+--Eigene Widgets erstellen
+--...


Es sind natürlich alle herzlich dazu eingeladen, etwas dazu beizutragen.
Um jetzt aber nicht das totale Chaos ausbrechen zulassen und doppelte Arbeit zu vermeiden, wäre es vielleicht sinnvoll, wenn sich die Leute melden, die einen bestimmten Bereich/Widget dokumentieren wollen. Ich würde das dann in der Übersicht ergänzen. Außerdem wäre es sicher gut, wenn man sich auf einen einheitlichen Aufbau der Widget-Doku einigen könnte, damit sich die Leser auch schnell darin zurecht finden.

Ein Benutzerkonto für das Wiki kann hier beantragt werden: https://wiki.fhem.de/wiki/FHEMWiki:Administratoren (habe ich auch gerade getan).

Inhalt der Widget-Doku:
- Bilder der verschiedenen Formatierungsmöglichkeiten (Vergleich: http://knowthelist.github.io/fhem/tablet/demo_spinner.html)
- Verfügbare Formatierungsattribute
- Verfügbare Steuerungsattribute
- FHEM-Definition zugehöriger Devices (falls zutreffend)

Folgende Festlegungen wurden getroffen:
- Namensgebung der Wiki-Seiten für Widgets nach folgendem Schema: FTUI Widget <Widgetname>
- Namensgebung der Wiki-Seiten für Beispiele nach folgendem Schema: FTUI Beispiel <Thema des Beispiels>
- Hauptsprache der Dokumentation: Deutsch
- Der Grundsätzliche Aufbau sollte an FTUI Widget Select und FTUI Widget Push orientieren
- CSS-Klassen sollen in der Vorlage gepflegt und daraus verwendet werden
- Einleitung der Seite sollte so aussehen: Das [[{{PAGENAME}}|<Widget-Name>]] ist ein Widget für [[FHEM Tablet UI]]...

Noch ein paar generelle Anmerkungen zur Vorgehensweise:
Die Tablet-UI Hauptseite im Wiki besteht momentan (vereinfacht gesagt) aus:
- Einleitung
- Auflistung aller Widgets
- Konfiguration aller Widgets
- Beispiele zu allen Widgets

Wenn jemand eine Seite erstellt hat, dann bitte das entsprechende Widget (Konfiguration und Beispiele) aus der Hauptseite löschen und den Link in der Widget-Liste auf die neue Seite umlenken. So gibt es keine doppelte Doku. Bei der Zusammenfassung der Änderung schreibt Ihr dann bitte hinein, dass die Doku für dieses Widget auf eine neue Seite ausgelagert wurde.
Tipp: Manchmal sind die Beispiele von der Hauptseite besser, als die auf Github.

[drhirn]

Danke für's Thread-Erstellen!

Die generellen Attribute fehlen noch. Und ein Absatz zur Installation.

Die Positionierung würde ich auf der Hauptseite abhandeln, Beispiele dann auf einer Unterseite (eine gemeinsame Unterseite für alle drei Möglichkeiten).

Wir müssen uns über die Namensgebung der Widget-Seiten einigen. Schlage vor FTUI Select Widget.

Und wir sollten uns einigen, ob wir's auf englisch oder deutsch machen.

[setstate]

Eine Untergruppe fällt mir noch ein: "eigene Widgets erstellen"

[Standarduser]

Eine Untergruppe fällt mir noch ein: "eigene Widgets erstellen"

Das ist ja fast die wichtigste

1. Die generellen Attribute fehlen noch. Und ein Absatz zur Installation.
2. Die Positionierung würde ich auf der Hauptseite abhandeln, Beispiele dann auf einer Unterseite (eine gemeinsame Unterseite für alle drei Möglichkeiten).
3. Wir müssen uns über die Namensgebung der Widget-Seiten einigen. Schlage vor FTUI Select Widget.
4. Und wir sollten uns einigen, ob wir's auf englisch oder deutsch machen.

1. Sehe ich im Getting startet
2. Ja, kann man eigentlich gut zusammenfassen
3. Mir egal, Hauptsache immer nach dem gleichen Schema
4. Ich stimme für deutsch. Übersetzen kann man das ja zusätzlich noch.

[drhirn]

Ich nehm auf jeden Fall das Select-Widget. Da hab ich nämlich grad mal ein Beispiel gemacht, damit ich weiß, wie's aussehen könnte

[Familienpapi]

Die Theorie/Basis sieht schon mal sehr gut aus. Lasst es uns umsetzen. Freu mich.

gesendet von meinem Note via Tapatalk

[bm7777]

Das sieht gut aus. Ich würde auch gerne mithelfen, denke aber das ich noch nicht genug Erfahrung habe um mitzuschreiben. Ich könnte aber Korrektur lesen und austesten. Gut fände ich auch Links zu guten HTML\CSS Seiten(selfhtml....). Ich sehe oft Fragen die eigentlich reines HTML\CSS sind.

[drhirn]

Mitschreiben geht immer. Zu Anfang geht's ja nur darum, Bestehendes zu übernehmen und eventuell zu ergänzen. Solltest du wider Erwartens was falsch machen, können das ja andere korrigieren.

Links zu HTML/CSS-Seiten halte ich nicht für notwendig. Eine Suchmaschine kann eigentlich jeder verwenden (sollte man zumindest meinen). Und außer SelfHTML und dem Mozilla Developer Network braucht man eigentlich nicht viel

[redlav]

Die Frage wäre noch, ob die def's der fhem-Devices auch in den Beispielen abgelegt werden sollen/müssen.

Oft kopiert man sich den ftui-Code und bekommt es dann nicht hin, weil das Device im fhem selber nicht so
aussieht, wie es müsste.

Man könnte den Devicecode natürlich auch auf der wiki-Seite des jeweiligen Moduls oder unter den Code Snippets
ablegen und verlinken.

Es sollte nur einheitlich gehandhabt werden.

[Standarduser]

Ich denke, es wäre eine gute Idee, auch die passende FHEM-Config mit ans Beispiel anzuhängen

[drhirn]

Die Frage wäre noch, ob die def's der fhem-Devices auch in den Beispielen abgelegt werden sollen/müssen.

Hab ich mir auch überlegt. Halte ich grundsätzlich für eine gute Idee. Befürchte aber, dass die Leute dann einfach die DEFs kopieren und dann dazu Fragen stellen, weil sie nicht verstehen, was sie da tun.

[redlav]

Befürchte aber, dass die Leute dann einfach die DEFs kopieren und dann dazu Fragen stellen, weil sie nicht verstehen, was sie da tun.

Die Frage kommt sowieso. Wenn nur der ftui-Code da steht, funktioniert es ja auch nicht automatisch in fhem.
Manches ist ja auch nicht unbedingt trivial  Mir hilft es immer, wenn ich die def's dazu habe, weil ich dann die Chance habe die commandref
anhand dieses Beispiels zu verstehen. Sonst breche ich mir da gerne schonmal einen ab.

[bm7777]

Mitschreiben geht immer. Zu Anfang geht's ja nur darum, Bestehendes zu übernehmen und eventuell zu ergänzen. Solltest du wider Erwartens was falsch machen, können das ja andere korrigieren.

Das kann ich machen. Abschreiben kann ich gut 

[TWART016]

Mir fallen noch ein paar Untergruppen ein:
- Versionshistorie
- Beispielseiten (index-example.html), inkl. der aktuellen Header
- User Demos: Einige stellen in den Thread ihre Seiten vor. Nachträglich die zu finden ist nicht gerade einfach
https://forum.fhem.de/index.php?topic=37378.0

[Standarduser]

Deinen 2. und 3. Anstrich sehe ich eigentlich bei "komplexe Beispiele". Da passt denke ich so ziemlich alles rein. Ob das nun wirklich so heißen muss, oder ob es da nicht eine treffendere Bezeichnung gibt, darf natürlich gern diskutiert werden.
Ab einem bestimmten Punkt macht es sicher auch Sinn, das noch etwas weiter zu untergliedern, aber das werden wir ja dann sehen.

Nur was soll man sich unter Versionshistorie vorstellen und wer soll das pflegen?