How to Customize ownCloud Web UI Branding and Theme Colors

The most reliable way to customize the current ownCloud Web interface is to create a supported theme JSON file and point ownCloud Infinite Scale to that theme. You do not need to rebuild the Web frontend just to change the brand name, logos, favicon, login background, or common interface colors. In the current Infinite Scale theming model, those elements are supplied through a theme definition, while design tokens control colors and other visual values.

This guide is written for ownCloud Infinite Scale (oCIS) and its modern ownCloud Web frontend. It is not a guide for the older ownCloud Server 10/11 PHP theming system, which uses an app-based theme structure and different configuration. ownCloud's stable Infinite Scale 8.2 documentation and the 9.0 development documentation both describe the same runtime approach: provide a custom themes directory with WEB_ASSET_THEMES_PATH, then select a theme JSON file with WEB_UI_THEME_PATH. See the official ownCloud Web custom theming documentation.

What you can customize without rebuilding ownCloud Web

A normal organization theme can cover the visual changes most administrators actually need. The theme JSON can define the product name and slogan, paths to logos and a favicon, the login-page background, and Web design tokens such as brand, primary, background, text, border, and file-type colors. This is preferable to editing compiled frontend files because the theme remains a separate deployment asset and can be managed alongside your server configuration.

Step 1: Create a separate theme directory and assets folder

Start by keeping your custom theme separate from the built-in ownCloud assets. A simple layout is a theme directory containing themes.json plus an assets folder for your logos, favicon, and login image. The exact host path is your choice; what matters is that the directory is mounted or otherwise exposed to the oCIS Web service through WEB_ASSET_THEMES_PATH.

Example file layout for a custom ownCloud Web theme. The theme definition and image assets are kept together in a dedicated directory.

For example, a host-side structure could look like this:

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

Utilize imagens que permaneçam legíveis no contexto em que aparecem. Um logotipo escuro que funciona bem em uma página branca pode desaparecer contra uma barra superior escura, portanto, geralmente é útil fornecer variantes separadas do logotipo, em versões clara e escura. Além disso, mantenha o fundo da área de login relativamente simples atrás dos controles de login. A identidade visual deve melhorar o reconhecimento sem comprometer a legibilidade.

Etapa 2: Defina o nome da marca, os caminhos do logotipo, o favicon e o fundo da tela de login.

O JSON do tema é o centro da personalização. A commonseção contém textos de marca compartilhados, como o nome e o slogan. Em clients.web.defaults, você pode definir os logotipos padrão da Web e o plano de fundo de login. O esquema documentado do ownCloud usa chaves de logotipo separadas para topbar, favicone login.

Ilustração no estilo do editor da parte de identidade visual de um arquivo de tema. Use a estrutura de objeto documentada no exemplo abaixo, em vez de tratar a ilustração como código para copiar e colar.

Um ponto de partida mínimo pode ser baseado na estrutura suportada abaixo. Mantenha os caminhos consistentes com o caminho da URL pela qual o serviço Web expõe os recursos do seu 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": []
    }
  }
}

Não presuma que todas as chaves podem ser omitidas com segurança apenas porque o analisador JSON aceita o arquivo. A ownCloud observa que algumas chaves de tema obrigatórias são injetadas em tempo de execução, mas um tema sintaticamente válido ainda pode estar semanticamente incorreto. Uma boa prática de produção é começar com o modelo de tema fornecido na versão do Infinite Scale que você está usando, fazer apenas as alterações de marca necessárias e manter o restante da estrutura alinhado com essa versão.

Passo 3: Alterar as cores do tema com tokens de design

A personalização de cores deve ser feita em uma entrada de tema dentro de `<theme>` clients.web.themes. Cada tema pode identificar se é escuro com isDark`<theme-style>`, fornecer um `<theme-style>` legível namee sobrescrever tokens de design. É colorPaletteaqui que as cores visíveis da marca são normalmente ajustadas.

Exemplo dos tipos de tokens de cor usados ​​pelo ownCloud Web. Altere primeiro o conjunto selecionado e, em seguida, verifique o contraste e o estado de foco antes de expandir a paleta.

Para um tema corporativo leve, você pode começar com um pequeno conjunto de símbolos em vez de alterar todas as cores disponíveis:

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

O importante equilíbrio é entre consistência e abrangência. Alterar apenas um elemento swatch-brand-defaultpode proporcionar um resultado visual rápido, mas os tokens de foco, contraste, barra lateral, borda e texto ainda podem refletir o tema padrão. Por outro lado, sobrescrever dezenas de tokens sem testes pode criar combinações ilegíveis. Para a maioria das implementações, comece com os valores de marca, cor principal, contraste, plano de fundo, texto e borda, e expanda apenas onde os valores padrão entrarem em conflito visível com o seu design.

Preste atenção especial ao contraste. Se escolher uma cor clara para a sua marca, combine-a com um elemento de contraste escuro em vez de forçar texto branco sobre ele. Teste o foco do teclado, os estados de foco ao passar o cursor, os controles desativados, o modo escuro (se disponível) e os modos de alto contraste (se relevantes para os seus usuários).

Passo 4: Instale o tema personalizado e configure o ownCloud para usar o arquivo themes.json.

Assim que o diretório e o arquivo JSON estiverem prontos, configure o serviço Web para que ele possa lê-los. As duas variáveis ​​de ambiente relevantes são ` WEB_ASSET_THEMES_PATHcustomThemeRoot`, que informa ao ownCloud onde o tema personalizado está localizado, e WEB_UI_THEME_PATH`themeJSONFile`, que seleciona o arquivo JSON do tema a ser carregado.

