So passen Sie das Branding und die Designfarben der ownCloud-Weboberfläche an

Die zuverlässigste Methode zur Anpassung der ownCloud-Weboberfläche besteht darin, eine unterstützte Theme-JSON-Datei zu erstellen und ownCloud Infinite Scale auf dieses Theme zu verweisen. Sie müssen das Web-Frontend nicht neu erstellen, nur um Markennamen, Logos, Favicon, Anmeldehintergrund oder allgemeine Oberflächenfarben zu ändern. Im aktuellen Infinite Scale-Thememodell werden diese Elemente über eine Theme-Definition bereitgestellt, während Design-Tokens Farben und andere visuelle Werte steuern.

Diese Anleitung richtet sich an ownCloud Infinite Scale (oCIS) und dessen modernes ownCloud Web-Frontend. Sie ist nicht für das ältere ownCloud Server 10/11 PHP-Themesystem gedacht, das eine anwendungsbasierte Themestruktur und eine andere Konfiguration verwendet. Sowohl die Dokumentation der stabilen ownCloud Infinite Scale 8.2-Version als auch die Entwicklerdokumentation der Version 9.0 beschreiben denselben Ansatz: Sie erstellen ein Verzeichnis für benutzerdefinierte Themes und WEB_ASSET_THEMES_PATHwählen anschließend eine Theme-JSON-Datei aus WEB_UI_THEME_PATH. Weitere Informationen finden Sie in der offiziellen ownCloud Web-Dokumentation zur benutzerdefinierten Themeverwaltung .

Was Sie anpassen können, ohne ownCloud Web neu zu erstellen

Ein Standard-Organisationsdesign deckt die visuellen Änderungen ab, die die meisten Administratoren benötigen. Die Design-JSON-Datei definiert Produktname und Slogan, Pfade zu Logos und Favicon, den Hintergrund der Anmeldeseite sowie Webdesign-Elemente wie Marken-, Primär-, Hintergrund-, Text-, Rahmen- und Dateitypfarben. Dies ist der Bearbeitung kompilierter Frontend-Dateien vorzuziehen, da das Design eine separate Bereitstellungsressource bleibt und zusammen mit der Serverkonfiguration verwaltet werden kann.

Schritt 1: Erstellen Sie ein separates Themenverzeichnis und einen separaten Assets-Ordner.

Beginnen Sie damit, Ihr benutzerdefiniertes Design von den integrierten ownCloud-Elementen zu trennen. Ein einfaches Layout besteht aus einem Designverzeichnis mit dem entsprechenden Ordner themes.jsonsowie einem assetsUnterordner für Ihre Logos, Ihr Favicon und Ihr Anmeldebild. Der genaue Hostpfad ist Ihnen überlassen; wichtig ist nur, dass das Verzeichnis eingebunden oder anderweitig über den ownCloud-Webdienst zugänglich gemacht wird WEB_ASSET_THEMES_PATH.

Beispielhafte Dateistruktur für ein benutzerdefiniertes ownCloud-Web-Theme. Die Theme-Definition und die Bilddateien befinden sich in einem separaten Verzeichnis.

Eine Host-seitige Struktur könnte beispielsweise so aussehen:

/srv/owncloud/themes/
└── acme/
    ├── themes.json
    └── assets/
        ├── logo.svg
        ├── logo-white.svg
        ├── favicon.png
        └── login-background.jpg

Verwenden Sie Bildmaterial, das im jeweiligen Kontext gut lesbar bleibt. Ein dunkles Logo, das auf einer weißen Seite gut aussieht, kann vor einer dunklen oberen Leiste untergehen. Daher ist es oft sinnvoll, separate helle und dunkle Logovarianten anzubieten. Halten Sie den Hintergrund hinter den Anmelde-Steuerelementen möglichst schlicht. Branding sollte die Wiedererkennung verbessern, ohne die Lesbarkeit zu beeinträchtigen.

Schritt 2: Markennamen, Logopfade, Favicon und Anmeldehintergrund definieren

Die Theme-JSON-Datei bildet das Zentrum der Anpassung. Dieser commonAbschnitt enthält den gemeinsamen Markentext wie Name und Slogan. Unter clients.web.defaults„“ können Sie die Standard-Weblogos und den Anmeldehintergrund definieren. Das dokumentierte Schema von ownCloud verwendet separate Logo-Schlüssel für „“ topbar, favicon„“ und login„“.

Illustration des Branding-Bereichs einer Designdatei im Editor-Stil. Verwenden Sie die dokumentierte Objektstruktur aus dem folgenden Beispiel, anstatt die Illustration als Code zum Kopieren und Einfügen zu behandeln.

