Cómo personalizar la imagen de marca y los colores del tema de la interfaz web de ownCloud.

La forma más fiable de personalizar la interfaz web actual de ownCloud es crear un archivo JSON de tema compatible e indicar a ownCloud Infinite Scale que utilice dicho tema. No es necesario reconstruir la interfaz web solo para cambiar el nombre de la marca, los logotipos, el favicon, el fondo de inicio de sesión o los colores comunes de la interfaz. En el modelo de temas actual de Infinite Scale, estos elementos se proporcionan mediante una definición de tema, mientras que los tokens de diseño controlan los colores y otros valores visuales.

Esta guía está escrita para ownCloud Infinite Scale (oCIS) y su interfaz web moderna ownCloud. No es una guía para el sistema de temas PHP de ownCloud Server 10/11 anterior, que utiliza una estructura de temas basada en la aplicación y una configuración diferente. La documentación estable de ownCloud Infinite Scale 8.2 y la documentación de desarrollo de la versión 9.0 describen el mismo enfoque de tiempo de ejecución: proporcionar un directorio de temas personalizados con WEB_ASSET_THEMES_PATH, luego seleccionar un archivo JSON de tema con WEB_UI_THEME_PATH. Consulte la documentación oficial de temas personalizados de ownCloud Web .

Qué puedes personalizar sin reconstruir ownCloud Web

Un tema de organización estándar puede cubrir los cambios visuales que la mayoría de los administradores realmente necesitan. El archivo JSON del tema puede definir el nombre y el eslogan del producto, las rutas a los logotipos y un favicon, el fondo de la página de inicio de sesión y los tokens de diseño web, como los colores de la marca, el color principal, el fondo, el texto, el borde y el tipo de archivo. Esto es preferible a editar los archivos compilados del frontend, ya que el tema permanece como un recurso de implementación independiente y se puede administrar junto con la configuración del servidor.

Paso 1: Crea un directorio de tema y una carpeta de recursos separados.

Comience por mantener su tema personalizado separado de los recursos integrados de ownCloud. Un diseño simple consiste en un directorio de tema que contiene themes.jsonmás una assetscarpeta para sus logotipos, favicon e imagen de inicio de sesión. La ruta exacta del host es de su elección; lo importante es que el directorio esté montado o expuesto de alguna otra manera al servicio web de oCIS a través de WEB_ASSET_THEMES_PATH.

Ejemplo de estructura de archivos para un tema web personalizado de ownCloud. La definición del tema y los archivos de imagen se guardan juntos en un directorio específico.

Por ejemplo, una estructura del lado del anfitrión podría verse así:

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

Utilice imágenes que se mantengan legibles en el contexto en el que aparecen. Un logotipo oscuro que funciona bien en una página blanca puede desaparecer sobre una barra superior oscura, por lo que suele ser útil proporcionar variantes claras y oscuras del logotipo. Además, mantenga el fondo de inicio de sesión relativamente sencillo detrás de los controles de acceso. La imagen de marca debe mejorar el reconocimiento sin reducir la legibilidad.

Paso 2: Defina el nombre de la marca, las rutas del logotipo, el favicon y el fondo de inicio de sesión.

El tema JSON es el centro de la personalización. La commonsección contiene texto de marca compartido, como el nombre y el eslogan. Debajo clients.web.defaults, puede definir los logotipos web predeterminados y el fondo de inicio de sesión. El esquema documentado de ownCloud utiliza claves de logotipo separadas para topbar, favicon, y login.

Ilustración estilo editor de la sección de marca de un archivo de tema. Utilice la estructura de objetos documentada en el ejemplo siguiente en lugar de tratar la ilustración como código para copiar y pegar.

Un punto de partida mínimo puede basarse en la estructura compatible que se muestra a continuación. Mantenga las rutas coherentes con la ruta URL mediante la cual el servicio web expone los recursos de su 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": []
    }
  }
}

