Dokumentation

[Fry]

Dafür gibts einen Parameter im Pages-Element der Config:

<pages ... scroll_speed="0" ...>

Danke. Sagt mal, um solche Fragen in Zukunft zu vermeiden, WO finde ich eine vollständige Auflistung der verfügbaren Optionen und XML-Tags? Einzeilige Erläuterungen würden reichen.

(das einzige, was ich bisher gefunden habe, ist hoffnungslos veraltet oder unvollständig oder beides, aber dafür ausführlich).

VG, Fry

[swiss]

Hallo Fry

Du such also etwas in der Art...

Attribute für das Pages Element:

design = Desigen des Visualisierung
backend = Zu verwendendes Backend (weggelassen = cgi-bin) mögliche Optionen oh für OpenHAB
bind_click_to_widget = Bei true wird die ganze Widgetfläche als Schaltfläche verwendet
scroll_speed = Geschwindigkeit der Scrollanimation beim Seitenwechsel. 0 = deaktiviert
max_mobile_screen_width = Maximale Bildschirmbreite in pixel die zur Unterscheidung zwischen Desktop und Mobile Geräte verwendet wird.
min_column_width = Minimale Breite in Pixel die ein Widget einnehmen kann damit es auch auf kleinen Displays bedienbar bleibt.
default_columns = Hier weiss ich lieder nicht wozu das sein soll.
enable_column_adjustment = Kenne ich auch noch nicht.
lib_version = Wird intern vom Updatecript verwendet um festzustellen ob eine Config auf Grund von Syntaxänderungen aktualisiert werden sollte oder nicht.
screensave_time = Zeit in Sekunden bis die Visu zur screensave_page zurück scrollt
screensave_page = Seite innerhalb der Visu die als screensave_page genutzt werden soll
xsi:noNamespaceSchemaLocation = Relativer Pfad zur visu_config.xsd (ist im Normalfall nie anzufassen und steht im Editor auch nicht zur Verfügung)

Wenn wir das kompletiert bekommen kann ich das im Handbuch gerne nachführen

[peuter]

default_columns = Hier weiss ich lieder nicht wozu das sein soll.
enable_column_adjustment = Kenne ich auch noch nicht.

default_columns = normalerweise werden die Widgets auf 12 Spalten pro Zeile aufgeteilt und man kann über das <layout colspan="x"/> Element die Breite eines Widget in Spalten festlegen. Hiermit kann man nun den Default-Wert der Spalten von 12 z.B. für kleinere Bildschirme reduzieren oder auch erhöhen (für große Bildschirme).

enable_column_adjustment = true|false(default) versucht das o.g. in eingeschränktem Rahmen automatisch zu machen, d.h. auf kleinen Bildschirmen wird die Anzahl der Spalten reduziert von 12 auf 6 / 3 / 2 / 1
ist der Versuch die Visu, die für einen PC/Tablet entworfen wurde zumindest einigermaßen brauchbar auf das Smartphone zu bekommen. Ist aber nicht perfekt.

Man kann den letzten Parameter mal aktivieren und dann die Breite seines Browserfensters verkleiner um das in Aktion zu sehen, dann wird der Sinn vielleicht klarer.

[Fry]

Hallo Fry

Du such also etwas in der Art...

Attribute für das Pages Element:

Ja, genau. Und das Gleiche for <text>, <info> usw. Ein Absatz pro Tag, eine Zeile pro Parameter. ZB findet man unter /diagram/structure_plugin.js gleich am Anfang den Kommentar

/**
 * short documentation
 *
 * widgets:
 *   - diagram
 *   - diagram_info
 *
 * attributes:
 *   - series:               optional, "hour", "day" (default), "week", "month", "year"
 *   - period:               optional, number of "series" to be shown
 *   - refresh:              optional, refresh-rate in seconds, no refresh if missing
 *   - fill:                 optional, true or false - filling the space under the line
 *   - gridcolor:            optional, color for dataline and grid, HTML-colorcode
 *   - width, height:        optional, width and height of "inline"-diagram
 *   - previewlabels:        optional, show labels on "inline"-diagram
 *   - popup:                optional, make diagram clickable and open popup
 *   - legend:               optional, "none", "both", "inline", "popup" select display of legend
 *   - title:                optional, diagram title (overrides label-content)
 */

Das hilft schon ganz erheblich. Nur dass es das für die meisten Widgets so nicht gibt... (oder ich es nicht gefunden habe).

VG, Fry

[kleinklausi]

, WO finde ich eine vollständige Auflistung der verfügbaren Optionen und XML-Tags?

Hi,
in der XSD sollten eigentlich alle validen Parameter für PAGE und alle Widgets drin stehen. So hatte ich es jedenfalls verstanden.

Gruß Moritz

[swiss]

@Tobias: Danke für die Erklärung

@Moritz: Genau in der visu_config.xsd ist alles enthalten. Nur sind da leider viele Attribute noch nicht mit Hilfstexte (die auch im Editor angezeigt würden) ausgestattet. Dazu bin ich einfach noch nicht gekommen und jemand anderes hat sich bis jetzt noch nicht dazu bereiterklärt

@Fry: Du hast recht etwas in der Art existiert noch überhaubt nicht auch wenn es für Leute die direkt in der XML arbeiten ein gutes Hilfsmittel wäre... Ich sehe mir dass mal an und versuche mal eine komplete Attributenliste mit Beschreibung zu ersellen. Dies wird aber etwas Zeit in Anspruch nehmen...

[Chris M.]

Die XSD ist eigentlich der beste Platz(*) um das aus Entwickler-Sichet zu dokumentieren. Dann können die Doku-Ersteller dort nachsehen und das Wiki passend pflegen (natürlich darf es auch die Personal-Union von Entwickler und Doku-Ersteller geben )

--
(*) Noch besser wäre natürlich im Code und eine Auto-Generierte XSD. Aber vorher gibt's genug andere Baustellen zu lösen...

[Tqm]

Da es mir an großen Entwickler-Fähigkeiten fehlt oute ich mal hier nur zu gerne als Tester und Dokumentierer ...
Gebt mir die Aufgabe und ich mache ...

Schöne Grüße,
Thomas

[swiss]

Hier Wäre die XSD ein super Anfang. Wenn die mal sauber auskommentiert ist, geht der Rest schon wesentlich einfacher

Das Dokumentieren ist im Grunde genommen auch nicht sehr kompliziert...

In der visu_config.xsd findest gerade in der unteren Hälfte alle Widget und ihre Attribute aufgeführt. Diese sehen z.B. beim slide so aus:

<xsd:complexType name="slide">
<xsd:sequence>
<xsd:element name="layout" type="layout" minOccurs="0" maxOccurs="1"/>
<xsd:element name="label" type="label" minOccurs="0" maxOccurs="1"/>
<xsd:element name="address" type="address" minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute ref="min" />
<xsd:attribute ref="max" />
<xsd:attribute ref="step" />
<xsd:attribute ref="mapping" use="optional" />
<xsd:attribute ref="styling" use="optional" />
<xsd:attribute ref="format" use="optional" />
<xsd:attribute ref="flavour" use="optional" />
</xsd:complexType>

Wichtig sind die <xsd:attribute ref= die zur Dokumentation um:

<xsd:annotation>
<xsd:documentation xml:lang="en">Beschreibung in englisch</xsd:documentation>
<xsd:documentation xml:lang="de">Beschreibung in deutsch.</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

ergänzt werden. Dabei entfällt der schliessende Slasch am ende des Attributes...

Hier mal ein Beispiel wie die Doku beim ersten und zweiten Attribut für das slide Widget aussehen müsste (vieles ist coppy&paste):

<xsd:complexType name="slide">
<xsd:sequence>
<xsd:element name="layout" type="layout" minOccurs="0" maxOccurs="1"/>
<xsd:element name="label" type="label" minOccurs="0" maxOccurs="1"/>
<xsd:element name="address" type="address" minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute ref="min">
<xsd:annotation>
<xsd:documentation xml:lang="en">Minimum value of the slide Widget.</xsd:documentation>
<xsd:documentation xml:lang="de">Mindestwert des Slide Widgets.</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute ref="max">
<xsd:annotation>
<xsd:documentation xml:lang="en">Maximum value of the slide Widget.</xsd:documentation>
<xsd:documentation xml:lang="de">Maximalwert des Slide Widgets.</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute ref="step" />
<xsd:attribute ref="mapping" use="optional" />
<xsd:attribute ref="styling" use="optional" />
<xsd:attribute ref="format" use="optional" />
<xsd:attribute ref="flavour" use="optional" />
</xsd:complexType>

Diese Hilfetexte werden dann automatisch auch im Editor angezeigt:

<xsd:attribute name="mapping" type="xsd:string">
<xsd:annotation>
<xsd:documentation xml:lang="en">Map the bus value to a different value for displaying.</xsd:documentation>
<xsd:documentation xml:lang="de">Ordnet den Werten vom Bus andere zur Anzeige zu.</xsd:documentation>
</xsd:annotation>
</xsd:attribute>

Lieder kann der Editor momentan nur englisch aber man sollte trotzdem beide Sprachen schon mal vorbereiten

[swiss]

@Chris: Sorry das was wieder einmal zu impulsiv. Könntest du das in ein separates Thema auslagern. Das hat hier nix zu suchen. Ich war nur so happy dass sich gerade jemand zum dokumentieren helfen angeboten hat

[Chris M.]

Könntest du das in ein separates Thema auslagern.

