Roundcube/Skins

Roundcube/Skins - Gestaltung des Roundcube-Frontends

Beschreibung

Ein großer Vorteil von Roundcube ist sicherlich die strikte Trennung von Funktionalität und Erscheinungsbild. Dadurch können Sie Ihr individuelles Skin mit so vielen oder so wenigen Funktionen erstellen, wie Sie möchten. Im Folgenden wird erläutert, wie Skins funktionieren und welche Befehle und Objekte in der Template-Engine zur Verfügung stehen.

Funktionsweise

Wie funktionieren Skins?

Ein Skin ist eine Sammlung von HTML-basierten Vorlagen mit CSS-Stylesheets und allem, was sonst noch nötig ist, damit Roundcube ansprechend aussieht. Alle zu einem Skin gehörenden Dateien werden in einem Unterordner des Verzeichnisses skins/ gespeichert, dessen Name gleichzeitig den Namen des Skins angibt.

Als letzten Schritt bei der Bearbeitung einer Anfrage des Clients liest die Template-Engine von Roundcube eine Vorlagendatei aus dem aktiven Skin ein und ersetzt bestimmte Platzhalter durch den tatsächlichen Inhalt. In den Dev Docs gibt es ein übersichtliches Schema, das diesen Vorgang erläutert.

Aufbau

Bestandteile eines Skins

Im Unterordner „skin“ werden alle Vorlagen aus dem Unterordner templates/ geladen, wobei ihre Dateinamen fest codiert sind. Alle anderen Dateien sind individuell und werden in den Vorlagen referenziert; daher können sie individuell benannt werden. Roundcube wird mit einem Standard-Skin ausgeliefert (skins/larry/), der einen Blick wert ist, um zu sehen, woraus ein vollständiger Skin besteht.

Dies ist die Mindeststruktur, die ein Skin bieten sollte (eine Liste der Vorlagen findest du bei den vorhandenen Core-Skins):

  skins/<skinname>/
    composer.json
    meta.json
    thumbnail.png
    styles.css
    images/
    templates/
      about.html [...]

Plugins zur Anpassung

Plugins zur Anpassung des Erscheinungsbilds

Ab Roundcube-Version 1.5.0 benötigen einige Roundcube-Plugins zusätzliche Skin-Informationen, um korrekt angezeigt zu werden. Diese befinden sich im Unterordner skins/ des jeweiligen Plugins. Um Skin-Entwicklern die Unterstützung von Plugins zu erleichtern, wird ein zweiter Speicherort innerhalb des Skin-Ordners unterstützt. Erstellen Sie in Ihrem Skin-Ordner einen Unterordner namens plugins und anschließend Unterordner für jedes Plugin, das Sie unterstützen möchten:

  skins/<skinname>/
    plugins/
      archive/
      markasjunk/
          markasjunk.css
      managesieve/
          managesieve.css
          templates/
              managesieve.html [...]
      <pluginname>/
          templates/

Der Inhalt jedes Plugin-Unterordners sollte mit dem Inhalt eines Skin-Unterordners im ursprünglichen Plugin-Ordner übereinstimmen. Der ursprüngliche Plugin-Ordner hat Vorrang vor diesem Speicherort.

meta.json

Diese Datei enthält einige Metainformationen zum Skin, die zusammen mit der Datei thumbnail.png im Bereich zur Skin-Auswahl auf der Seite mit den Benutzereinstellungen angezeigt werden. Die Metadatei liegt ausschließlich im JSON-Format (UTF-8!) vor und enthält die folgenden Eigenschaften:

{
  "name": "<the skin name>",
  "author": "<the skin author's name>",
  "url": "<link to author's website>",
  "license": "<skin license, e.g. Creative Commons, BSD, GPL>",
  "license-url": "<link to license text>",
  "localization": true,
  "config": [],
  "meta": {},
  "links": {}
}

