FTUI Widget Calview

Das Calview Widget ist ein Widget für FHEM Tablet UI V2, welches Einträge aus einem CALVIEW-Device anzeigen kann.

Attribute

Allgemeine Attribute

Attribut	Beschreibung	Standard-Wert	Beispiel
data-device	Name des CALVIEW-Devices, dessen Reading dargestellt werden sollen
data-get	Welche Termine sollen angezeigt werden? Mögliche Werte: all, today, tomorrow	STATE	data-get="all"
data-start	Termine von heute oder heute+morgen nicht anzeigen. Gilt nur für data-get="all". Mögliche Werte: none, all, notoday und notomorrow	all	data-start="notoday"
data-max	Bestimmt, wie viele Termine angezeigt werden	10	data-max="20"
data-class	CSS-Klasse(n); alle im FTUI verfügbaren class-Werte nutzbar		data-class="left-align small"
data-color	Textfarbe als HEX-Angabe oder Farbname		data-color="#ff0000"
data-background-color	Hintergrundfarbe als HEX-Angabe oder Farbname		data-background-color="#0000ff"
data-detail	Array von CALVIEW-Details, die angezeigt werden sollen		data-detail='["bdate","btime","summary"]'
data-detailwidth	Breite der einzelnen Spalten in %		data-detailwidth='["20","20","60"]'
data-dateformat	Formatierung der Datumsanzeige (mit/ohne Jahreszahl)	long	data-dateformat="short"
data-timeformat	Formatierung der Uhrzeitanzeige (mit/ohne Sekunden)	long	data-timeformat="short"
data-showempty	Infotext anzeigen, wenn keine Termine vorhanden sind Mögliche Werte: true, false oder individueller Text	true	data-showempty="Derzeit keine Termine"
data-oneline	Zu langen Text einer Spalte abschneiden (... wird ans Ende gesetzt) statt umzubrechen	no	data-oneline="yes"
data-sourcecolor	Als Textfarbe eines Eintrages die sourcecolor verwenden (s. Beispiel)	no	data-sourcecolor="yes"

Nahende Termine hervorheben

Optional können nahende Termine optisch hervorgehoben werden; die Aktivierung erfolgt durch das Verwenden von data-daysleft-values. Die anderen Attribute sind allesamt optional. Fehlt ein optionales Attribut oder enthält leere Einträge, wird der für normale Termine gültige Wert angenommen; andernfalls wird der für normale Termine gültige Wert durch den angegebenen Wert ersetzt.

Attribut	Beschreibung	Standard-Wert	Beispiel
data-daysleft-values	Array von Tagen bis zum Termin (aufsteigend)		data-daysleft-values='[1,3,8]'
data-daysleft-classes	Array von CSS-Klasse(n) - analog zu data-daysleft-values ; optional		data-daysleft-classes='["blink","",""]'
data-daysleft-colors	Array von Textfarben - analog zu data-daysleft-values ; optional		data-daysleft-colors='["red","yellow","green"]'
data-daysleft-background-colors	Array von Hintergrundfarben - analog zu data-daysleft-values ; optional		data-daysleft-background-colors='["gray","lightgray","white"]'

Titelzeile

Optional kann eine zusätzliche Tabellenzeile als Titelzeile dargestellt werden; die Aktivierung erfolgt durch das Verwenden von data-header. Die anderen Attribute sind allesamt optional.

Attribut	Beschreibung	Standard-Wert	Beispiel
data-header	Array - analog zu data-detail		data-header='["am","um","Zusammenfassung"]'
data-header-class	CSS-Klasse(n) - analog zu data-class ; optional		data-header-class="large"
data-header-color	Textfarbe - analog zu data-color ; optional		data-header-color="hotpink"
data-header-background-color	Hintergrundfarbe - analog zu data-background-color ; optional		data-header-background-color="white"

Anwendungsbereich für class-Attribute

Termine werden jeweils als einzelne Zeile mit der definierten Anzahl von Spalten dargestellt. Angegebene Werte für data-header-class, data-class bzw. data-daysleft-classes können also entweder einmalig einer kompletten Zeile oder aber einzeln jeder Spalte zugewiesen werden. Abhängig hiervon kann sich die Darstellung ändern; beispielsweise blinkt im einen Fall eine ganze Zeile; im anderen Fall nur der Vordergrund.

Attribut	Beschreibung	Standard-Wert	Beispiel
data-class-usage	Anwendungsbereich festlegen	col	data-class-usage="row"

Swiper-Darstellung

Um z.B. viele Termine im Zugriff zu haben, aber nur wenig Platz zu benötigen, kann die Swiper-Darstellung genutzt werden. Hierbei stellt jeder Termin eine eigene Swiper-Seite dar; zwischen diesen kann manuell oder automatisch gewechselt werden.

