Come personalizzare il branding e i colori del tema dell'interfaccia web di ownCloud.

Il modo più affidabile per personalizzare l'attuale interfaccia Web di ownCloud è creare un file JSON del tema supportato e indicare a ownCloud Infinite Scale di utilizzare tale tema. Non è necessario ricostruire il frontend Web solo per modificare il nome del marchio, i loghi, la favicon, lo sfondo della pagina di accesso o i colori comuni dell'interfaccia. Nell'attuale modello di temi di Infinite Scale, questi elementi vengono forniti tramite una definizione di tema, mentre i token di progettazione controllano i colori e altri valori visivi.

Questa guida è stata scritta per ownCloud Infinite Scale (oCIS) e la sua moderna interfaccia web ownCloud. Non è una guida per il vecchio sistema di temi PHP di ownCloud Server 10/11, che utilizza una struttura di temi basata su app e una configurazione diversa. La documentazione stabile di ownCloud Infinite Scale 8.2 e la documentazione di sviluppo 9.0 descrivono entrambe lo stesso approccio in fase di esecuzione: fornire una directory di temi personalizzati con WEB_ASSET_THEMES_PATH, quindi selezionare un file JSON del tema con WEB_UI_THEME_PATH. Consultare la documentazione ufficiale di ownCloud Web sui temi personalizzati .

Cosa puoi personalizzare senza ricostruire ownCloud Web

Un tema aziendale standard può coprire le modifiche visive di cui la maggior parte degli amministratori ha effettivamente bisogno. Il file JSON del tema può definire il nome e lo slogan del prodotto, i percorsi ai loghi e alla favicon, lo sfondo della pagina di accesso e i token di progettazione web come i colori del marchio, primario, di sfondo, del testo, del bordo e del tipo di file. Questo è preferibile alla modifica dei file frontend compilati perché il tema rimane una risorsa di distribuzione separata e può essere gestito insieme alla configurazione del server.

Passaggio 1: Creare una directory per il tema e una cartella per le risorse separate.

Inizia mantenendo il tuo tema personalizzato separato dalle risorse integrate di ownCloud. Un layout semplice prevede una directory del tema contenente themes.jsonpiù una assetscartella per i tuoi loghi, favicon e immagine di accesso. Il percorso host esatto è a tua discrezione; ciò che conta è che la directory sia montata o comunque esposta al servizio Web oCIS tramite WEB_ASSET_THEMES_PATH.

Esempio di struttura dei file per un tema Web personalizzato di ownCloud. La definizione del tema e le risorse grafiche sono conservate insieme in una directory dedicata.

Ad esempio, la struttura lato host potrebbe apparire così:

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

Utilizzate immagini che rimangano leggibili nel contesto in cui appaiono. Un logo scuro che funziona su una pagina bianca potrebbe non essere visibile su una barra superiore scura, quindi è spesso utile fornire varianti del logo separate, una chiara e una scura. Inoltre, mantenete lo sfondo della schermata di accesso relativamente semplice, dietro i controlli di login. Il branding dovrebbe migliorare il riconoscimento senza compromettere la leggibilità.

Passaggio 2: Definisci il nome del marchio, i percorsi del logo, la favicon e lo sfondo della pagina di accesso.

Il tema JSON è il fulcro della personalizzazione. La commonsezione contiene il testo del marchio condiviso, come il nome e lo slogan. Sotto clients.web.defaults, è possibile definire i loghi Web predefiniti e lo sfondo di accesso. Lo schema documentato di ownCloud utilizza chiavi logo separate per topbar, favicon, e login.

Illustrazione in stile editor della sezione branding di un file di tema. Utilizzare la struttura degli oggetti documentata nell'esempio seguente anziché considerare l'illustrazione come codice da copiare e incollare.

Un punto di partenza minimo può essere basato sulla struttura supportata riportata di seguito. Mantieni i percorsi coerenti con l'URL tramite il quale il servizio Web espone le risorse del tuo tema:

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

Non date per scontato che ogni chiave possa essere omessa in tutta sicurezza solo perché il parser JSON accetta il file. ownCloud fa notare che alcune chiavi del tema obbligatorie vengono inserite in fase di esecuzione, ma un tema sintatticamente valido può comunque essere semanticamente errato. Una buona prassi in produzione è quella di partire dal template del tema fornito nella versione di Infinite Scale che effettivamente utilizzate, apportare solo le modifiche di branding necessarie e mantenere il resto della struttura allineato a tale versione.

