Los portales enterprise tienen un problema recurrente que las aplicaciones web convencionales no enfrentan con la misma intensidad: multiples personas crean paginas de forma independiente, y el resultado visual tiende a divergir con el tiempo. Un editor en el area de recursos humanos crea paginas con un estilo, otro editor en comunicaciones internas usa combinaciones de colores distintas, y en seis meses el portal parece un collage.
Liferay DXP abordo este problema con dos herramientas introducidas en la version 7.3+: Master Pages para estructura y StyleBooks para estilo. Juntas, forman un sistema de diseno que permite a los administradores definir las reglas visuales y estructurales, mientras los editores de contenido se enfocan en lo que mejor saben hacer -- crear contenido -- dentro de un marco gobernado.
Despues de trabajar con estas herramientas en varios proyectos, tengo una opinion matizada: son un avance significativo sobre el modelo anterior (temas monoliticos con FreeMarker), pero aun tienen limitaciones que debes conocer antes de apostar tu proyecto a ellas.
Antes de hablar de Master Pages y StyleBooks, necesitamos entender las Content Pages, porque son el contexto donde estas herramientas cobran sentido.
A partir de Liferay 7.3, las Content Pages reemplazaron a las Widget Pages como el tipo de pagina recomendado. La diferencia fundamental es que las Content Pages ofrecen un editor visual de arrastrar y soltar donde los editores pueden componer paginas usando fragmentos (componentes visuales predefinidos), organizarlos en grids responsivos, y configurar estilos basicos sin tocar codigo.
Este modelo democratizo la creacion de paginas -- pero tambien abrio la puerta a la inconsistencia visual, porque cada editor tiene libertad para configurar colores, fuentes y espaciados de forma individual en cada fragmento. Master Pages y StyleBooks existen para poner limites sanos a esa libertad.
Una Master Page define la estructura contenedora de una pagina: header, footer, barras laterales, y la zona central donde los editores colocan contenido. Conceptualmente, es el equivalente a un layout template, pero con la flexibilidad del editor visual.
El elemento central de una Master Page es la Drop Zone -- un area designada donde los editores de contenido pueden agregar y organizar fragmentos. Todo lo que esta fuera de la Drop Zone es fijo e inmodificable para los editores. Esto te permite garantizar que el header de navegacion, el footer institucional, y cualquier barra lateral de contexto se mantengan consistentes en todas las paginas que usen esa Master Page.
En el panel de administracion de Liferay, accedes a Design > Page Templates > Masters. Al crear una nueva Master Page, el editor visual te presenta un lienzo donde puedes:
Un patron comun es crear Master Pages diferenciadas para distintas secciones del portal:
Cada Content Page puede tener una Master Page asignada. Al crear una nueva pagina, seleccionas la Master Page como base. Las paginas existentes tambien pueden cambiarse a una Master Page diferente sin perder el contenido de la Drop Zone.
Esto permite una gobernanza a nivel de sitio: el administrador define las Master Pages disponibles y los editores eligen entre las opciones aprobadas. No pueden modificar la estructura fuera de la Drop Zone.
Si las Master Pages gobiernan la estructura, los StyleBooks gobiernan el estilo visual. Un StyleBook es un conjunto de tokens de diseno -- valores de colores, tipografia, espaciado, bordes y sombras -- que se aplican de forma coherente a todas las paginas y fragmentos del sitio.
Un StyleBook define valores para un conjunto de Frontend Token Categories que Liferay traduce a CSS custom properties (variables CSS). Cuando un fragmento referencia el color primario, no usa un valor fijo sino una variable que el StyleBook resuelve en runtime.
Por ejemplo, si tu StyleBook define el color primario como #2B6CB0, Liferay genera algo como:
:root {
--color-primary: #2B6CB0;
--color-secondary: #4A5568;
--font-family-base: 'Inter', sans-serif;
--spacing-unit: 1rem;
--border-radius-base: 4px;
}
Los fragmentos y widgets nativos de Liferay consumen estas variables, por lo que cambiar un valor en el StyleBook propaga el cambio automaticamente a todos los componentes que lo referencian.
Los tokens se organizan en categorias predefinidas:
Color: Define la paleta del sitio. Incluye tokens como color primario, secundario, exito, error, fondo, texto, y sus variantes. Liferay genera automaticamente algunas variantes (hover, active) basadas en los colores definidos.
Spacing: Controla margenes y paddings con una escala consistente. Tokens como spacer-1 a spacer-6 definen una progresion que los fragmentos usan para espaciado interno y externo.
General: Agrupa tokens de proposito general como border-radius, box-shadow, y opacidad. Estos tokens afectan transversalmente a todos los componentes del sitio.
Typography: Define familias tipograficas, tamanos de fuente para headings y cuerpo, line-height, y font-weight. Un cambio en el token de tipografia actualiza todos los textos del sitio.
Para crear un StyleBook, vas a Design > Style Books en el panel de administracion. El editor te muestra una vista previa del sitio y un panel lateral con todos los tokens organizados por categoria. Modificas los valores y ves el impacto en tiempo real.
Para extender los tokens predeterminados con tokens propios, necesitas crear una Frontend Token Definition en formato JSON dentro de tu tema custom:
{
"frontendTokenCategories": [
{
"label": "Marca Corporativa",
"name": "corporateBrand",
"frontendTokenSets": [
{
"label": "Colores de Marca",
"name": "brandColors",
"frontendTokens": [
{
"defaultValue": "#1A365D",
"label": "Color Institucional",
"mappings": [
{
"type": "cssVariable",
"value": "brand-institutional-color"
}
],
"name": "brandInstitutionalColor",
"type": "String"
}
]
}
]
}
]
}
Esta definicion agrega un token custom que genera la variable CSS --brand-institutional-color, disponible para tus fragmentos personalizados.
Aqui es donde necesito ser honesto: los StyleBooks son una herramienta que aun esta verde. Funcionan bien para casos basicos, pero tienen limitaciones que afectan proyectos reales.
No puedes definir estilos diferentes para tipos especificos de fragmentos a nivel de StyleBook. Si quieres que los botones de tipo "CTA" tengan un border-radius distinto al de los botones de formulario, el StyleBook no te ofrece esa distincion -- el token de border-radius se aplica de forma global. Terminas recurriendo a CSS custom para esas diferenciaciones, lo que anula parcialmente el proposito del StyleBook.
Los tokens son valores estaticos. No puedes definir un color primario que cambie segun el dispositivo, la hora del dia, el segmento de usuario, o cualquier otra condicion. Si necesitas un modo oscuro, necesitas un StyleBook separado y una forma de alternar entre ellos, que Liferay no proporciona nativamente.
Algunos nombres de tokens no son intuitivos. La relacion entre un token como info y donde se aplica visualmente requiere experimentacion. La documentacion ha mejorado, pero sigue habiendo tokens cuyo efecto no es evidente sin prueba y error.
Si tu proyecto usa un tema personalizado con CSS propio, los StyleBooks pueden generar conflictos de especificidad. Las variables CSS del StyleBook se definen en :root, pero si tu tema tambien define variables o usa selectores con mayor especificidad, el resultado puede ser impredecible. Lograr una coexistencia limpia requiere disciplina en la arquitectura CSS del tema.
El preview del editor de StyleBooks no siempre refleja con precision el resultado final. Fragmentos con JavaScript, componentes dinamicos, y widgets interactivos pueden verse diferentes en la vista previa versus la pagina publicada. Esto obliga a un ciclo de prueba manual que ralentiza el proceso.
El flujo de trabajo intencionado por Liferay es el siguiente:
Este flujo funciona especialmente bien en instancias multi-sitio de Liferay, donde una organizacion tiene multiples sitios (por ejemplo, un sitio publico, una intranet, y un portal de proveedores) que comparten estructura pero necesitan branding diferenciado. Cada sitio puede tener su propio StyleBook mientras comparte las mismas Master Pages.
El modelo anterior a Master Pages y StyleBooks era crear un tema de Liferay completo con templates FreeMarker, CSS custom, y logica de layout. Este enfoque ofrece control absoluto pero tiene desventajas claras:
Los StyleBooks proporcionan una capa de flexibilidad gobernada: los valores visuales cambian sin redespliegue, pero dentro de los limites que el desarrollador definio al crear los tokens. Es un equilibrio entre control tecnico y autonomia editorial.
Sin embargo, para proyectos con requisitos de diseno muy especificos -- interfaces altamente customizadas, animaciones complejas, layouts no convencionales -- los temas custom siguen siendo necesarios. La recomendacion practica es usar un tema custom que defina tokens extendidos compatibles con StyleBooks, obteniendo lo mejor de ambos mundos: control profundo cuando lo necesitas, y flexibilidad editorial cuando no.
Usa StyleBooks para consistencia de marca en portales multi-sitio. Define una paleta corporativa como StyleBook base, y permite que cada sitio la extienda o adapte sin divergir de la identidad principal.
Crea Master Pages especificas por tipo de contenido, no una Master Page generica. Una pagina de noticias tiene necesidades de layout distintas a una pagina de servicio o una landing page.
No abandones los temas custom si tu proyecto tiene requisitos visuales avanzados. Usa el tema como base solida y los StyleBooks como capa de configuracion. Define tokens custom en tu tema que representen las decisiones de diseno mas granulares.
Documenta tus tokens. Crea una guia interna que mapee cada token a su efecto visual con capturas de pantalla. Esto acelera la configuracion de StyleBooks por personas que no participaron en el desarrollo inicial.
Testea en paginas reales, no solo en el preview del editor. Crea una pagina de referencia con todos los fragmentos y componentes del portal para validar el efecto completo de un StyleBook antes de aplicarlo al sitio.
Los StyleBooks y Master Pages representan la direccion correcta para Liferay -- un sistema de diseno gobernado que separa la definicion del estilo de la creacion del contenido. Pero todavia necesitan madurar, especialmente en granularidad de tokens y herramientas de preview. Usarlos con conocimiento de sus limitaciones actuales te permite aprovechar sus beneficios sin frustrarte con lo que aun no pueden hacer.