Views

El módulo wippy/views proporciona un sistema de páginas y componentes virtuales con renderizado de plantillas, gestión de recursos y mapeo de variables de entorno. Las páginas pueden estar respaldadas por plantillas Jet o componentes externos (SPAs, micro-frontends).

Configuración

Agregue el módulo a su proyecto:

wippy add wippy/views
wippy install

Declare la dependencia:

version: "1.0"
namespace: app

entries:
  - name: dep.views
    kind: ns.dependency
    component: wippy/views
    version: "*"
    parameters:
      - name: api_router
        value: app:api.public
      - name: env_storage
        value: app:env.storage

Páginas de Plantilla

Las páginas de plantilla se renderizan en el lado del servidor usando plantillas Jet:

entries:
  - name: contact_page
    kind: template.jet
    meta:
      type: view.page
      name: contact
      title: Contact Us
      icon: mail
      order: 5
      group: main
      group_icon: layout-grid
      group_order: 1
      announced: true
      secure: false
    data:
      set: app.templates:default
      data_func: app:contact_data
      resources:
        - contact_styles

Metadatos de Página

Datos de Plantilla

La función data_func recibe { params, query } y retorna una tabla que se convierte en el contexto data en la plantilla.

Pipeline de Renderizado

1. Cargar la página desde el registro
2. Verificar acceso (seguridad)
3. Llamar a data_func si está definido
4. Recolectar recursos: globales + recursos del conjunto de plantillas + recursos específicos de la página
5. Cargar variables de entorno
6. Renderizar plantilla Jet con contexto: { data, resources, query_params, route_params, env }

Páginas de Componente

Las páginas de componente apuntan a aplicaciones externas (SPAs, micro-frontends):

entries:
  - name: dashboard
    kind: registry.entry
    meta:
      type: view.page
      name: dashboard
      title: Dashboard
      icon: chart-bar
      url: https://cdn.example.com/dashboard/
      secure: true
      announced: true
    data:
      proxy:
        enabled: true
        css:
          prime_vue: true
          theme_config: true
        tailwind_config: true

La API retorna un descriptor de componente con la URL base y la configuración del proxy. El frontend renderiza el componente en un iframe o en línea.

Campos de Componente

Configuración del Proxy

El proxy controla qué CSS y comportamiento se inyecta en el componente:

Componentes de Vista

Componentes independientes que no son páginas (sin entrada de navegación):

entries:
  - name: widget
    kind: registry.entry
    meta:
      type: view.component
      name: chat-widget
      title: Chat Widget
      url: https://cdn.example.com/chat-widget/
    data:
      proxy:
        enabled: true

Los componentes usan meta.type: view.component en lugar de view.page. Por defecto usan index.js como punto de entrada.

Recursos

Los recursos son archivos CSS, JS y de fuentes asociados con las páginas:

entries:
  - name: global_styles
    kind: registry.entry
    meta:
      type: view.resource
      name: Global Styles
      resource_type: style
      global: true
      order: 1
      url: https://cdn.example.com/global.css

  - name: app_script
    kind: registry.entry
    meta:
      type: view.resource
      name: App Script
      resource_type: script
      template_set: app.templates:default
      order: 10
      url: https://cdn.example.com/app.js
      defer: true

Campos de Recurso

Recolección de Recursos

Los recursos se recolectan en tres capas, fusionados en orden:

1. Recursos globales — global: true, aplicados a todas las páginas
2. Recursos del conjunto de plantillas — coincidentes por ID de template_set
3. Recursos de página — listados en el array data.resources

Dentro de cada capa, los recursos se agrupan por resource_type y se ordenan por order.

Mapeo de Variables de Entorno

El cargador de entorno mapea variables de entorno a claves del contexto de plantilla mediante un sistema basado en prioridad.

Definición de Mapeos

entries:
  - name: app_env
    kind: registry.entry
    meta:
      type: view.env_mapping
      priority: 20
    data:
      mappings:
        api_endpoint: API_BASE_URL
        app_title: APP_NAME
        debug_mode: DEBUG_ENABLED

Cada entrada de mapeo asocia claves de contexto (usadas en plantillas como env.api_endpoint) con nombres de variables de entorno.

Sistema de Prioridad

Mayor prioridad gana cuando múltiples mapeos definen la misma clave de contexto.

Uso en Plantillas

Los valores de entorno resueltos están disponibles en el objeto de contexto env:

<script>
    window.API_URL = "{{ env.api_endpoint }}";
    document.title = "{{ env.app_title }}";
</script>

Endpoints de la API HTTP

El módulo views registra estos endpoints en el router configurado:

Respuesta de Renderizado

Para páginas de plantilla, retorna HTML renderizado con el content_type de la página.

Para páginas de componente, retorna un descriptor:

{
    "name": "dashboard",
    "version": "1.0.0",
    "specification": "wippy-component-1.0",
    "title": "Dashboard",
    "baseUrl": "https://cdn.example.com/dashboard/",
    "wippy": {
        "type": "page",
        "path": "index.html",
        "proxy": {
            "enabled": true,
            "injections": {
                "css": { "fonts": true, "themeConfig": true, "iframe": true },
                "tailwindConfig": false,
                "resizeObserver": true,
                "preventLinkClicks": true
            }
        }
    }
}

Control de Acceso

Las páginas con secure: true requieren autenticación. El registro de páginas verifica security.can("view", "page:<page_id>") contra el actor y el ámbito actuales.

Las páginas no seguras siempre son accesibles. La bandera announced controla la visibilidad en los listados de navegación sin afectar el acceso.

Calificación de IDs

Los IDs relativos en las definiciones de página se califican con el namespace de la entrada:

# En el namespace "app"
data:
  data_func: my_data_func       # se resuelve a app:my_data_func
  set: templates:default         # permanece como templates:default (ya calificado)
  resources:
    - page_styles                # se resuelve a app:page_styles

Véase También

• Facade - Facade de iframe del frontend y barra lateral de navegación
• Template - Motor de plantillas Jet
• Security - Actores de seguridad y control de acceso
• Environment - Almacenamiento de variables de entorno
• Resumen del Framework - Uso del módulo del framework