Passaggio 3: Modifica i colori del tema con i token di progettazione

La personalizzazione del colore appartiene a una voce del tema sotto clients.web.themes. Ogni tema può identificare se è scuro con isDark, fornire un in formato leggibile namee sovrascrivere i token di design. Il colorPaletteè dove vengono normalmente regolati i colori del marchio visibili.

Esempio dei tipi di token di colore utilizzati da ownCloud Web. Modifica prima un set attivo, poi verifica il contrasto e lo stato al passaggio del mouse prima di espandere la tavolozza.

Per un tema aziendale leggero, potresti iniziare con un piccolo set di token invece di cambiare ogni colore disponibile:

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

Il compromesso fondamentale è tra coerenza e completezza. Modificare solo alcuni elementi swatch-brand-defaultpuò dare un risultato visivo immediato, ma i token relativi a hover, contrasto, barra laterale, bordo e testo potrebbero comunque riflettere il tema predefinito. D'altra parte, sovrascrivere decine di token senza testarli può creare combinazioni illeggibili. Per la maggior parte delle implementazioni, iniziate con i valori di brand, primary, contrasto, background, testo e bordo, quindi estendete le modifiche solo dove i valori predefiniti sono visibilmente in conflitto con il vostro design.

Presta particolare attenzione al contrasto. Se scegli un colore chiaro per il tuo marchio, abbinalo a un elemento di contrasto scuro anziché sovrapporre del testo bianco. Testa il focus della tastiera, gli stati al passaggio del mouse, i controlli disabilitati, la modalità scura (se disponibile) e le modalità ad alto contrasto, se importanti per i tuoi utenti.

Passaggio 4: Monta il tema personalizzato e configura ownCloud in modo che punti al file themes.json.

Una volta che la directory e il file JSON sono pronti, configura il servizio Web in modo che possa leggerli. Le due variabili d'ambiente rilevanti sono WEB_ASSET_THEMES_PATH, che indica a ownCloud dove si trova la directory principale del tema personalizzato, e WEB_UI_THEME_PATH, che seleziona il file JSON del tema da caricare.

Illustrazione in stile Docker Compose del montaggio di una directory di temi personalizzata e della configurazione delle due variabili d'ambiente di ownCloud Web Themes. Adatta i percorsi alla tua implementazione effettiva.

Un'implementazione con Docker Compose potrebbe utilizzare uno schema simile a questo:

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

Il tag immagine qui sopra è intenzionalmente un segnaposto. Per l'ambiente di produzione, utilizzare la versione esatta di oCIS testata anziché copiare un tag fluttuante da un esempio. Dopo aver modificato l'ambiente o i file montati, riavviare o ricreare il servizio oCIS interessato in base al metodo di implementazione utilizzato, in modo che la nuova configurazione venga letta.

ownCloud documenta un importante comportamento di fallback: se non viene fornito alcun tema personalizzato o se il caricamento del tema fallisce, viene utilizzato il tema standard Infinite Scale. Questo fallback è utile perché un percorso mancante non rende necessariamente l'interfaccia inutilizzabile. Tuttavia, significa anche che visualizzare l'aspetto predefinito di ownCloud dopo un riavvio può essere un indizio diagnostico del mancato caricamento del tema personalizzato.

Come verificare che il marchio sia stato effettivamente caricato

Non fermarti alla modifica della pagina di accesso. Un controllo completo dovrebbe includere tutti i punti in cui gli utenti visualizzeranno effettivamente il tuo marchio. Apri il sito in una nuova sessione del browser o in una finestra di navigazione privata per ridurre la possibilità che una risorsa memorizzata nella cache nasconda lo stato attuale.

• Verifica che la pagina di accesso utilizzi il logo e lo sfondo previsti.
• Dopo aver effettuato l'accesso, verifica che il logo nella barra superiore sia corretto e rimanga leggibile sullo sfondo.
• Controlla la scheda del browser per visualizzare la favicon personalizzata.
• Apri l'area dei file e verifica i pulsanti principali, gli stati al passaggio del mouse, i colori della barra laterale, le icone delle cartelle e il contrasto del testo.
• Se offri temi chiari e scuri, passa da uno all'altro e verificali entrambi separatamente.
• Verifica almeno una larghezza ridotta del browser in modo che un logo di grandi dimensioni non sovraccarichi la barra superiore adattiva.

