Views

Das Modul wippy/views bietet ein virtuelles Seiten- und Komponentensystem mit Template-Rendering, Ressourcenverwaltung und Mapping von Umgebungsvariablen. Seiten können durch Jet-Templates oder externe Komponenten (SPAs, Micro-Frontends) gestützt werden.

Setup

Modul zum Projekt hinzufügen:

wippy add wippy/views
wippy install

Abhängigkeit deklarieren:

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

Template-Seiten

Template-Seiten werden serverseitig mit Jet-Templates gerendert:

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

Seiten-Metadaten

Template-Daten

Die data_func empfängt { params, query } und gibt eine Tabelle zurück, die zum data-Kontext im Template wird.

Rendering-Pipeline

1. Seite aus Registry laden
2. Zugriff prüfen (Sicherheit)
3. data_func aufrufen, falls definiert
4. Ressourcen sammeln: globale + Template-Set-Ressourcen + seitenspezifische Ressourcen
5. Umgebungsvariablen laden
6. Jet-Template mit Kontext rendern: { data, resources, query_params, route_params, env }

Komponenten-Seiten

Komponenten-Seiten verweisen auf externe Anwendungen (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

Die API gibt einen Komponentendeskriptor mit der Basis-URL und der Proxy-Konfiguration zurück. Das Frontend rendert die Komponente in einem iframe oder inline.

Komponentenfelder

Proxy-Konfiguration

Der Proxy steuert, welches CSS und Verhalten in die Komponente injiziert wird:

View-Komponenten

Eigenständige Komponenten, die keine Seiten sind (kein Navigationseintrag):

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

Komponenten verwenden meta.type: view.component anstelle von view.page. Sie verwenden standardmäßig index.js als Eintragspunkt.

Ressourcen

Ressourcen sind CSS-, JS- und Font-Dateien, die mit Seiten verknüpft sind:

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

Ressourcenfelder

Ressourcensammlung

Ressourcen werden in drei Schichten gesammelt und in dieser Reihenfolge zusammengeführt:

1. Globale Ressourcen — global: true, auf alle Seiten angewendet
2. Template-Set-Ressourcen — über die template_set-ID zugeordnet
3. Seitenressourcen — im data.resources-Array gelistet

Innerhalb jeder Schicht werden Ressourcen nach resource_type gruppiert und nach order sortiert.

Mapping von Umgebungsvariablen

Der Env-Loader bildet Umgebungsvariablen über ein prioritätsbasiertes System auf Template-Kontext-Schlüssel ab.

Mappings definieren

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

Jeder Mapping-Eintrag verknüpft Kontext-Schlüssel (in Templates als env.api_endpoint verwendet) mit Umgebungsvariablennamen.

Prioritätssystem

Höhere Priorität gewinnt, wenn mehrere Mappings denselben Kontext-Schlüssel definieren.

Verwendung in Templates

Aufgelöste Umgebungswerte sind im env-Kontextobjekt verfügbar:

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

HTTP-API-Endpunkte

Das Views-Modul registriert diese Endpunkte am konfigurierten Router:

Render-Antwort

Für Template-Seiten wird gerenderter HTML mit dem content_type der Seite zurückgegeben.

Für Komponenten-Seiten wird ein Deskriptor zurückgegeben:

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

Zugriffskontrolle

Seiten mit secure: true erfordern Authentifizierung. Die Seiten-Registry prüft security.can("view", "page:<page_id>") gegen den aktuellen Aktor und Scope.

Nicht-sichere Seiten sind immer zugänglich. Das announced-Flag steuert die Sichtbarkeit in Navigationslisten, ohne den Zugriff zu beeinflussen.

ID-Qualifizierung

Relative IDs in Seitendefinitionen werden mit dem Namespace des Eintrags qualifiziert:

# In namespace "app"
data:
  data_func: my_data_func       # resolves to app:my_data_func
  set: templates:default         # stays as templates:default (already qualified)
  resources:
    - page_styles                # resolves to app:page_styles

Siehe auch

• Facade - Frontend-iframe-Facade und Navigations-Sidebar
• Template - Jet-Template-Engine
• Sicherheit - Sicherheitsaktoren und Zugriffskontrolle
• Umgebung - Speicherung von Umgebungsvariablen
• Framework-Übersicht - Verwendung des Framework-Moduls