Jak dostosować branding i kolory motywu interfejsu użytkownika ownCloud Web

Najbardziej niezawodnym sposobem dostosowania obecnego interfejsu internetowego ownCloud jest utworzenie pliku JSON obsługiwanego motywu i skierowanie go do ownCloud Infinite Scale. Nie trzeba przebudowywać front-endu, aby zmienić nazwę marki, logo, ikonę favicon, tło logowania lub kolory interfejsu. W obecnym modelu motywów Infinite Scale elementy te są dostarczane poprzez definicję motywu, podczas gdy tokeny projektowe kontrolują kolory i inne wartości wizualne.

Ten przewodnik został napisany dla ownCloud Infinite Scale (oCIS) i jego nowoczesnego front-endu ownCloud Web. Nie jest to przewodnik dla starszego systemu motywów PHP ownCloud Server 10/11, który wykorzystuje strukturę motywów opartą na aplikacji i inną konfigurację. Stabilna dokumentacja ownCloud Infinite Scale 8.2 oraz dokumentacja programistyczna 9.0 opisują to samo podejście w czasie wykonywania: podaj katalog motywów niestandardowych za pomocą WEB_ASSET_THEMES_PATH, a następnie wybierz plik JSON motywu za pomocą WEB_UI_THEME_PATH. Zobacz oficjalną dokumentację motywów niestandardowych ownCloud Web .

Co można dostosować bez konieczności przebudowywania witryny ownCloud Web

Standardowy motyw organizacji może obejmować zmiany wizualne, których faktycznie potrzebuje większość administratorów. Kod JSON motywu może definiować nazwę produktu i slogan, ścieżki do logo i favicon, tło strony logowania oraz tokeny projektu witryny, takie jak kolor marki, kolor podstawowy, kolor tła, tekst, obramowanie i kolor typu pliku. Jest to lepsze rozwiązanie niż edycja skompilowanych plików front-end, ponieważ motyw pozostaje oddzielnym zasobem wdrożeniowym i można nim zarządzać równolegle z konfiguracją serwera.

Krok 1: Utwórz oddzielny katalog motywu i folder zasobów

Zacznij od oddzielenia swojego niestandardowego motywu od wbudowanych zasobów ownCloud. Prosty układ to katalog motywu zawierający themes.jsondodatkowo assetsfolder na logo, ikonę favicon i obraz logowania. Dokładna ścieżka hosta zależy od Ciebie; ważne jest, aby katalog był zamontowany lub w inny sposób udostępniany usłudze sieciowej oCIS za pośrednictwem WEB_ASSET_THEMES_PATH.

Przykładowy układ pliku dla niestandardowego motywu internetowego ownCloud. Definicja motywu i zasoby obrazów są przechowywane razem w dedykowanym katalogu.

Na przykład struktura po stronie hosta mogłaby wyglądać następująco:

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

Używaj zasobów graficznych, które pozostają czytelne w kontekście, w którym się pojawiają. Ciemne logo, które dobrze wygląda na białej stronie, może znikać na tle ciemnego górnego paska, dlatego często przydatne jest zapewnienie oddzielnych wariantów logo – jasnego i ciemnego. Zadbaj również o to, aby tło logowania za panelem logowania było stosunkowo proste. Branding powinien poprawiać rozpoznawalność, nie zmniejszając jednocześnie czytelności.

Krok 2: Zdefiniuj nazwę marki, ścieżki logo, ikonę favicon i tło logowania

Motyw JSON stanowi centrum personalizacji. commonSekcja zawiera współdzielony tekst marki, taki jak nazwa i slogan. W sekcji clients.web.defaultsmożesz zdefiniować domyślne logo internetowe i tło logowania. Udokumentowany schemat ownCloud używa oddzielnych kluczy logo dla topbar, faviconi login.

Ilustracja w stylu edytora przedstawiająca część brandingową pliku motywu. Użyj udokumentowanej struktury obiektów z poniższego przykładu, zamiast traktować ilustrację jako kod kopiuj-wklej.

Minimalny punkt wyjścia można oprzeć na obsługiwanej strukturze opisanej poniżej. Zachowaj ścieżki spójne ze ścieżką URL, za pośrednictwem której usługa internetowa udostępnia zasoby motywu:

{
  "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": []
    }
  }
}

Nie zakładaj, że każdy klucz można bezpiecznie pominąć tylko dlatego, że parser JSON akceptuje plik. Firma ownCloud zauważa, że ​​niektóre obowiązkowe klucze motywu są wstrzykiwane w czasie wykonywania, ale poprawny składniowo motyw może nadal być semantycznie błędny. Dobrą praktyką produkcyjną jest rozpoczęcie od szablonu motywu dostarczonego w wersji Infinite Scale, z której faktycznie korzystasz, wprowadzenie tylko niezbędnych zmian w brandingu i zachowanie zgodności reszty struktury z daną wersją.