No asuma que todas las claves se pueden omitir sin problemas solo porque el analizador JSON acepta el archivo. ownCloud indica que algunas claves de tema obligatorias se insertan en tiempo de ejecución, pero un tema sintácticamente válido aún puede ser semánticamente incorrecto. Una buena práctica de producción es partir de la plantilla de tema incluida en la versión de Infinite Scale que realmente utiliza, realizar solo los cambios de marca necesarios y mantener el resto de la estructura alineada con esa versión.

Paso 3: Cambia los colores del tema con tokens de diseño.

La personalización del color pertenece a una entrada de tema en clients.web.themes. Cada tema puede identificar si es oscuro con isDark, proporcionar un texto legible para humanos namey anular los tokens de diseño. Es colorPalettedonde normalmente se ajustan los colores visibles de la marca.

Ejemplo de los tipos de tokens de color que utiliza ownCloud Web. Modifique primero el conjunto seleccionado, luego verifique el contraste y los estados al pasar el cursor antes de expandir la paleta.

Para un tema corporativo sencillo, puedes empezar con un pequeño conjunto de fichas en lugar de cambiar todos los colores disponibles:

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

La disyuntiva importante reside en la coherencia frente a la exhaustividad. Modificar solo un elemento swatch-brand-defaultpuede ofrecer un resultado visual rápido, pero los tokens de desplazamiento, contraste, barra lateral, borde y texto podrían seguir reflejando el tema predeterminado. Por otro lado, sobrescribir decenas de tokens sin realizar pruebas puede generar combinaciones ilegibles. En la mayoría de las implementaciones, comience con los valores de marca, principal, contraste, fondo, texto y borde, y luego amplíe solo donde los valores predeterminados entren en conflicto visible con su diseño.

Presta especial atención al contraste. Si eliges un color de marca claro, combínalo con un elemento de contraste oscuro en lugar de superponer texto blanco. Prueba el enfoque del teclado, los estados al pasar el cursor, los controles deshabilitados, el modo oscuro (si lo ofreces) y los modos de alto contraste si son importantes para tus usuarios.

Paso 4: Monta el tema personalizado y configura ownCloud para que apunte a themes.json.

Una vez que el directorio y el archivo JSON estén listos, configure el servicio web para que pueda leerlos. Las dos variables de entorno relevantes son WEB_ASSET_THEMES_PATH, que le indica a ownCloud dónde se encuentra la raíz del tema personalizado, y WEB_UI_THEME_PATH, que selecciona el archivo JSON del tema que se va a cargar.

Ilustración al estilo Docker Compose sobre cómo montar un directorio de tema personalizado y configurar las dos variables de entorno de temas web de ownCloud. Adapte las rutas a su implementación real.

Un despliegue de Docker Compose podría utilizar un patrón 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

La etiqueta de imagen anterior es un marcador de posición. Para producción, utilice la versión exacta de oCIS que haya probado, en lugar de copiar una etiqueta flotante de un ejemplo. Tras modificar el entorno o los archivos montados, reinicie o vuelva a crear el servicio oCIS afectado según su método de implementación para que se lea la nueva configuración.

ownCloud documenta un comportamiento de reserva importante: si no se proporciona un tema personalizado o si falla la carga del tema, se utiliza el tema estándar Infinite Scale. Esta reserva es útil porque la ausencia de una ruta no necesariamente deja la interfaz inutilizable. Sin embargo, también significa que ver la apariencia predeterminada de ownCloud después de un reinicio puede ser una pista de diagnóstico de que su tema personalizado no se cargó.

Cómo verificar que la marca se haya cargado correctamente

No te detengas después de que cambie la página de inicio de sesión. Una revisión completa debe abarcar los lugares donde los usuarios verán tu marca. Abre el sitio en una sesión nueva del navegador o en una ventana privada para reducir la posibilidad de que un archivo en caché oculte el estado actual.

• Confirma que la página de inicio de sesión utiliza el logotipo y el fondo esperados.
• Tras iniciar sesión, compruebe que el logotipo de la barra superior es correcto y que sigue siendo legible sobre el fondo.
• Comprueba la pestaña del navegador para ver el favicon personalizado.
• Abra el área de archivos y verifique los botones principales, los estados al pasar el cursor, los colores de la barra lateral, los iconos de las carpetas y el contraste del texto.
• Si ofreces temas claros y oscuros, cambia entre ellos y verifica ambos de forma independiente.
• Comprueba que el ancho del navegador sea al menos uno estrecho para que un logotipo ancho no sature la barra superior adaptable.