• localization – Weist Roundcube an, die Lokalisierungsdateien aus dem Verzeichnis localization/ im Skin-Verzeichnis zu lesen. Wenn Ihr Skin keine zusätzlichen Übersetzungsbezeichnungen benötigt, setzen Sie den Wert einfach auf false. Skins sollten dieselbe Struktur und dasselbe Format der Lokalisierungsdateien verwenden wie das Plugin-System.
• config – Hiermit können Sie beliebige Konfigurationsoptionen festlegen (und erzwingen).
• meta – (Hinzugefügt in Version 1.4) Ein JSON-Objekt mit Meta-Tags, die in das meta-Vorlagenobjekt eingefügt werden sollen, z. B.

...
"meta": {
  "<name>": "<content>",
  "viewport": "width=device-width, initial-scale=1.0, shrink-to-fit=no, maximum-scale=1.0"
  "theme-color": "#ffffff",
},
...

Sie können zusätzliche Parameter für das Meta-Tag wie folgt festlegen:

...
"<name>": {"content": "<content>", "id": "<id>"},
...

Sie können mehrere Tags mit demselben Namen wie folgt definieren:

...
"<name>": [{"content": "<content>", "id": "<id>"}, "<content>"],
...

• links – (Hinzugefügt in 1.4) Ein JSON-Objekt mit Link-Tags, die in das links-Vorlagenobjekt eingefügt werden sollen; das „links“-Objekt hat dieselbe Struktur wie das „meta“-Objekt, z. B.

...
"links": {
  "<rel>": "<href>",
  "apple-touch-icon": {"sizes": "180x180", "href": "/apple-touch-icon.png"},
  "icon": [
    {"type": "image/png", "sizes": "32x32", "href": "/favicon-32x32.png"},
    {"type": "image/png", "sizes": "16x16", "href": "/favicon-16x16.png"}
  ],
  "manifest": "/site.webmanifest",
  "mask-icon": {"href": "/safari-pinned-tab.svg", "color": "#5bbad5"},
  "stylesheet": [
    "/branding.css",
    "/layout.css"
  ]
}
...

Skins erweitern

Ab Roundcube-Version 0.9.0 ermöglicht das Skinning-System, dass ein Skin auf einem anderen Skin aufbaut. Dadurch ist es nun sehr einfach, benutzerdefinierte Skins zu erstellen, die nur geringfügige Änderungen an den Standard-Skins vornehmen, die im Roundcube-Kernpaket enthalten sind. Um einen Skin zu erstellen, der auf einem anderen aufbaut, benennen Sie den Basis-Skin einfach mit dem Label extends in der Datei „meta.json“ Ihres Skins:

{
  "extends": "larry",
  ...
}

Dadurch wird im Wesentlichen der Basis-Skin-Ordner zum Suchpfad für Vorlagen und Assets hinzugefügt. Nun muss der erweiterte Skin nur noch die Vorlagen oder Include-Dateien bereitstellen, die sich tatsächlich vom Basis-Skin unterscheiden. Wenn Sie beispielsweise lediglich eine zusätzliche CSS-Datei hinzufügen möchten, die bestimmte Stile des Larry-Themes überschreibt, können Sie die Datei „include/links.html“ in Ihrem Skin überschreiben und ein weiteres Stylesheet hinzufügen. Dann kann die benutzerdefinierte Skin-Datei sogar das entsprechende Element aus dem Basis-Theme einbinden, indem das Attribut skinPath angegeben wird:

<roundcube:include file="/includes/links.html" skinPath="skins/larry" />
<link rel="stylesheet" type="text/css" href="/customstyles.css" />

Eine vorhandene Kopfzeile aufheben

Wenn Sie beim Erweitern eines Skins ein in dem übergeordneten Skin definiertes Meta- oder Link-Tag deaktivieren möchten, können Sie dies wie folgt tun:

{
  "name": "MySkin",
  "extends": "elastic",
  ...
  "meta": {
    "viewport": false
  }
}

Skins erweitern – Elastisch

