Layouts

En Osumi Framework, un layout es un componente especial que envuelve la salida del componente principal de una ruta.

Los layouts se utilizan normalmente para compartir la misma estructura HTML entre varias rutas.

Un layout se aplica después del componente de la ruta y de la fase Middleware afterRender. Recibe la salida actual del componente como su body.

Las respuestas OStreamResponse son una excepción: no tienen un cuerpo materializado que pueda envolverse y no utilizan layout.

1. Flujo de renderizado

Para una respuesta tradicional:

Enrutamiento
↓
Middlewares before
↓
Componente
↓
Middlewares afterRender
↓
Layout
↓
Middlewares afterResponse
↓
Respuesta HTTP

Para una respuesta streaming:

Enrutamiento
↓
Middlewares before
↓
Componente → OStreamResponse
↓
Middlewares afterRender
↓
Middlewares afterResponse
↓
Emisión del stream

Esto significa:

• afterRender se ejecuta antes del layout en respuestas tradicionales.
• El layout envuelve el contenido resultante.
• afterResponse se ejecuta después de producir el cuerpo final tradicional.
• En streaming, el layout se omite y afterResponse termina antes de enviar el primer byte.

Si before detiene la ejecución, se omiten el componente y el layout.

Si afterRender detiene la ejecución, se omite el layout.

2. Layout predeterminado

Los nuevos proyectos incluyen un layout predeterminado. DefaultLayoutComponent expone normalmente title y body.

3. Definición de layouts en el enrutamiento

ORoute::layout(
	MainLayoutComponent::class,
	static function (): void {
		ORoute::get('/home', HomeComponent::class);
		ORoute::get('/contact', ContactComponent::class);
	}
);

ORoute::layout() acepta un tercer argumento opcional con Middlewares.

ORoute::group(
	'/admin',
	AdminLayoutComponent::class,
	static function (): void {
		ORoute::get('/dashboard', DashboardComponent::class);
	}
);

ORoute::group() acepta un cuarto argumento opcional con Middlewares.

Aunque una ruta esté dentro de un grupo con layout, si su componente devuelve OStreamResponse ese layout se omite.

Consulta /docs/es/concepts/middlewares.md.

4. Inyección de CSS / JS

Los layouts son el punto donde Osumi Framework inyecta los recursos frontend configurados en documentos que contienen </head>.

Esta inyección no se aplica a respuestas streaming.

5. Mejores prácticas

• Mantén los layouts centrados en estructura y presentación.
• No incluyas lógica de negocio en los layouts.
• Usa layouts dedicados para distintas áreas cuando sea útil.
• No dependas de un layout para cabeceras necesarias en una descarga streaming; defínelas en OStreamResponse o en Middlewares.

6. Resumen

• Los layouts envuelven respuestas tradicionales basadas en componentes.
• afterRender se ejecuta antes del layout.
• afterResponse se ejecuta después del cuerpo final tradicional.
• Un stop en before o afterRender evita el layout.
• OStreamResponse omite siempre el layout.