Al crear sitios corporativos o sitios para clientes como agencia, a menudo surge esta situación: el cliente quiere un diseño de frontend completamente diferente, pero esta plantilla pertenece solo a este cliente, no puede entrar en el paquete del producto ni debería aparecer en otros sitios. El «tema privado» de KingCMS X1 está pensado para este escenario: se coloca en el directorio privado del sitio, solo lo ve este sitio y no se sobrescribe al actualizar.

KingCMS X1 前台首页示例
Con el mismo panel de administración, se pueden asignar temas de frontend completamente distintos a diferentes sitios.

Dónde se colocan los temas privados

El directorio predeterminado es local/themes/<id>/ bajo la raíz del sitio (en el repositorio de desarrollo es x1/local/themes/). Cada tema tiene un subdirectorio y su estructura es idéntica a la de los temas oficiales: theme.json es obligatorio, templates/ contiene las plantillas Twig, assets/ contiene imágenes y estilos, lang/ contiene los textos del tema y preview.png es opcional y se usa como imagen de vista previa en el panel de administración.

<id> debe coincidir con el id de theme.json y solo puede contener letras minúsculas, números, guiones bajos y guiones. Este directorio no entra en Git, ni en el paquete de publicación ni en el paquete de actualización; al actualizar se reemplaza el paquete completo, pero local/ se conserva intacto.

Lista mínima

theme.json debe tener al menos cuatro campos: id, name, version y author; si falta uno o el formato es incorrecto, este tema se omite. También hay campos de uso común como screenshot (nombre del archivo de vista previa), supported_modules (módulos de los que depende), options y ad_slots. Las reglas de validación de estos dos últimos son las mismas que en los temas oficiales; las estructuras no válidas se ignoran.

La forma más sencilla: copiar un tema oficial y modificarlo

No empieces desde cero. Primero copia un tema oficial completo a local/themes/, cámbiale el id y el name por los tuyos y luego reemplaza plantillas y recursos página por página. Proporciona solo las plantillas de las páginas que necesites: las plantillas que no encuentres se resolverán con el tema oficial default y, por último, con las plantillas propias del módulo; por eso puedes modificar solo la página de inicio, los listados y los detalles, y dejar el resto con los valores predeterminados.

Los recursos del tema se sirven mediante la ruta /n/<id>/...: primero se busca en assets/ de la raíz del tema oficial, luego en assets/ de la raíz privada y, si no existe en ninguna, se recurre al tema predeterminado. Los textos del tema se leen desde el directorio donde realmente se encuentra el tema.

KingCMS X1 前台商品详情页示例
Con un tema privado se pueden rehacer solo las páginas de la tienda y seguir usando las plantillas predeterminadas para el resto.

Activación y conflictos

Una vez colocado el directorio, el tema aparecerá en la lista «Temas» del panel de administración marcado como «Privado»; se puede previsualizar, activar y eliminar. Los temas privados no ofrecen edición de plantillas en línea. Al activarlo, theme.active registra el id del tema; volver a un tema oficial no requiere pasos adicionales.

Hay una regla estricta: si el id coincide, el tema oficial tiene prioridad. Si en el directorio privado aparece un id con el mismo nombre que un tema oficial, el tema oficial se muestra con normalidad, el privado se omite y, además, se escribe una entrada en error_log y se añade a la lista de diagnóstico, sin provocar errores en el sitio. Por eso, el tema personalizado debe usar un id propio; no lo llames default ni furniture.

Consideraciones

  • Copia de seguridad: local/ no entra en el paquete de publicación; aunque se conserva al actualizar, debes hacer una copia de seguridad por separado. Si cambias de servidor, recuerda llevarlo contigo.
  • Eliminación: si eliminas un tema privado que está en uso, el tema actual volverá automáticamente a default; no se mostrará una pantalla en blanco.
  • Versión: incrementa version al modificar el tema para poder identificar fácilmente qué versión se está usando en producción.
  • Licencia: los temas privados solo resuelven el «diseño exclusivo de este sitio»; no deben usarse para eludir licencias comerciales ni para distribuir temas oficiales.

Resumen

Los temas privados separan la «personalización para el cliente» de la «actualización del producto»: el diseño se coloca en local/themes/ y el paquete de actualización solo gestiona el núcleo y los temas oficiales, sin que ambas partes se sobrescriban. Para agencias y operación de múltiples sitios, esto es mucho más estable que fusionar plantillas manualmente antes de cada actualización.