From 8c479ffcee5100af7e90243ecd0f5cd23ef589c1 Mon Sep 17 00:00:00 2001
From: ulrich <not disclosed>
Date: Sat, 27 Jan 2018 17:32:55 +0000
Subject: [PATCH] Doku erweitert
---
README.md | 205 ++++++++++++++++++++++++++++++++++++--------------
1 files changed, 146 insertions(+), 59 deletions(-)
diff --git a/README.md b/README.md
index 63e0444..ff8bc8d 100644
--- a/README.md
+++ b/README.md
@@ -2,29 +2,27 @@
Eine Bedienoberfläche für Webradio
-## Prototyp
+## Funktionen
-Diese Anwendung ist zur Zeit im Bau. Der aktuelle Prototyp zum Stand des Codes in diesem Repository ist hier zu sehen: [Link zum Prototyp](/data/ulrich/test/radio-ui).
-
-## Vorgesehene Funktionen
-
-Das radio-ui zeigt eine Übersicht von Radiosendern. Antippen eines Senders in der Übersicht spielt den Sender ab.
+Das radio-ui zeigt eine Übersicht von Radiosendern. Antippen eines Senders in der Übersicht spielt den [Livestream](/gitblit/doc/web!radio-ui.git/master/radiostreams.md) des Senders ab.
Radiosender können hinzugefügt, geändert und gelöscht werden. Ein Suchfeld ermöglicht das Einschränken der Übersicht auf bestimmte Sender.
-Das Abspiel-Ziel ist konfigurierbar: Ein Radionsender kann entweder auf dem Gerät abgespielt werden, auf dem das radio-ui im Browser läuft oder auf einem anderen Gerät wie z.B. einem Raspberry Pi.
+Das Abspiel-Ziel ist konfigurierbar: Ein Radionsender kann entweder auf dem Gerät abgespielt werden, auf dem das radio-ui im Browser läuft oder auf einem anderen Gerät wie z.B. einem [Raspberry Pi](/gitblit/doc/web!radio-ui.git/master/pirc.md).
-Zum Abspielen auf einem Raspberry Pi ist die Nutzung der Anwendung [pirc](/gitblit/docs/pirc.git) vorgesehen, die zum Spielen von Audiostreams den [omxplayer](https://elinux.org/Omxplayer) mit einer unter [Tomcat](https://de.wikipedia.org/wiki/Apache_Tomcat) laufenden Fernbedienung kombiniert, die per HTTP gesteuert werden kann.
+## Protoyp, Demo
-## Nutzung von Vorlagen
+Das radio-ui als einzelne Webanwendung hat prototypischen Charakter, es kann für allerlei Webradio-Anwendungen die wiederverwendbare Grundlage bilden.
-Die Anwendung radio-ui ist ein Beispiel für die Nutzung von Vorlagen in Webanwendungen. Die Datei `index.html` definiert Bereiche einer HTML-Seite als `div`-Elemente, die während der Ausführung des Programmes dynamisch mit wechselnden Inhalten gefüllt werden.
+Als reinem Client-Teil solcher Anwendungen fehlt dem radio-ui ein zentraler Anwendungskern mit Funktionen zum Speichern individueller Einstellungen an einem zentralen Ort. Die Trennung von Client und Server ist bewußt so gewählt, um einen gleichartigen Client-Teil für verschiedene Implementierungen auf der Serverseite zu ermöglichen.
-Inhalte werden dabei mit Hilfe von [Mustache](https://github.com/janl/mustache.js) aus einer Vorlage und einer Inhaltsbeschreibung in [JSON](https://de.wikipedia.org/wiki/JavaScript_Object_Notation) zu [HTML](https://de.wikipedia.org/wiki/Hypertext_Markup_Language) zusammengesetzt.
+Der aktuelle Stand des Codes in diesem Repository kann hier ausprobiert werden: [Link zur Demo](/data/ulrich/test/radio-ui).
+
+Code und Demo des radio-ui [veranschaulichen](/gitblit/doc/web!radio-ui.git/master/beispiel.md) zusätzlich zum praktischen Nutzen als Webradiofernbedienung verschiedene Aspekte des Baus von Webanwendungen.
## Abhängigkeiten
-Zur Verwendung des radio-ui sind die folgenden Komponenten erforderlich
+Neben dem Code in diesem Repository sind zur Nutzung des radio-ui die folgenden Komponenten erforderlich
+ [jQuery](http://jquery.com/)
+ [Mustache](https://github.com/janl/mustache.js)
@@ -33,87 +31,176 @@
Diese sind in der Datei `index.html` über die folgenden Einträge eingebunden.
````
-<link rel="stylesheet" type="text/css" href="../jslib/app-menu/nav-toggle.css">
<link rel="stylesheet" type="text/css" href="../jslib/app-menu/app-menu.css">
<script src="../jslib/jquery-1.11.1/jquery-1.11.1.min.js"></script>
<script src="../jslib/mustache/mustache.min.js"></script>
<script src="../jslib/app-menu/app-menu.js"></script>
````
-Sollen einzelne Komponenten von einem anderen Ort wie beispielsweise einem Content Delivery Network (CDN) eingebunden werden, müssen nur die obigen Einträge entsprechend angepasst werden.
+Sollen einzelne Komponenten von einem anderen Ort, beispielsweise aus einem Content Delivery Network (CDN) eingebunden werden, müssen diese Einträge angepasst werden.
-## Kombination von pirc und radio-ui
+### Zeichensätze
-Zur Verwendung des radio-ui mit pirc kann die Anwendung radio-ui direkt auf einen Raspberry Pi installiert werden, beispielsweise ähnlich wie pirc als Webanwendung für Tomcat. Stattdessen kann radio-ui auch von einer anderen Maschine aus die pirc-Instanz auf einen Raspberry Pi aufrufen.
-
-Auch eine direkte Steuerung des omxplay aus radio-ui heraus ist denkbar. Das wäre allerdings eine Doppelung der meisten der in pirc bereits enthaltenen Funktionen. Zudem würde die engere Koppelung zwischen Pi und radio-ui die Verwendbarkeit des radio-ui einschränken.
-
-### Abspielen auf dem Raspberry Pi
-
-Kommandos an pirc werden via HTTP an die betreffende Maschine gesendet und bestehen aus einem Klassennamen `c`, einem Methodennamen `m` und einem Parameter `p`. Ein Kommando setzt sich wie folgt zusammen
-
-1. `http://raspi:8080/` - URL der Maschine
-1. `pirc/` - Name des Kontext, unter dem die Anwendung pirc läuft
-1. `sys/rpc` - Service-Endpunkt der pirc-API
-1. `c=de.uhilger.pirc.App` - Name der Klasse von pirc, die die Abspielmethode enthält
-1. `m=abspielen` - Name der Methode zum Abspielen
-1. `p=Sender-URL` - der Parameter mit dem URL zum Audiostream des Webradiosenders
-
-Zum Aufruf des Kommandos mit dem radio-ui kann es weitgehend unverändert bleiben. Nur der Teil 6. mit dem URL des Senders muss veränderlich gestaltet sein.
-
-#### Beispiel Abspielen
-
-Ist die Fernbedienung pirc auf einem Raspberry Pi installiert, lautet das Kommando zum Abspielen des Webradiosenders radiobob (vgl. Senderliste weiter unten) wie folgt
+Neben den obigen Komponenten werden zudem die Zeichensätze `Amethysta`, `Oswald` und `Roboto Condensed` verwendet. Sie können von Google Fonts heruntergeladen werden und sind über das Stylesheet `app.css` von folgenden Orten auf dem Server eingebunden:
````
-http://raspi:8080/pirc/sys/rpc?c=de.uhilger.pirc.App&m=abspielen&p=http://bob.hoerradar.de/radiobob-live-mp3-hq
+/lib/fonts/Amethysta/Amethysta-Regular.ttf
+/lib/fonts/Oswald/Oswald-Regular.ttf
+/lib/fonts/Oswald/Oswald-Bold.ttf
+/lib/fonts/Roboto_Condensed/RobotoCondensed-Regular.ttf
+/lib/fonts/Roboto_Condensed/RobotoCondensed-Bold.ttf
````
-Das obige Kommando geht davon aus, dass der betreffende Raspberry Pi unter dem Namen `raspi` auf Port `8080` über `HTTP` erreichbar ist und dass auf dem Pi die Anwendung pirc unter dem Kontextnamen `pirc` installiert wurde. Es bewirkt, dass auf dem betreffenden Raspberry Pi eine Instanz des omxplayer gestartet wird und diese fortlaufend den Webradio-Stream unter der angegebenen Adresse abspielt.
+### Bilder
-#### Beispiel Stoppen
+Zu jedem Sender wird an der Bedienoberfläche des radio-ui ein Piktogramm angezeigt. In der Demo des radio-ui ist hierfür der Ordner `bilder` vorgesehen. Prinzipiell kann aber jeder Ablageort für Bilder verwendet werden. Jedem Sender ist ein URL zu einem Bild über die Datei `sender.json` zugeordnet. Der URL für ein Bild kann zur Laufzeit über die Funktion `Sender ändern` geändert werden.
-Zum Stoppen des zur Zeit abgespielten Webradios dient das folgende Kommando
+## Installation
+
+Zur Verwendung des radio-ui muss dessen Code mit den Komponenen kombiniert werden, die vom radio-ui benötigt werden.
+
+1. Code aus diesem Repository herunterladen
+1. Die unter Abhängigkeiten oben angegebenen Komponenten herunterladen
+1. Aus den heruntergeladenen Teilen eine Ordnerstruktur bilden
````
-http://raspi:8080/sys/rpc?c=de.uhilger.pirc.App&m=kommando&p=q
+radio-ui/
+ hier der Inhalt aus diesem Repository
+jslib/
+ jquery-1.11.1/
+ jquery-1.11.1.min.js
+ mustache/
+ mustache.min.js
+ app-menu/
+ hier der Inhalt aus dem app-menu-Repository
+lib/
+ fonts/
+ Amethysta/
+ Amethysta-Regular.ttf
+ Oswald/
+ Oswald-Regular.ttf
+ Oswald-Bold.ttf
+ Roboto_Condensed/
+ RobotoCondensed-Regular.ttf
+ RobotoCondensed-Bold-ttf
+bilder/
+ hier Bilder nach Wahl
````
-Mit dem obigen Aufruf wird das Kommando `q` an den laufenden Prozess des omxplayer gesendet. Das bewirkt, dass der omxplayer das Abspielen stoppt und der laufende omxplayer-Prozess endet.
+Die obige Ordnerstruktur wird auf einem HTTP-Server wie z.B. [Tomcat](https://de.wikipedia.org/wiki/Apache_Tomcat) oder [lighttpd](https://de.wikipedia.org/wiki/Lighttpd) hinterlegt und kann dann mit einem Browser aufgerufen werden.
+## Noch zu erledigen
-## Radiostreams
+### Templates für Mustache dynamisch laden
-Nachfolgend die Adressen einiger Radiostreams
+Spart Ladezeit zu Beginn. Lösungsansatz: Eine Funktion, die als Parameter das Element erhält, dessen html mit dem gerenderten Template ersetzt werden soll und den zu rendernden Inhalt. Die dynamische Ladefunktion
-### hr3
+1. prüft, ob das Template schon im cache ist
+1. Lädt das Template, wenn nicht
+1. wartet, bis das Template geladen ist
+1. rendert das Template mit dem übergebenen Inhalt
+1. schreibt das Ergebnis ins html des übergebenen Elements
-[Livestream-Übersicht](http://www.hr3.de/service/hr3-online-hoeren,webradio-100.html)
+Der letzte Teil des Ablaufs muss asynchron gefasst sein, damit auf das Laden gewartet werden kann.
-128 kbit http://hr-hrinfo-live.cast.addradio.de/hr/hrinfo/live/mp3/128/stream.mp3
+## Schnittstellenbeschreibung
-48 kbit http://hr-hr3-live.cast.addradio.de/hr/hr3/live/mp3/48/stream.mp3
+Für den Prototyp des radio-ui können verschiedene Arten des Umgangs mit Sendern und Abspielern hergestellt werden. Die folgenden Angaben zeigen die Punkte auf, an denen eine konkrete Implementierung ansetzen kann.
-### hr info
+### Sender
-[Livestream-Übersicht](http://www.hr-inforadio.de/livestream/index.html)
+#### Senderliste lesen
-128 kBit/s http://hr-hrinfo-live.cast.addradio.de/hr/hrinfo/live/mp3/128/stream.mp3
+Aufruf
-48 kBit/s http://hr-hrinfo-live.cast.addradio.de/hr/hrinfo/live/mp3/48/stream.mp3
+````
+data/sender.json
+````
-### radiobob
+Antwort
-[Livestream-Übersicht](http://www.radiobob.de/radiobob/empfang/livestream)
+````
+{
+ "senderliste": {
+ "titel": "Senderliste",
+ "inhalt": [
+ {
+ "senderid": 1,
+ "sendername": "hr info",
+ "senderurl": "http://hr-hrinfo-live.cast.addradio.de/hr/hrinfo/live/mp3/128/stream.mp3",
+ "senderlogo": "../bilder/hr-info.png"
+ },
+ {
+ "senderid": 2,
+ "sendername": "radiobob",
+ "senderurl": "http://bob.hoerradar.de/radiobob-live-mp3-hq",
+ "senderlogo": "../bilder/radio-bob-logo-80.png"
+ },
+ usw.
+ ]
+ }
+}
+````
-MP3: http://bob.hoerradar.de/radiobob-live-mp3-hq
+#### Neuen Sender speichern
-Mobile Nutzung: http://bob.hoerradar.de/aac-radiobob
+Noch nicht realisiert.
-### FFH
+#### Änderungen an einem Sender speichern
-[Livestream-Übersicht](https://www.ffh.de/musik/webradios/stream-adressen.html)
+Noch nicht realisiert.
-128kbps http://mp3.ffh.de/radioffh/hqlivestream.mp3
+#### Sender löschen
-48kbps http://mp3.ffh.de/radioffh/livestream.aac
+Noch nicht realisiert.
+
+### Abspieler
+
+#### Abspielerliste lesen
+
+Aufruf
+
+````
+data/abspieler.json
+````
+
+Antwort
+
+````
+{
+ "abspielerliste": {
+ "titel": "Abspielerliste",
+ "inhalt": [
+ {
+ "abspielerid": 1,
+ "abspielername": "dieses Gerät",
+ "abspielerurl": "",
+ "abspielertyp":"lokal",
+ "abspielerbild": "",
+ "abspielerzustand":""
+ },
+ {
+ "abspielerid": 2,
+ "abspielername": "Raspberry Pi Wohnzimmer",
+ "abspielerurl": "",
+ "abspielertyp":"pirc",
+ "abspielerbild": "",
+ "abspielerzustand":"selected"
+ },
+ usw.
+ ]
+ }
+}
+````
+
+#### Neuen Abspieler speichern
+
+Noch nicht realisiert.
+
+#### Änderungen an einem Abspieler speichern
+
+Noch nicht realisiert.
+
+#### Abspieler löschen
+
+Noch nicht realisiert.
--
Gitblit v1.9.3