Hab ich gerade gemacht. Ein besserer Thread-Name ist mir spontan nicht eingefallen...

[tht]

(*) Noch besser wäre natürlich im Code und eine Auto-Generierte XSD. Aber vorher gibt's genug andere Baustellen zu lösen...

Fehlt mir hier das Verständnis für dir Methodik der CV oder haben wir hier unterschiedliche Ansichten, möglich wäre wohl beides.

Ich persönliche sehe die xsd als Basis an, auf dem der Code aufbaut. Bei neuen Elementen/Widgets/Attributen sollte nach der Idee generell die Frage kommen, wie man das repräsentiert -> Änderung an der XSD und daraufhin wird der Code gebaut.

Einfacher: der Code hängt von der XSD ab und nicht die XSD vom Code. XSDs
Haben für mich immer etwas normatives. Auch im Sinne der Abwärtskompatibilität: der Code muss so geschrieben sein, dass er aus der Config die auf der XSD basiert die richtigen Elemente erzeugt.

Auch fürs testen: der Code erzeugt aus einer XML Elemente im Frontend. Vergleiche würde ich auf Basis einer XSD und unterschiedlicher Codeversionen/ bzw der Referenzdefiniton durchführen.

Wenn sollte der erste Teil der Doku in der XSD sein und nicht im Code oder?

Oder entwickelt ihr andersrum: erst den Code und dann die XSD?

[Chris M.]

Fehlt mir hier das Verständnis für dir Methodik der CV oder haben wir hier unterschiedliche Ansichten, möglich wäre wohl beides.

Ich persönliche sehe die xsd als Basis an, auf dem der Code aufbaut.
[...]

Wenn sollte der erste Teil der Doku in der XSD sein und nicht im Code oder?

Oder entwickelt ihr andersrum: erst den Code und dann die XSD?

Theorie und Praxis. Wahre Lehre und optimaler Ressourcen-Einsatz...

Praktisch wird der Code-Entwickelt. Dabei wird festgelegt wie ein Widget-Heißt (-> identisch zum XML-Element) und welche Attribute (+ ggf. Sub-Elemente) es benötigt.
Ein Widget baut das dann in HTML, ggf. CSS und JavaScript-Funktionen für Action (User-Aktion -> Schreiben) und Update (Bus-Aktion -> Visu-Updaten) um.

Aktuell muss nun der Entwickler das im XSD nachziehen.

Früher musste auch noch der Editor nachgezogen werden - womit das Problem des alten Editors klar sein dürfte.

Da jedes Widget sehr unterschiedlich ist und die XSD von den Informationen her schon sehr verdichtet ist, sehe ich weiterhin den Weg Widget-Code -> XSD (-> Editor) richtig an - auch wenn ich Deinen Punkt mit "normativ" durchaus verstehe.

Wer jetzt eine Fingerübung haben möchte, könnte durchaus einen Widget-JS-Parser schreiben, der aus diesen Informationen die XSD bastelt. (Müssten die Hooks in Git das dann nicht sogar automatisch updaten können?).
Und wer es sich einfach machen möchte, dem könnten wir ja anbieten die entsprechenden Infos in den Widget-Dateien in einem definierten Format in die Kommentare zu schreiben.
Das ist schon fast an der wahren Lehre dran - und als selbst dokumentierender Code bereits eine sehr gute Lösung.

[tht]

Wer jetzt eine Fingerübung haben möchte, könnte durchaus einen Widget-JS-Parser schreiben, der aus diesen Informationen die XSD bastelt.

Auf den ersten Blick stecken die Widget-Parameter in den data-Variablen der .js-Dateien der Widgets oder übersehe ich noch etwas?

[Chris M.]

Auf den ersten Blick stecken die Widget-Parameter in den data-Variablen der .js-Dateien der Widgets oder übersehe ich noch etwas?

Jain:

• Ja, ich denke man könnte eine Regel darauf aufbauen
• Nein, da hält sich natürlich aktuell nicht alles daran, da es ja keine Regel gibt...

Für einen ersten Ansatz denke ich, dass wir daraus eine Regel ableiten können. Wir müssen nur dafür sorgen, dass in data auch Werte stehen können, die keine Attribute sind - z.B. über die Benamung dieser Keys (z.B. alle Keys die mit einem Underscore anfangen sind privat und gehören nicht in die XSD).


Was dann aber noch zu klären wäre, ist wie man dann dem Übersetzer mitteilt:

• Datentyp (Number, String, ...)
• Optional (ggf. der dann verwendete Default-Wert)
• Beschreibung des Attributes (in mehreren Sprachen)

Daher hätte ich es mir einfach gemacht und mir ein entsprechendes Format überlegt mit dem diese Info weiter oben in einen großen Kommentar-Block geschrieben werden kann.
Direktes Auslesen aus dem Code hat aber natürlich mehr Hack-Value