Um ein Skin zu erstellen, das auf „elastic“ aufbaut, benennen Sie das Basis-Skin einfach mit der Bezeichnung extends in der Datei „meta.json“ Ihres Skins:

{
  "extends": "elastic",
  ...
}

Wenn Sie beispielsweise lediglich eine zusätzliche CSS-Datei hinzufügen möchten, die bestimmte Stile des Elastic-Themes überschreibt, können Sie in Ihrem Skin die Datei „templates/includes/layout.html“ erstellen bzw. überschreiben und ein weiteres Stylesheet hinzufügen. Anschließend kann die benutzerdefinierte Skin-Datei sogar das entsprechende Element aus dem Basis-Theme einbinden, indem Sie das Attribut skinPath angeben:

<roundcube:include file="includes/layout.html" skinPath="skins/elastic" />
<link rel="stylesheet" type="text/css" href="/customstyles.css" />

Template-Engine

Alle Vorlagen sind reine XHTML-Dateien und enthalten spezielle Tags der Form <roundcube: .../>, die ausgewertet und durch den entsprechenden Inhalt ersetzt werden. Mithilfe dieser speziellen Tags können Sie auch andere Vorlagendateien einbinden und bedingte Blöcke erstellen. Die Syntax und eine detaillierte Liste der verfügbaren Tags finden Sie auf der Seite Skin Markup.

Wenn dies in der Konfiguration aktiviert ist ($rcmail_config['skin_include_php']), wird auch PHP-Code innerhalb der Vorlagen ausgeführt. Alle Verweise wie Bilder, Stylesheets und eingebundene Dateien müssen mit absoluten Pfaden (beginnend mit /) definiert werden, wobei / das Stammverzeichnis des Skin-Unterordners ist.

Vorlagen

Vorlagen und ihre Verwendung

login.html

Es versteht sich von selbst, dass diese Vorlage zur Anzeige der Anmeldeseite dient.

mail.html

Die Standardansicht des E-Mail-Bereichs von Roundcube. Diese Vorlage sollte die Ordner- und Nachrichtenliste sowie möglicherweise den Vorschaubereich zur Inline-Anzeige einer Nachricht enthalten. Der Vorschaubereich ist eigentlich ein Iframe, in dem eine E-Mail-Nachricht angezeigt wird, die mit der Datei messagepreview.html gerendert wurde.

message.html

Dient zur Anzeige der ausgewählten Nachricht einschließlich aller Kopfzeilen und Anhänge. Die Nachrichtenanzeige wird im gesamten Browserfenster geöffnet und erfordert zudem Navigationselemente, um zur Hauptansicht zurückzukehren.

messagepreview.html

Ähnlich wie message.html, wird jedoch für die Inline-Anzeige einer Nachricht im Vorschaufenster verwendet. Hier sind keine Navigationselemente erforderlich.

Teil der Nachricht

Diese Vorlage dient zur Darstellung des Rahmens, in dem ein angehängter Nachrichtentext angezeigt wird. Sie enthält im Wesentlichen ein Objekt, in das der eigentliche Anhang geladen wird, sowie einen Download-Link.

messageprint.html

Beim Öffnen einer E-Mail-Nachricht zum Drucken wird diese Vorlage geladen. Sie sollte einige für den Druck optimierte Stylesheets enthalten und keine Navigationselemente aufweisen. Sie wird in einem neuen Fenster geöffnet und enthält möglicherweise einen Link zum Schließen des Fensters.

compose.html

Diese Vorlage enthält alle Formularelemente, die zum Verfassen einer E-Mail-Nachricht erforderlich sind. Kopiere sie aus dem Standard-Skin, da es sonst ziemlich kompliziert werden könnte :-)

Adressbuch

Die Hauptansicht des Adressbuchbereichs wird durch diese Vorlage gesteuert. Ähnlich wie die E-Mail-Ansicht zeigt sie die Liste der Kontakte, Adressquellen und Gruppen an und lädt die Kontaktdetails in einem Iframe.