Attribut	Beschreibung	Standard-Wert	Beispiel
data-swiperstyle	Legt fest, ob die Swiper-Darstellung genutzt werden soll	no	data-swiperstyle="yes"
data-swiper-autoplay	Zeit in ms (!), nach der zum nächsten Termin gewechselt wird	kein autoplay	data-swiper-autoplay="2000"
data-swiper-effect	Effekt für den Wechsel zum nächsten Termin festlegen Mögliche Werte: flip bzw. slide	flip	data-swiper-effect="slide"
data-swiper-pagination	Schnellzugriff unterhalb der Termine einblenden	yes	data-swiper-pagination="no"

CSS Klassen

Falls die Formatierungsmöglichkeiten unter Verwendung der class- bzw. color-Attribute nicht ausreichen, kann noch auf vorgegebene CSS-Klassen zurückgegriffen werden. Diese sind laut der folgenden Tabelle jedem calview-Element automatisch zugeordnet. Um sie mit Leben zu füllen, müssen die gewünschten CSS-Klassen in der user-spezifischen css-Datei angelegt werden.

Klasse	Beschreibung
calview	gilt für den ganzen Kalender
calview-row-header	gilt für die komplette Headerzeile
calview-col-header	gilt für eine einzelne Headerspalte
calview-row	gilt für eine komplette Zeile eines Termins, wenn kein daysleft-Fall vorliegt
calview-col	gilt für eine einzelne Spalte eines Termins, wenn kein daysleft-Fall vorliegt
calview-row-daysleft-<n>	gilt für eine komplette Zeile eines Termins, wenn ein daysleft-Fall vorliegt; <n> entspricht dem Eintrag im daysleft-Array - beginnend mit 1
calview-col-daysleft-<n>	gilt für eine einzelne Spalte eines Termins, wenn ein daysleft-Fall vorliegt; <n> entspricht dem Eintrag im daysleft-Array - beginnend mit 1

Beispiele

Einfaches Beispiel

Folgendes Beispiel zeigt die nächsten zehn Kalender-Einträge in einer unformatierten Liste an.

<div data-type="calview"
     data-device="myCalView"
     data-get="all"
     data-detail='["bdate","btime","summary"]'
     data-detailwidth='["30","30","40"]'></div>

Geburtstagskalender mit Berechnung des Alters

Das Beispiel zeigt einen Geburtstagskalender der Geburtstage ab heute - eine oft gewünschte Funktion. Das Lebensalter (Anna wird 35 Jahre) wird berechnet und angezeigt.

Anders als in vielen im FHEM-Forum und im Internet zu findenden Beispielen kommt es ohne zusätzlich einzubindende PERL-Funktion(en) aus.

Die iCal-Datei (hier: test.ics) der Geburtstage hat so auszusehen - meine Mutter wurde am 24. Mai 1931 geboren:

BEGIN:VCALENDAR
PRODID:-//calcurse//NONSGML v4.0.0//EN
VERSION:2.0
BEGIN:VEVENT
DTSTART:19310524
DTEND:19310524
RRULE:FREQ=YEARLY
SUMMARY: Geburtstag meiner Mutter
DESCRIPTION: 1931
END:VEVENT
END:VCALENDAR

Wichtig ist hier insbesondere "DESCRIPTION", hier muss das Geburtsjahr stehen: Diese Angabe ist Basis für die Berechnung des Lebensalters.

Dieser Kalender, der natürlich nicht nur den Geburtstag der Mutter hat, muss in fhem.cfg eingebunden sein:

defmod Testkalender Calendar ical file FHEM/test.ics 86400
attr Testkalender hideOlderThan 3600s

Um den Kalender anzusehen, benötigen wir in fhem.cfg noch eine CalView-Device:

defmod TestkalenderView CALVIEW Testkalender 1
attr TestkalenderView isbirthday 1
attr TestkalenderView modes next
attr TestkalenderView yobfield _description

Abschließend muss in einer FTUI-Seite des FHEM Tablet UI eine Gridster-Kachel gefunden werden, in die das folgende gehört:

<!-- https://forum.fhem.de/index.php?topic=91903.new;topicseen#new #15 -->
    <div data-type="calview"
     data-device="TestkalenderView"
     data-get="all"
     data-max="5"
     data-detail='["bdate","summary","age"]'
     data-detailwidth='["25","70","5"]'
     data-showempty="true"
     data-dateformat="short"
     data-timeformat="short"
     data-oneline="yes"
     data-class='left-align'
     >
</div>

Anmerkung: Screenshot fehlt noch. Curt (Diskussion) 04:11, 14. Okt. 2018 (CEST)

Einfärbung von Kalendereinträgen (sourcecolor)

Folgendes Beispiel soll die unterschiedliche Einfärbung von Kalendereinträgen bei Verwendung mehrerer Kalender zeigen.

Vorausgesetzt werden:

• eine Anzahl von beliebigen ics-Dateien, auf die FHEM Zugriff hat; in unserem Beispiel test1.ics und test2.ics.
• ein Calendar-Device pro ics-Datei; in unserem Beispiel Testkalender1 und Testkalender2
• ein CALVIEW-Device zum Sammeln der Termine aus den einzelnen Kalendern; in unserem Beispiel TestkalenderView