Krok 3: Zmień kolory motywu za pomocą tokenów projektowych

Personalizacja kolorów powinna być dostosowana do wpisu motywu w sekcji clients.web.themes. Każdy motyw może identyfikować, czy jest ciemny, za pomocą isDark, zapewniać czytelny dla człowieka namei zastępować tokeny projektowe. To colorPalettetutaj zazwyczaj dostosowuje się widoczne kolory marki.

Przykład rodzajów tokenów kolorów używanych przez ownCloud Web. Najpierw zmień wybrany zestaw, a następnie sprawdź kontrast i stany najechania kursorem, zanim rozszerzysz paletę.

Jeśli chcesz uzyskać jasny motyw korporacyjny, możesz zacząć od małego zestawu żetonów, zamiast zmieniać każdy dostępny kolor:

{
  "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"
    }
  }
}

Istotnym kompromisem jest spójność kontra kompletność. Zmiana samej wartości swatch-brand-defaultmoże dać szybki efekt wizualny, ale tokeny najechania kursorem, kontrastu, paska bocznego, obramowania i tekstu mogą nadal odzwierciedlać domyślny motyw. Z drugiej strony, nadpisanie dziesiątek tokenów bez przetestowania może prowadzić do nieczytelnych kombinacji. W większości wdrożeń należy zacząć od wartości marki, elementu głównego, kontrastu, tła, tekstu i obramowania, a następnie rozszerzać je tylko tam, gdzie wartości domyślne widocznie kolidują z projektem.

Zwróć szczególną uwagę na kontrast. Jeśli wybierzesz jasny kolor marki, połącz go z ciemnym, kontrastowym tokenem, zamiast narzucać mu biały tekst. Przetestuj fokus klawiatury, stany najechania kursorem, wyłączone elementy sterujące, tryb ciemny, jeśli go udostępniasz, oraz tryby wysokiego kontrastu, jeśli mają one znaczenie dla użytkowników.

Krok 4: Zamontuj niestandardowy motyw i skieruj ownCloud na plik themes.json

Gdy katalog i plik JSON będą gotowe, skonfiguruj usługę internetową tak, aby mogła je odczytać. Dwie istotne zmienne środowiskowe to WEB_ASSET_THEMES_PATH, która wskazuje ownCloud lokalizację katalogu głównego motywu niestandardowego, oraz WEB_UI_THEME_PATH, która wybiera plik JSON motywu do załadowania.

Ilustracja w stylu Docker Compose przedstawiająca montowanie katalogu motywu niestandardowego i konfigurowanie dwóch zmiennych środowiskowych motywu internetowego ownCloud. Dostosuj ścieżki do rzeczywistego wdrożenia.

Wdrożenie Docker Compose może wykorzystywać następujący wzorzec:

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

Powyższy tag obrazu jest celowo symbolem zastępczym. W środowisku produkcyjnym należy użyć dokładnie tej samej wersji oCIS, którą przetestowano, zamiast kopiować tag zmienny z przykładu. Po zmianie środowiska lub zamontowanych plików należy ponownie uruchomić lub utworzyć ponownie usługę oCIS, zgodnie z metodą wdrożenia, aby nowa konfiguracja została odczytana.

Własna platforma cloud dokumentuje ważne zachowanie awaryjne: jeśli nie podano motywu niestandardowego lub jego załadowanie się nie powiedzie, używany jest standardowy motyw Infinite Scale. To rozwiązanie awaryjne jest przydatne, ponieważ brak ścieżki niekoniecznie oznacza, że ​​interfejs jest bezużyteczny. Oznacza to jednak również, że wyświetlenie domyślnego wyglądu ownCloud po ponownym uruchomieniu może być wskazówką diagnostyczną, że motyw niestandardowy nie został załadowany.

Jak sprawdzić, czy branding został faktycznie załadowany

Nie zatrzymuj się po zmianie strony logowania. Kompleksowe sprawdzenie powinno objąć miejsca, w których użytkownicy faktycznie zobaczą Twoją markę. Otwórz witrynę w nowej sesji przeglądarki lub w oknie prywatnym, aby zmniejszyć ryzyko, że zasób z pamięci podręcznej ukryje aktualny stan.

• Sprawdź, czy strona logowania używa oczekiwanego logo i tła.
• Po zalogowaniu się sprawdź, czy logo na górnym pasku jest prawidłowe i czy jest czytelne na swoim tle.
• Sprawdź kartę przeglądarki w celu znalezienia niestandardowej ikony.
• Otwórz obszar pliku i sprawdź główne przyciski, stany najechania kursorem, kolory paska bocznego, ikony folderów i kontrast tekstu.
• Jeśli używasz jasnego i ciemnego motywu, przełączaj się między nimi i zweryfikuj każdy z nich niezależnie.
• Zaznacz co najmniej jedną wąską opcję przeglądarki, aby szerokie logo nie zasłaniało górnego paska.

