Wie kann ich einen Link zur Doku im Konfigurationsformular anbieten?

Erweiterungen PHP-Module (Entwicklung)
1

Hallo,

der Weg zur Doku ist manchmal weit:)

Beispiel: ich suche eine Hilfestellung bei der Konfiguration einer Instanz.

Dann muss ich zunächst wissen:

[ul]
[li]ist es eine Symcon eigene Instanz -> dann suche ich in der Online Doku
[/li][li]ist es eine über das Modul Center installierte Instanz -> dann gehe ich ins Modul Center, suche den Git-Verweis, und suche unter dem Verweis die Doku
[/li][li]ist es eine über das Modul Store installierte Instanz -> dann gehe ich in den Modul Store, suche das installierte Modul und finde darüber den Verweis zur Doku
[/li][li]
[/li][/ul]

Kein Wunder, dass die Doku nur selten gelesen wird (behaupte ich einfach mal) :slight_smile:

Um dem abzuhelfen möchte ich gerne im Konfigurationsformular meiner Module einen direkten Link zur Doku unterbringen.

Hat jemand eine Idee, wie ich das am besten erreiche? Oder gibt es es bereits etwas vorgefertigtes?

Gruß

Burkhard

2

Hallo
Ich mache so etwas in meinem Modul.

{ "type": "Button"            , "caption": "Dokumentation", "onClick": "echo 'https://github.com/1007/Symcon1007_Withings/tree/4.0';" },

Gesendet von iPad mit Tapatalk

3

Danke! Probiere ich aus.

Am elegantesten fände ich, wenn gleich die Doku im Browser geöffnet würde. Hast du da auch eine Idee?

4

Genau das passiert, wenn du eine Adresse als echo ausgibst. Also einfach genau wie von 1007 vorgeschlagen.

5

Perfekt. Das passiert wohl in Verbindung mit dem neuen ‚link‘ Parameter zum ‚Button‘ Element. Wieder etwas dazugelernt.

Ich habe es jetzt mal im RowLayout an den Anfang des Elements Bereichs gesetzt.


    {
      "type": "RowLayout", "items": [
      {"type": "Label", "caption": "In this instance, all parameters for controlling a single blind are stored. The description of the individual parameters can be found in the documentation."},
      {"type": "Button", "caption": "Show Documentation", "onClick": "echo 'https://github.com/bumaas/BlindControl/blob/master/README.md';", "link": true}
    ]
    },

Sieht gut aus.

Eine letzte Frage: streng genommen müsste eigentlich auf die Doku der installierten Version verwiesen werden (also auf das lokale Filesystem …/modules/…/…md). Aber das geht wohl nicht, oder?

6

Du kannst auf die Readme eines spezifischen Commits linken, beispielsweise BlindControl/README.md at 242f1fc44f47eb5727a1cf5f542c08857b2f0d90 · bumaas/BlindControl · GitHub. Dann müsstest du halt den Link in jeder Version aktualisieren. Ob das den Mehrwert lohnt, das musst du entscheiden. Ähnlich könntest du auch per file://… auf lokale Dateien verlinken, da müsstest du allerdings wohl auch den link-Parameter setzen.

Das Links geöffnet werden hat übrigens gar nichts mit dem neuen link-Parameter zu tun, das war schon länger eingebaut. Mit link kannst du allerdings die automatische Erkennung umgehen, falls du beispielsweise eine Adresse anzeigen möchtest oder dein String nicht als Adresse erkannt wird, weil du irgendwelche exotischen Protokolle benutzt (wie z.B. file).

7

Der Aufwand ist dann doch etwas hoch, zumal der Link ja erst nach einem Commit feststeht.

Das klingt spannend und wäre eigentlich genau passend. Da hat man immer ohne Änderungsaufwand die passende Doku zur Version. Nur leider gelingt es mir nicht.
Mein (vielversprechendster) Versuch:

      {"type": "Button", "caption": "Show Documentation", "onClick": "echo 'file:///C:/IP-Symcon/modules/BlindControl/README.md';", "link": true}

Es wird immer nur eine leere Seite angezeigt.:frowning:

Ich vermute, der Speicherort der Datei ist das Problem …

8

Ich bin nicht so fit in dem Thema, aber ich glaube die meisten Browser können Markdown (also .md-Dateien) nicht direkt anzeigen. Github macht da halt die Renderarbeit. Aber man kann das sicherlich irgendwie als html-Datei rendern. Aber da müsstest du mal selber schauen. Vom Element her sieht das soweit richtig aus.

9

Tatsächlich:( Wenn man die Datei direkt im Browser öffnet, dann wird sie z.B. von Chrome als Textdatei angezeigt.

Aber selbst, wenn ich sie in eine html-Datei konvertiere:

      {"type": "Button", "caption": "Show Documentation", "onClick": "echo 'file:///C:/IP-Symcon/modules/BlindControl/README.html';", "link": true}

bleibt die Anzeige leer (about:blank).

Meiner Meinung nach kann es nicht funktionieren, da der lokale Browser nicht auf den Pfad zugreifen kann.

Also müsste wohl schon die Konsole das File darstellen können. Vielleicht zu 6.x :slight_smile:

Da ist es momentan wohl am besten, wie beschrieben auf Github zu verweisen.

Gruß

Burkhard

10

html anzeigen würde nur gehen, wenn dein Modul die Datei in den user Ordner kopiert, dann würde auch link: funktionieren ;).

11

Hallo
Hab das mal bei mir getestet und mir angeschaut ob der Browser in den Entwicklungtools eine Fehler bringt. Tut er :

console-app.js:32510 Not allowed to load local resource: file:///C://Program%20Files%20(x86)//IP-SYMCON//modules//Symcon1007_Withings//README.md
(anonymous) @ console-app.js:32510

12

Danke an euch! Dann liege ich ja richtig: Link auf Github anbieten und gut ist es :slight_smile: