Views

Модуль wippy/views предоставляет систему виртуальных страниц и компонентов с рендерингом шаблонов, управлением ресурсами и маппингом переменных окружения. Страницы могут опираться на Jet-шаблоны или внешние компоненты (SPA, микро-фронтенды).

Установка

Добавьте модуль в проект:

wippy add wippy/views
wippy install

Объявите зависимость:

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

Шаблонные страницы

Шаблонные страницы рендерятся на сервере с помощью 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

Метаданные страницы

Данные шаблона

data_func получает { params, query } и возвращает таблицу, которая становится контекстом data в шаблоне.

Конвейер рендеринга

1. Загрузить страницу из реестра
2. Проверить доступ (security)
3. Вызвать data_func, если определена
4. Собрать ресурсы: глобальные + ресурсы набора шаблонов + ресурсы страницы
5. Загрузить переменные окружения
6. Отрендерить Jet-шаблон с контекстом: { data, resources, query_params, route_params, env }

Компонентные страницы

Компонентные страницы указывают на внешние приложения (SPA, микро-фронтенды):

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

API возвращает дескриптор компонента с базовым URL и конфигурацией прокси. Фронтенд рендерит компонент в iframe или inline.

Поля компонента

Конфигурация прокси

Прокси контролирует, какие CSS и поведение внедряются в компонент:

View-компоненты

Самостоятельные компоненты, не являющиеся страницами (без записи в навигации):

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

Компоненты используют meta.type: view.component вместо view.page. По умолчанию точкой входа является index.js.

Ресурсы

Ресурсы — это файлы CSS, JS и шрифтов, связанные со страницами:

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

Поля ресурса

Сбор ресурсов

Ресурсы собираются в три слоя, объединяемых по порядку:

1. Глобальные ресурсы — global: true, применяются ко всем страницам
2. Ресурсы набора шаблонов — сопоставляются по ID template_set
3. Ресурсы страницы — перечислены в массиве data.resources

Внутри каждого слоя ресурсы группируются по resource_type и сортируются по order.

Маппинг переменных окружения

Загрузчик env сопоставляет переменные окружения с ключами контекста шаблона через систему приоритетов.

Определение маппингов

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

Каждая запись маппинга связывает ключи контекста (используются в шаблонах как env.api_endpoint) с именами переменных окружения.

Система приоритетов

Более высокий приоритет побеждает, если несколько маппингов определяют один и тот же ключ контекста.

Использование в шаблонах

Разрешённые значения окружения доступны в объекте контекста env:

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

HTTP API эндпоинты

Модуль views регистрирует следующие эндпоинты на настроенном роутере:

Ответ рендеринга

Для шаблонных страниц возвращается отрендеренный HTML с content_type страницы.

Для компонентных страниц возвращается дескриптор:

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

Контроль доступа

Страницы с secure: true требуют аутентификации. Реестр страниц проверяет security.can("view", "page:<page_id>") относительно текущего актора и области.

Незащищённые страницы всегда доступны. Флаг announced контролирует видимость в списках навигации, не влияя на доступ.

Квалификация ID

Относительные ID в определениях страниц квалифицируются пространством имён записи:

# В пространстве имён "app"
data:
  data_func: my_data_func       # разрешается в app:my_data_func
  set: templates:default         # остаётся как templates:default (уже квалифицирован)
  resources:
    - page_styles                # разрешается в app:page_styles

См. также

• Facade — Iframe-фасад фронтенда и боковая панель навигации
• Template — Движок Jet-шаблонов
• Security — Акторы безопасности и контроль доступа
• Environment — Хранение переменных окружения
• Обзор фреймворка — Использование модулей фреймворка