showcontact.html

Dient zur Anzeige aller Details des ausgewählten Kontaktdatensatzes.

editcontact.html

Das Bearbeitungsformular für einen Kontaktdatensatz wird mithilfe dieser Vorlage dargestellt. Es wird außerdem in den Iframe geladen, der von der Hauptansicht des Adressbuchs definiert wird.

addcontact.html

Sie ähnelt stark der Vorlage editcontact.html, zeigt jedoch wahrscheinlich andere Titel und Schaltflächen an, die der Aufgabe der Erstellung eines neuen Kontaktdatensatzes entsprechen.

importcontacts.html

Der gesamte Importvorgang wird durch diese Vorlage gestaltet. Der Hauptinhalt ist fest codiert, doch diese Vorlage stellt die Rahmenbedingungen wie Titel und Navigation für diese Schritte bereit.

settings.html

Der Bereich für alle Benutzereinstellungen wird durch diese Vorlage definiert. Er besteht aus einer Liste von Einstellungsgruppen und enthält außerdem die Navigation zu anderen Einstellungsbereichen wie Identitäten und Ordnerverwaltung.

Einstellungen bearbeiten.html

Diese Vorlage stellt das Formular zum Ändern einer bestimmten Gruppe von Benutzereinstellungen dar. Sie wird in einen iframe geladen, der in der Hauptvorlage settings.html definiert ist.

identities.html

Die Liste der Absenderidentitäten wird mithilfe dieser Vorlage verwaltet. Sie hat eine ähnliche Struktur wie die Vorlage addressbook.html und zeigt eine Liste der gespeicherten Identitäten sowie einen iframe zum Laden des Bearbeitungsformulars an.

editidentity.html

Enthält das Bearbeitungsformular zum Anlegen oder Ändern eines Absenderidentitätsdatensatzes und wird in einem iframe geladen, sodass keine Navigationselemente erforderlich sind.

managefolders.html

Die Vorlage, die alle Elemente enthält, die zur Verwaltung der IMAP-Ordner des aktuellen Postfachs benötigt werden. Sie ist Teil des Abschnitts „Einstellungen“ und sollte Verweise auf andere Teile dieses Abschnitts enthalten.

plugin.html

Dies ist eine allgemeine Vorlage, die zum Darstellen des Inhalts eines Plugins verwendet wird. Die meisten Plugins verfügen über eigene Vorlagen; falls dies jedoch nicht der Fall ist, wird diese Vorlage geladen.

error.html

Nicht zuletzt dient diese Vorlage dazu, Meldungen über schwerwiegende Fehler anzuzeigen, die den ordnungsgemäßen Betrieb des Systems verhindern.

Skins veröffentlichen

Wir empfehlen Skin-Entwicklern dringend, den Code in einem Git- oder SVN-Repository zu verwalten. Am besten erstellen Sie dafür für jedes einzelne Skin ein eigenes Repository. Es gibt zahlreiche Plattformen, die solche Repositorys kostenlos zur Verfügung stellen (z. B. Github, Gitorious oder Sourceforge).

Ab Roundcube 1.5.0 und Version 0.3.0 des Roundcube-Plugin-Installers können Skins über Composer verteilt werden. Veröffentlichen Sie Ihren Skin auf packagist.org, dem Standard-Repository für PHP-Pakete. Als Skin-Entwickler können Sie Ihr Skin auf dieser Plattform veröffentlichen. Durch die Verwendung von Git- oder SVN-Repositorys gelangt die dort eingecheckte neueste Version automatisch in das Repository und schließlich zu den Nutzern.

Beispiel für die Datei „composer.json“ für Skins

{
    "name": "<your-vendor-name>/<skin-name>",
    "type": "roundcube-skin",
    "license": "GPL-3.0+",
    "require": {
        "roundcube/plugin-installer": ">=0.3.0"
    }
}

Siehe auch

1. Skin-Markup