Views

O módulo wippy/views fornece um sistema de páginas e componentes virtuais com renderização de templates, gerenciamento de recursos e mapeamento de variáveis de ambiente. Páginas podem ser respaldadas por templates Jet ou componentes externos (SPAs, micro-frontends).

Configuração

Adicione o módulo ao seu projeto:

wippy add wippy/views
wippy install

Declare a dependência:

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 Template

Páginas template renderizam no lado do servidor usando templates 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

Metadados da Página

Dados do Template

A data_func recebe { params, query } e retorna uma tabela que se torna o contexto data no template.

Pipeline de Renderização

1. Carrega a página do registro
2. Verifica acesso (segurança)
3. Chama data_func se definida
4. Coleta recursos: globais + recursos do conjunto de templates + recursos específicos da página
5. Carrega variáveis de ambiente
6. Renderiza o template Jet com o contexto: { data, resources, query_params, route_params, env }

Páginas de Componente

Páginas de componente apontam para aplicações 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

A API retorna um descritor de componente com a URL base e configuração de proxy. O frontend renderiza o componente em um iframe ou inline.

Campos do Componente

Configuração do Proxy

O proxy controla qual CSS e comportamento é injetado no componente:

Componentes de View

Componentes autônomos que não são páginas (sem entrada de navegação):

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

Componentes usam meta.type: view.component em vez de view.page. Eles assumem index.js como ponto de entrada por padrão.

Recursos

Recursos são arquivos CSS, JS e fontes associados a 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

Coleta de Recursos

Recursos são coletados em três camadas, mescladas em ordem:

1. Recursos globais — global: true, aplicados a todas as páginas
2. Recursos do conjunto de templates — combinados pelo ID de template_set
3. Recursos da página — listados no array data.resources

Dentro de cada camada, recursos são agrupados por resource_type e ordenados por order.

Mapeamento de Variáveis de Ambiente

O carregador de env mapeia variáveis de ambiente para chaves de contexto do template através de um sistema baseado em prioridade.

Definindo Mapeamentos

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 mapeamento associa chaves de contexto (usadas em templates como env.api_endpoint) com nomes de variáveis de ambiente.

Sistema de Prioridade

A maior prioridade vence quando múltiplos mapeamentos definem a mesma chave de contexto.

Usando em Templates

Valores de ambiente resolvidos estão disponíveis no objeto de contexto env:

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

Endpoints HTTP da API

O módulo views registra estes endpoints no roteador configurado:

Resposta de Renderização

Para páginas template, retorna o HTML renderizado com o content_type da página.

Para páginas de componente, retorna um descritor:

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

Controle de Acesso

Páginas com secure: true exigem autenticação. O registro de páginas verifica security.can("view", "page:<page_id>") contra o ator e escopo atuais.

Páginas não seguras estão sempre acessíveis. A flag announced controla a visibilidade nas listagens de navegação sem afetar o acesso.

Qualificação de IDs

IDs relativos em definições de páginas são qualificados com o namespace da entrada:

# No namespace "app"
data:
  data_func: my_data_func       # resolve para app:my_data_func
  set: templates:default         # permanece como templates:default (já qualificado)
  resources:
    - page_styles                # resolve para app:page_styles

Veja Também

• Facade - Facade de iframe do frontend e barra lateral de navegação
• Template - Motor de templates Jet
• Segurança - Atores de segurança e controle de acesso
• Ambiente - Armazenamento de variáveis de ambiente
• Visão Geral do Framework - Uso do módulo do framework