Cuando no aparece el tema personalizado

El tema predeterminado de ownCloud sigue cargándose.

Primero, verifique las rutas dentro del contenedor o servicio en ejecución, no solo en el host. WEB_ASSET_THEMES_PATHDebe hacer referencia a la raíz del tema tal como la ve el servicio web, y WEB_UI_THEME_PATHdebe hacer referencia al archivo JSON real en ese entorno. ownCloud no puede leer una ruta de host que nunca se haya montado en el contenedor.

El JSON se carga pero falta una imagen.

Comprueba la ruta del recurso themes.json, respeta las mayúsculas y minúsculas del nombre del archivo y verifica si existe en el directorio de temas personalizados. Las herramientas para desarrolladores del navegador pueden ayudarte a distinguir una solicitud de recurso defectuosa de un problema de tema. Si los colores del tema se cargan, pero un logotipo no, es posible que el tema sea válido, aunque la ruta del recurso sea incorrecta.

La página tiene la marca, pero los colores se ven inconsistentes.

Esto suele significar que solo se modificó una parte de la paleta. Añade los tokens de desplazamiento y contraste correspondientes y vuelve a probar. No soluciones el problema de un botón ilegible cambiando de forma generalizada texto o tokens de fondo no relacionados; realiza el cambio más pequeño y coherente y verifícalo en toda la interfaz.

Un tema funciona en una versión pero se ve mal después de una actualización.

Los tokens de tema y el comportamiento del frontend pueden evolucionar. Antes de actualizar un entorno de producción, compare su tema personalizado con la plantilla y la documentación de la versión de oCIS de destino. La documentación de configuración web personalizada de ownCloud también explica la diferencia entre la configuración/recursos personalizados compatibles y el suministro de recursos web compilados completamente personalizados.

¿Debería editar los recursos web compilados en su lugar?

Por lo general, no es recomendable para la personalización de marca. Un tema personalizado es la mejor opción cuando el objetivo es cambiar nombres, logotipos, fondos y elementos de diseño, manteniendo la coherencia con la interfaz web compatible. Los recursos compilados totalmente personalizados solo tienen sentido al desarrollar o distribuir una interfaz de usuario modificada que no se puede expresar mediante temas o modificaciones de recursos compatibles. Este enfoque conlleva un mayor costo de mantenimiento, ya que usted es responsable de mantener la compatibilidad de su compilación personalizada con los futuros cambios web de ownCloud.

Una lista de verificación práctica para la producción

• Mantén los archivos de temas personalizados fuera de los directorios de la aplicación integrada.
• Comience con la estructura del tema documentada para la versión de oCIS que tiene instalada.
• Utilice variantes de logotipo diferentes cuando las superficies claras y oscuras lo requieran.
• Primero, sobrescriba un conjunto específico de tokens de diseño, incluidos los valores de desplazamiento del cursor y de contraste.
• Monta el directorio del tema en modo de solo lectura siempre que sea posible.
• Configure ambos WEB_ASSET_THEMES_PATHcomo WEB_UI_THEME_PATHrutas visibles dentro del servicio.
• Reinicie o vuelva a crear el servicio Web/oCIS después de realizar cambios en la implementación.
• Verificar el inicio de sesión, la barra superior, el favicon, el área de archivos, el diseño adaptable y cualquier tema oscuro o de alto contraste que se muestre.
• Vuelva a probar el tema antes de cada actualización importante de ownCloud Infinite Scale.

Para las implementaciones actuales de Infinite Scale, este enfoque de archivo de tema proporciona a los administradores una clara separación entre el código de la aplicación y la identidad visual. La clave es tratar el tema como un recurso de implementación versionado: utilice el esquema compatible con su versión de ownCloud, mantenga las rutas de las imágenes predecibles, cambie los colores mediante tokens de diseño en lugar de realizar ediciones ad hoc en el frontend y verifique el resultado en toda la interfaz web en lugar de juzgar el éxito desde una sola pantalla.