Quando il tema personalizzato non viene visualizzato

Il tema predefinito di ownCloud viene ancora caricato

Innanzitutto, verifica i percorsi all'interno del container o del servizio in esecuzione, non solo sull'host. WEB_ASSET_THEMES_PATHdeve fare riferimento alla directory principale del tema vista dal servizio Web e WEB_UI_THEME_PATHdeve fare riferimento al file JSON effettivo in quell'ambiente. Un percorso host che non è mai stato montato nel container non può essere letto da ownCloud.

Il file JSON viene caricato, ma manca l'immagine.

Verifica il percorso della risorsa all'interno di themes.json, la distinzione tra maiuscole e minuscole del nome del file e se il file esiste nella directory dei temi personalizzati. Gli strumenti per sviluppatori del browser possono aiutare a distinguere una richiesta di risorsa non riuscita da un problema di tematizzazione. Se i colori del tema vengono caricati ma un logo no, il tema stesso potrebbe essere valido mentre il percorso della risorsa è errato.

La pagina è brandizzata, ma i colori appaiono incoerenti.

Questo di solito significa che solo una parte della tavolozza è stata sovrascritta. Aggiungi i relativi token di hover e di contrasto, quindi esegui nuovamente il test. Non risolvere il problema di un singolo pulsante illeggibile modificando in modo generalizzato token di testo o di sfondo non correlati; apporta la più piccola modifica coerente e verificala su tutta l'interfaccia.

Un tema funziona correttamente in una versione, ma dopo un aggiornamento appare errato.

I token del tema e il comportamento del frontend possono evolversi. Prima di aggiornare un ambiente di produzione, confronta il tuo tema personalizzato con il modello e la documentazione della versione oCIS di destinazione. La documentazione di ownCloud sulla configurazione Web personalizzata spiega anche la distinzione tra le risorse personalizzate/configurazioni supportate e la fornitura di risorse Web completamente personalizzate e compilate.

È preferibile modificare le risorse Web compilate?

Solitamente non è la soluzione ideale per il branding ordinario. Un tema personalizzato è più adatto quando l'obiettivo è modificare nomi, loghi, sfondi e token di design rimanendo fedeli all'interfaccia utente Web supportata. Risorse completamente personalizzate hanno senso solo quando si sviluppa o si distribuisce un frontend realmente modificato che non può essere espresso tramite temi o override di risorse supportate. Questo approccio comporta costi di manutenzione più elevati perché è responsabilità dello sviluppatore garantire la compatibilità della propria build personalizzata con le future modifiche di ownCloud Web.

Una pratica lista di controllo per la produzione

• Mantieni i file dei temi personalizzati al di fuori delle directory predefinite dell'applicazione.
• Partite dalla struttura tematica documentata per la versione di oCIS che avete installato.
• Utilizzare varianti separate del logo quando le superfici chiare e scure lo richiedono.
• Innanzitutto, sovrascrivi un insieme mirato di token di design, inclusi i valori al passaggio del mouse e il contrasto.
• Se possibile, monta la directory del tema in modalità di sola lettura.
• Imposta entrambi i percorsi WEB_ASSET_THEMES_PATHsu WEB_UI_THEME_PATHpercorsi visibili all'interno del servizio.
• Riavviare o ricreare il servizio Web/oCIS dopo le modifiche di distribuzione.
• Verifica l'accesso, la barra superiore, la favicon, l'area dei file, il layout responsivo e qualsiasi tema scuro/ad alto contrasto che utilizzi.
• Ritesta il tema prima di ogni aggiornamento importante di ownCloud Infinite Scale.

Per le attuali implementazioni di Infinite Scale, questo approccio basato sui file di tema offre agli amministratori una netta separazione tra il codice dell'applicazione e l'identità visiva. La chiave è trattare il tema come una risorsa di implementazione versionata: utilizzare lo schema supportato dalla propria release di ownCloud, mantenere percorsi delle immagini prevedibili, modificare i colori tramite token di progettazione anziché con modifiche ad hoc nel frontend e verificare il risultato sull'intera interfaccia Web anziché giudicare il successo da una singola schermata.