Ein minimaler Ausgangspunkt kann auf der unten aufgeführten unterstützten Struktur basieren. Achten Sie darauf, dass die Pfade mit dem URL-Pfad übereinstimmen, über den der Webdienst Ihre Designressourcen bereitstellt:

{
  "common": {
    "name": "Acme Cloud",
    "slogan": "Your files. Your workspace.",
    "logo": "themes/acme/assets/logo.svg",
    "urls": {
      "accessDeniedHelp": "",
      "imprint": "",
      "privacy": "",
      "accessibilityStatement": "",
      "universalAccessEasyLanguage": "",
      "universalAccessSignLanguage": ""
    }
  },
  "clients": {
    "android": {},
    "desktop": {},
    "ios": {},
    "web": {
      "defaults": {
        "appBanner": {},
        "logo": {
          "topbar": "themes/acme/assets/logo-white.svg",
          "favicon": "themes/acme/assets/favicon.png",
          "login": "themes/acme/assets/logo-white.svg"
        },
        "loginPage": {
          "backgroundImg": "themes/acme/assets/login-background.jpg"
        },
        "icons": {
          "universalAccess": "",
          "universalAccessEasyLanguage": "",
          "universalAccessSignLanguage": ""
        }
      },
      "themes": []
    }
  }
}

Gehen Sie nicht davon aus, dass alle Schlüssel bedenkenlos weggelassen werden können, nur weil der JSON-Parser die Datei akzeptiert. ownCloud weist darauf hin, dass einige obligatorische Theme-Schlüssel zur Laufzeit eingefügt werden, ein syntaktisch korrektes Theme aber dennoch semantisch fehlerhaft sein kann. Es empfiehlt sich, mit der Theme-Vorlage der von Ihnen verwendeten Infinite Scale-Version zu beginnen, nur die benötigten Branding-Änderungen vorzunehmen und die restliche Struktur an diese Version anzupassen.

Schritt 3: Ändern Sie die Designfarben mithilfe von Design-Tokens

Die Farbanpassung gehört in einen Themeneintrag unter „Farben“ clients.web.themes. Jedes Thema kann mit „dunkel“ angeben, ob es dunkel ist isDark, eine lesbare Farbbeschreibung bereitstellen nameund Design-Tokens überschreiben. Im colorPaletteBereich „Farben“ werden normalerweise die sichtbaren Markenfarben angepasst.

Beispiel für die von ownCloud Web verwendeten Farb-Tokens. Ändern Sie zuerst einen ausgewählten Satz, überprüfen Sie dann Kontrast und Hover-Zustände, bevor Sie die Palette erweitern.

Für ein dezentes Firmenthema könnten Sie mit einer kleinen Auswahl an Spielsteinen beginnen, anstatt jede verfügbare Farbe zu ändern:

{
  "isDark": false,
  "name": "Acme Light",
  "logo": {
    "topbar": "themes/acme/assets/logo-white.svg",
    "favicon": "themes/acme/assets/favicon.png",
    "login": "themes/acme/assets/logo-white.svg"
  },
  "designTokens": {
    "colorPalette": {
      "background-default": "#ffffff",
      "background-sidebar": "#f5f7fa",
      "background-hover": "#eef4fb",
      "border": "#d8e0e8",
      "swatch-brand-default": "#176B87",
      "swatch-brand-hover": "#12556C",
      "swatch-brand-contrast": "#ffffff",
      "swatch-primary-default": "#176B87",
      "swatch-primary-hover": "#12556C",
      "swatch-primary-contrast": "#ffffff",
      "text-default": "#102A33",
      "text-inverse": "#ffffff",
      "text-muted": "#526873",
      "icon-folder": "#176B87"
    }
  }
}

Der entscheidende Kompromiss liegt zwischen Konsistenz und Vollständigkeit. Eine einfache Änderung swatch-brand-defaultmag zwar schnell ein visuelles Ergebnis liefern, doch Hover-Effekte, Kontrast, Seitenleiste, Rahmen und Textelemente spiegeln möglicherweise weiterhin das Standarddesign wider. Andererseits kann das Überschreiben dutzender Elemente ohne vorherige Tests zu unleserlichen Kombinationen führen. Beginnen Sie daher in den meisten Fällen mit den Werten für Marke, Primärfarbe, Kontrast, Hintergrund, Text und Rahmen und erweitern Sie diese nur dort, wo die Standardwerte sichtbar mit Ihrem Design in Konflikt stehen.