defmod Testkalender1 Calendar ical file test1.ics 86400
attr Testkalender1 hideOlderThan 3600s

defmod Testkalender2 Calendar ical file test2.ics 86400
attr Testkalender2 hideOlderThan 3600s

defmod TestkalenderView CALVIEW Testkalender1,Testkalender2 1
attr TestkalenderView modes next

Um Kalendereinträge je nach Kalender eingefärbt darzustellen, muss das sourcecolor-Attribut beim CALVIEW-Device gesetzt werden.

attr TestkalenderView sourcecolor Testkalender1:green,Testkalender2:yellow

Nach dem Setzen vom sourcecolor-Attribut sollte man das CALVIEW-Device aktualisieren, ansonsten wird die eingestellte sourcecolor erst mit der jeweils nächsten Kalenderaktualisierung aktiv.

set TestkalenderView update

Das aktualisierte CALVIEW-Device sollte nun in den t_<nnn>_sourcecolor-Readings den gewünschten Farbwert enthalten.

Die gewünschte Darstellung im FTUI erreicht man, indem man das Widget-Attribut data-sourcecolor verwendet und auf den Wert yes setzt.

• In früheren Widget-Versionen musste zusätzlich im Widget-Attribut data-detail die Spalte sourcecolor mit der Breite 0 enthalten sein; dies ist nicht mehr notwendig.

<div data-type="calview"
     data-device="TestkalenderView"
     data-get="all"
     data-detail='["weekdayname","bdate","summary"]'
     data-detailwidth='["10","20","70"]'
     data-sourcecolor="yes"></div>

Anzumerken bleibt noch, dass das Widget-Attribut data-color bei Verwendung von sourcecolor ignoriert wird. Die data-daysleft-Attribute allerdings haben Vorrag vor sourcecolor und führen - je nach daysleft-Konfiguration - zum Überschreiben der sourcecolor.

Beispiel unter Verwendung der vorgegebenen CSS-Klassen

Folgendes Beispiel soll den Einsatz der vorgegebenen CSS-Klassen, die jedem calview-Element automatisch zugeordnet sind, zeigen.

Zunächst einmal wird das folgende calview-widget deklariert. Es stellt einen Kalender mit einer Titelzeile und maximal 15 Terminen mit je drei Spalten dar. Termine, die in weniger als 17 Tagen anstehen, sollen speziell behandelt werden; Termine, die in weniger als 3 Tagen anstehen, sollen (zusätzlich) blinken. Bis auf das blink-Feature ist keine Information zur Formatierung der Termine enthalten. Folglich wird ein praktisch unformatierter Kalender dargestellt.

<div data-type="calview" data-device="TestkalenderView"
                         data-class-usage="row"
                         data-daysleft-values='[2,9,16]'
                         data-daysleft-classes='["blink","",""]'
                         data-detail='["weekdayname","bdate","summary"]'
                         data-detailwidth='["10","20","70"]'
                         data-get="all"
                         data-header='["","am","Zusammenfassung"]'
                         data-max="15"
                         data-oneline="yes"
                         data-showempty="Derzeit keine Termine"></div>

Legt man in der user-spezifischen css-Datei zusätzlich folgende CSS-Klassen an, ändert sich die Darstellung des Kalenders grundlegend. Der ganze Kalender bekommt einen hellblauen Hintergrund mit abgerundeten Ecken und schwarzer Schrift. Die Titelzeile wird fett und mit leicht vergrößerter Schrift dargestellt. Normale Termine sind grau hinterlegt; Termine in max. 2 Tagen sind rot hinterlegt und blinken; Termine in max. 9 Tagen sind gelb hinterlegt; Termine in max. 16 Tagen sind grün hinterlegt - jeweils mit abgerundeten Ecken je Zeile.

.calview {
  background-color: #99ccff;
  border-radius: 8px;
  padding: 4px;
  color: black;
}

.calview-row-header {
  border-radius: 8px;
  font-size:125%;
  font-weight: bold;
}

.calview-col-header {
  text-align: left;
}

.calview-row {
  background-color: #c0c0c0;
  border-radius: 8px;
  padding-left: 4px;
  padding-right: 4px;
}

.calview-col {
  text-align: left;
}

.calview-row-daysleft-1 {
  background-color: #ff8080;
  border-radius: 8px;
  padding-left: 4px;
  padding-right: 4px;
}

.calview-col-daysleft-1 {
  text-align: left;
}

.calview-row-daysleft-2 {
  background-color: #ffffb3;
  border-radius: 8px;
  padding-left: 4px;
  padding-right: 4px;
}

.calview-col-daysleft-2 {
  text-align: left;
}

.calview-row-daysleft-3 {
  background-color: #99ff99;
  border-radius: 8px;
  padding-left: 4px;
  padding-right: 4px;
}

.calview-col-daysleft-3 {
  text-align: left;
}

Die hier angelegten CSS-Klassen gelten für jeden Kalender; über CSS-Selektoren können natürlich auch für jeden Kalender eigene CSS-Klassen angelegt werden.