Gdy niestandardowy motyw się nie wyświetla

Domyślny motyw ownCloud nadal się ładuje

Najpierw sprawdź ścieżki wewnątrz działającego kontenera lub usługi, a nie tylko na hoście. WEB_ASSET_THEMES_PATHŚcieżka musi odnosić się do katalogu głównego motywu widzianego przez usługę internetową oraz WEB_UI_THEME_PATHdo rzeczywistego pliku JSON w tym środowisku. Ścieżka hosta, która nigdy nie została zamontowana w kontenerze, nie może zostać odczytana przez ownCloud.

JSON ładuje się, ale brakuje obrazu

Sprawdź ścieżkę dostępu do zasobu themes.json, wielkość liter w nazwie pliku oraz to, czy plik znajduje się w katalogu motywów niestandardowych. Narzędzia programistyczne przeglądarek mogą pomóc odróżnić nieprawidłowe żądanie zasobu od problemu z motywem. Jeśli kolory motywu się ładują, ale jedno logo nie, sam motyw może być prawidłowy, a ścieżka dostępu do zasobu jest błędna.

Strona jest markowa, ale kolory wydają się niespójne

Zwykle oznacza to, że tylko część palety została nadpisana. Dodaj powiązane tokeny najechania kursorem i kontrastu, a następnie przetestuj ponownie. Nie rozwiązuj problemu pojedynczego nieczytelnego przycisku, zmieniając ogólnie niepowiązany tekst lub tokeny tła; wprowadź najmniejszą spójną zmianę i zweryfikuj ją w całym interfejsie.

Motyw działa w jednej wersji, ale po aktualizacji wygląda nieprawidłowo

Tokeny motywu i zachowanie front-endu mogą ewoluować. Przed uaktualnieniem środowiska produkcyjnego należy porównać niestandardowy motyw z szablonem i dokumentacją docelowej wersji oCIS. Dokumentacja konfiguracji sieciowej ownCloud wyjaśnia również różnicę między obsługiwaną konfiguracją/zasobami niestandardowymi a dostarczaniem w pełni spersonalizowanych, skompilowanych zasobów sieciowych.

Czy zamiast tego powinieneś edytować skompilowane zasoby internetowe?

Zazwyczaj nie jest to rozwiązanie do standardowego brandingu. Motyw niestandardowy jest lepszym rozwiązaniem, gdy celem jest zmiana nazw, logo, tła i tokenów projektowych, przy jednoczesnym zachowaniu zgodności z obsługiwanym interfejsem użytkownika. W pełni spersonalizowane, skompilowane zasoby mają sens tylko wtedy, gdy tworzysz lub dystrybuujesz autentycznie zmodyfikowany interfejs użytkownika, którego nie da się wyrazić za pomocą motywu ani obsługiwanych nadpisów zasobów. Takie podejście wiąże się z wyższymi kosztami utrzymania, ponieważ odpowiadasz za zgodność swojej niestandardowej kompilacji z przyszłymi zmianami w OwnCloud Web.

Praktyczna lista kontrolna produkcji

• Przechowuj pliki motywów niestandardowych poza wbudowanymi katalogami aplikacji.
• Rozpocznij od struktury motywu opisanej dla zainstalowanej wersji oCIS.
• Jeśli wymagają tego jasne i ciemne powierzchnie, stosuj osobne warianty logo.
• Najpierw należy zastąpić skoncentrowany zestaw tokenów projektowych, w tym wartości najechania kursorem i kontrastu.
• Jeśli to możliwe, zamontuj katalog motywu w trybie tylko do odczytu.
• Ustaw zarówno WEB_ASSET_THEMES_PATHi , WEB_UI_THEME_PATHaby wskazywały ścieżki widoczne wewnątrz usługi.
• Po wprowadzeniu zmian wdrożeniowych należy ponownie uruchomić usługę Web/oCIS lub utworzyć ją na nowo.
• Sprawdź logowanie, pasek górny, ikonę witryny, obszar plików, układ responsywny i wszelkie ciemne lub kontrastowe motywy, które udostępniasz.
• Przed każdą większą aktualizacją ownCloud Infinite Scale należy ponownie przetestować motyw.

W przypadku obecnych wdrożeń Infinite Scale, podejście oparte na plikach motywu zapewnia administratorom wyraźne oddzielenie kodu aplikacji od identyfikacji wizualnej. Kluczem jest traktowanie motywu jako wersjonowanego zasobu wdrożeniowego: należy używać schematu obsługiwanego przez wersję ownCloud, zapewnić przewidywalność ścieżek obrazów, zmieniać kolory za pomocą tokenów projektowych, a nie doraźnych zmian w interfejsie, oraz weryfikować wynik w całym interfejsie webowym, zamiast oceniać sukces na podstawie jednego ekranu.