Achten Sie besonders auf den Kontrast. Wenn Sie eine helle Markenfarbe wählen, kombinieren Sie diese mit einem kontrastreichen dunklen Element, anstatt weißen Text darauf zu platzieren. Testen Sie den Tastaturfokus, den Hover-Effekt, deaktivierte Steuerelemente, den Dunkelmodus (falls vorhanden) und kontrastreiche Modi, falls diese für Ihre Nutzer relevant sind.

Schritt 4: Benutzerdefiniertes Design einbinden und ownCloud auf themes.json verweisen

Sobald das Verzeichnis und die JSON-Datei bereit sind, konfigurieren Sie den Webdienst so, dass er sie lesen kann. Die beiden relevanten Umgebungsvariablen sind `/var/log/theme` WEB_ASSET_THEMES_PATH, die ownCloud den Speicherort des benutzerdefinierten Theme-Verzeichnisses mitteilt, und `/var/log/theme` WEB_UI_THEME_PATH, die die zu ladende Theme-JSON-Datei auswählt.

Illustration im Docker Compose-Stil zum Einbinden eines benutzerdefinierten Theme-Verzeichnisses und Konfigurieren der beiden ownCloud Web-Theme-Umgebungsvariablen. Passen Sie die Pfade an Ihre tatsächliche Bereitstellung an.

Eine Docker Compose-Bereitstellung könnte beispielsweise folgendes Muster verwenden:

services:
  ocis:
    image: owncloud/ocis:<your-tested-version>
    environment:
      WEB_ASSET_THEMES_PATH: /etc/ocis/themes
      WEB_UI_THEME_PATH: /etc/ocis/themes/acme/themes.json
    volumes:
      - ./themes:/etc/ocis/themes:ro

Der obige Bild-Tag dient lediglich als Platzhalter. Verwenden Sie für den Produktivbetrieb die exakte oCIS-Version, die Sie getestet haben, anstatt einen Platzhalter aus einem Beispiel zu kopieren. Nach Änderungen an der Umgebung oder den eingebundenen Dateien starten Sie den betroffenen oCIS-Dienst gemäß Ihrer Bereitstellungsmethode neu oder erstellen Sie ihn neu, damit die neue Konfiguration übernommen wird.

ownCloud dokumentiert ein wichtiges Ausweichverhalten: Wenn kein benutzerdefiniertes Theme angegeben ist oder das Laden des Themes fehlschlägt, wird das Standard-Theme „Unendliche Skala“ verwendet. Dieses Ausweichverhalten ist nützlich, da ein fehlender Pfad die Benutzeroberfläche nicht zwangsläufig unbrauchbar macht. Es bedeutet jedoch auch, dass das Erscheinen des Standard-ownCloud-Designs nach einem Neustart ein Hinweis darauf sein kann, dass Ihr benutzerdefiniertes Theme nicht geladen wurde.

So überprüfen Sie, ob das Branding tatsächlich geladen wurde

Prüfen Sie nicht nur die Anmeldeseite. Eine vollständige Überprüfung sollte alle Bereiche umfassen, in denen Nutzer Ihre Marke tatsächlich sehen. Öffnen Sie die Website in einer neuen Browsersitzung oder im privaten Modus, um zu vermeiden, dass zwischengespeicherte Daten den aktuellen Zustand verdecken.

• Prüfen Sie, ob die Anmeldeseite das erwartete Logo und den erwarteten Hintergrund verwendet.
• Nach dem Anmelden überprüfen Sie bitte, ob das Logo in der oberen Leiste korrekt ist und sich gut vom Hintergrund abhebt.
• Überprüfen Sie den Browser-Tab auf das benutzerdefinierte Favicon.
• Öffnen Sie den Dateibereich und überprüfen Sie die primären Schaltflächen, Hover-Zustände, Seitenleistenfarben, Ordnersymbole und den Textkontrast.
• Wenn Sie helle und dunkle Designs anbieten, wechseln Sie zwischen ihnen und überprüfen Sie beide unabhängig voneinander.
• Prüfen Sie mindestens eine schmale Browserbreite, damit ein breites Logo die responsive obere Leiste nicht überfrachtet.

Wenn das benutzerdefinierte Design nicht angezeigt wird

Das Standard-ownCloud-Theme wird weiterhin geladen.

Überprüfen Sie zunächst die Pfade innerhalb des laufenden Containers oder Dienstes, nicht nur auf dem Host. Der Pfad WEB_ASSET_THEMES_PATHmuss auf das Theme-Root-Verzeichnis verweisen, wie es vom Webdienst gesehen wird, und WEB_UI_THEME_PATHauf die tatsächliche JSON-Datei in dieser Umgebung. Ein Host-Pfad, der nie in den Container eingebunden wurde, kann von ownCloud nicht gelesen werden.