Ilustração no estilo Docker Compose de como montar um diretório de tema personalizado e configurar as duas variáveis ​​de ambiente de tema web do ownCloud. Adapte os caminhos à sua implantação real.

Uma implementação do Docker Compose pode usar um padrão como este:

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

A tag de imagem acima é intencionalmente um marcador de posição. Para produção, use a versão exata do oCIS que você testou, em vez de copiar uma tag flutuante de um exemplo. Após alterar o ambiente ou os arquivos montados, reinicie ou recrie o serviço oCIS afetado de acordo com seu método de implantação para que a nova configuração seja lida.

A documentação do ownCloud descreve um importante comportamento alternativo: se nenhum tema personalizado for fornecido ou se o carregamento do tema falhar, o tema padrão Infinite Scale será utilizado. Esse comportamento alternativo é útil porque a ausência de um caminho não torna necessariamente a interface inutilizável. No entanto, isso também significa que ver a aparência padrão do ownCloud após uma reinicialização pode ser um indício de que seu tema personalizado não foi carregado.

Como verificar se a marca foi realmente carregada?

Não pare após as alterações na página de login. Uma verificação completa deve abranger os locais onde os usuários realmente verão sua marca. Abra o site em uma nova sessão do navegador ou em uma janela anônima para reduzir a chance de um recurso em cache ocultar o estado atual.

• Confirme se a página de login utiliza o logotipo e o plano de fundo esperados.
• Após efetuar o login, confirme se o logotipo na barra superior está correto e permanece legível sobre o fundo.
• Verifique a aba do navegador para ver o favicon personalizado.
• Abra a área de arquivos e verifique os botões principais, os estados de foco, as cores da barra lateral, os ícones das pastas e o contraste do texto.
• Se você disponibilizar temas claros e escuros, alterne entre eles e verifique ambos separadamente.
• Verifique pelo menos uma largura de navegador estreita para que um logotipo largo não sobrecarregue a barra superior responsiva.

Quando o tema personalizado não aparece

O tema padrão do ownCloud ainda carrega.

Primeiro, verifique os caminhos dentro do contêiner ou serviço em execução, não apenas no host. WEB_ASSET_THEMES_PATHO caminho deve se referir à raiz do tema, conforme vista pelo serviço web, e WEB_UI_THEME_PATHdeve se referir ao arquivo JSON real nesse ambiente. Um caminho de host que nunca foi montado no contêiner não pode ser lido pelo ownCloud.

O JSON carrega, mas falta uma imagem.

Verifique o caminho do recurso themes.json, o uso de maiúsculas e minúsculas no nome do arquivo e se o arquivo existe no diretório de temas personalizados. As ferramentas de desenvolvedor do navegador podem ajudar a distinguir uma solicitação de recurso corrompida de um problema de tema. Se as cores do tema carregarem, mas um logotipo não, o tema em si pode estar correto, enquanto o caminho do recurso está incorreto.

A página está identificada com a marca, mas as cores parecem inconsistentes.

Isso geralmente significa que apenas parte da paleta foi sobrescrita. Adicione os tokens de foco e contraste relacionados e teste novamente. Não resolva um único botão ilegível alterando amplamente tokens de texto ou de fundo não relacionados; faça a menor alteração coerente possível e verifique-a em toda a interface.

Um tema funciona em uma versão, mas fica com aparência incorreta após uma atualização.

Os tokens de tema e o comportamento do frontend podem evoluir. Antes de atualizar um ambiente de produção, compare seu tema personalizado com o modelo e a documentação da versão oCIS de destino. A documentação de configuração personalizada da Web do ownCloud também explica a distinção entre configurações/ativos personalizados suportados e o fornecimento de ativos da Web compilados totalmente personalizados.

Em vez disso, você deveria editar os recursos da Web compilados?

Geralmente não é adequado para personalização de marca comum. Um tema personalizado é a melhor opção quando seu objetivo é alterar nomes, logotipos, planos de fundo e elementos de design, mantendo-se fiel à interface web padrão. Recursos compilados totalmente personalizados só fazem sentido quando você está desenvolvendo ou distribuindo um frontend genuinamente modificado que não pode ser expresso por meio de temas ou substituições de recursos padrão. Essa abordagem acarreta um custo de manutenção mais alto, pois você é responsável por manter sua versão personalizada compatível com futuras alterações do ownCloud Web.

Uma lista de verificação prática para a produção

• Mantenha os arquivos de tema personalizados fora dos diretórios padrão do aplicativo.
• Comece pela estrutura de temas documentada para a versão do oCIS instalada em sua casa.
• Utilize variantes de logotipo diferentes quando superfícies claras e escuras assim o exigirem.
• Primeiro, substitua um conjunto específico de marcadores de design, incluindo os valores de foco e contraste.
• Sempre que possível, monte o diretório do tema como somente leitura.
• Defina ambos WEB_ASSET_THEMES_PATHos WEB_UI_THEME_PATHcaminhos como visíveis dentro do serviço.
• Reinicie ou recrie o serviço Web/oCIS após as alterações de implantação.
• Verifique o login, a barra superior, o favicon, a área de arquivos, o layout responsivo e quaisquer temas escuros/de alto contraste que você disponibilizar.
• Teste novamente o tema antes de cada atualização importante do ownCloud Infinite Scale.

Para as implementações atuais do Infinite Scale, essa abordagem de arquivo de tema oferece aos administradores uma separação clara entre o código do aplicativo e a identidade visual. A chave é tratar o tema como um recurso de implementação versionado: use o esquema compatível com a sua versão do ownCloud, mantenha os caminhos das imagens previsíveis, altere as cores por meio de tokens de design em vez de edições ad hoc no frontend e verifique o resultado em toda a interface da Web, em vez de avaliar o sucesso com base em apenas uma tela.