Die JSON-Datei wird geladen, aber ein Bild fehlt.

Überprüfen Sie den Pfad der Assets themes.json, die Groß-/Kleinschreibung des Dateinamens und ob die Datei im Verzeichnis der benutzerdefinierten Designs vorhanden ist. Die Entwicklertools Ihres Browsers können helfen, eine fehlerhafte Asset-Anfrage von einem Designproblem zu unterscheiden. Wenn die Designfarben geladen werden, ein Logo jedoch nicht, ist das Design selbst möglicherweise gültig, der Asset-Pfad jedoch falsch.

Die Seite ist zwar im Corporate Design gestaltet, aber die Farben wirken uneinheitlich.

Dies bedeutet in der Regel, dass nur ein Teil der Farbpalette überschrieben wurde. Fügen Sie die zugehörigen Hover- und Kontrast-Tokens hinzu und testen Sie erneut. Beheben Sie das Problem einer einzelnen unleserlichen Schaltfläche nicht, indem Sie unzusammenhängende Text- oder Hintergrund-Tokens umfassend ändern; nehmen Sie stattdessen die kleinstmögliche, sinnvolle Änderung vor und überprüfen Sie diese in der gesamten Benutzeroberfläche.

Ein Theme funktioniert in einer Version, sieht aber nach einem Upgrade fehlerhaft aus.

Theme-Tokens und das Verhalten des Frontends können sich ändern. Vergleichen Sie vor einem Upgrade Ihrer Produktionsumgebung Ihr benutzerdefiniertes Theme mit der Vorlage und der Dokumentation der Zielversion von oCIS. Die Dokumentation zur benutzerdefinierten Webkonfiguration von ownCloud erläutert außerdem den Unterschied zwischen unterstützten Konfigurationen/benutzerdefinierten Assets und der Bereitstellung vollständig benutzerdefinierter, kompilierter Web-Assets.

Sollten Sie stattdessen kompilierte Web-Assets bearbeiten?

Für Standard-Branding ist dies in der Regel nicht geeignet. Ein benutzerdefiniertes Theme ist besser geeignet, wenn Sie Namen, Logos, Hintergründe und Designelemente ändern möchten, dabei aber die unterstützte Web-Benutzeroberfläche beibehalten wollen. Vollständig selbst kompilierte Assets sind nur dann sinnvoll, wenn Sie ein wirklich modifiziertes Frontend entwickeln oder vertreiben, das sich nicht durch Themes oder unterstützte Asset-Überschreibungen ausdrücken lässt. Dieser Ansatz ist mit höheren Wartungskosten verbunden, da Sie dafür verantwortlich sind, Ihre benutzerdefinierte Version mit zukünftigen Änderungen an ownCloud Web kompatibel zu halten.

Eine praktische Produktionscheckliste

• Benutzerdefinierte Designdateien sollten außerhalb der integrierten Anwendungsverzeichnisse gespeichert werden.
• Gehen Sie von der für Ihre installierte oCIS-Version dokumentierten Themenstruktur aus.
• Verwenden Sie separate Logovarianten, wenn helle und dunkle Oberflächen dies erfordern.
• Zuerst sollten einige wenige Design-Tokens überschrieben werden, darunter Hover- und Kontrastwerte.
• Das Theme-Verzeichnis sollte nach Möglichkeit schreibgeschützt eingebunden werden.
• Setzen Sie sowohl WEB_ASSET_THEMES_PATHals WEB_UI_THEME_PATHauch auf Pfade, die innerhalb des Dienstes sichtbar sind.
• Nach Änderungen an der Bereitstellung muss der Web-/oCIS-Dienst neu gestartet oder neu erstellt werden.
• Überprüfen Sie Login, obere Leiste, Favicon, Dateibereich, responsives Layout und alle von Ihnen verwendeten dunklen/kontrastreichen Designs.
• Testen Sie das Theme vor jedem größeren ownCloud Infinite Scale-Upgrade erneut.

Bei aktuellen Infinite Scale-Bereitstellungen ermöglicht dieser Ansatz mit Designdateien Administratoren eine klare Trennung zwischen Anwendungscode und visueller Identität. Wichtig ist, das Design als versionierte Bereitstellungsressource zu behandeln: Verwenden Sie das von Ihrer ownCloud-Version unterstützte Schema, halten Sie Ihre Bildpfade vorhersehbar, ändern Sie Farben über Design-Tokens anstatt über Ad-hoc-Anpassungen im Frontend und überprüfen Sie das Ergebnis auf der gesamten Weboberfläche, anstatt den Erfolg nur anhand eines einzelnen Bildschirms zu beurteilen.