Создание собственных страниц JS-модулей

Скопировать ссылку на статью

Скопировано

Содержание

• Страницы в конфигурации модуля
• Какой endpoint использовать
• URL страницы
• Единая точка входа для виджетов и страниц
• Компоновка страниц
  • Общие правила
  • 1. Страница со списком сущностей
  • 2. Страница-карточка
  • 3. Страница с несколькими колонками
  • 4. Страница с collapse-блоками
  • 5. UiModalSidebar (шторка)
  • 6. UiModalWindow (модальное окно)
• Когда использовать страницы

Помимо виджетов в target, JS-модуль может содержать собственные страницы внутри CRM. Такой сценарий подходит, когда модулю нужен отдельный экран со списком, карточкой, настройками или сложной формой.

Для собственных страниц используются конфигурация pages, endpoint запуска, внутренний адрес CRM и общие правила компоновки интерфейса. Технические детали запуска страниц опираются на пакет @retailcrm/embed-ui-v1-endpoint, а рекомендации по интерфейсу — на v1-components и руководство по компоновке страниц.

Страницы в конфигурации модуля

Чтобы модуль содержал страницы, в его конфигурации нужно указать поле pages.

Для pages поддерживаются два варианта:

• короткая запись строкой: код страницы;
• объект с настройками меню и справочной информацией.

Пример:

{
  "pages": [
    {
      "code": "returns",
      "menu": "activity_main_menu",
      "menuItemOrdering": 15,
      "menuItemTitle": {
        "ru": "Возвраты",
        "en": "Returns",
        "es": "Devoluciones"
      },
      "pageHelpLink": null
    }
  ]
}

В объектной форме для страницы могут быть заданы:

• code — символьный код страницы внутри модуля;
• menu — код корневого меню CRM, в которое должна быть добавлена страница;
• parentMenuItemCode — код родительского пункта меню, если страницу нужно вложить в существующий или модульный пункт;
• menuItemOrdering — числовой порядок отображения пункта меню;
• menuItemTitle — локализованный заголовок пункта меню;
• pageHelpLink — локализованная ссылка на справку или документацию страницы.

Если для страницы указаны поля, связанные с меню, CRM добавляет ссылку на эту страницу в навигацию как новый пункт или подпункт того раздела, который был задан в конфигурации.

Какой endpoint использовать

Для модулей со страницами следует использовать точку входа из @retailcrm/embed-ui-v1-endpoint/remote.

Практически это означает, что сценарии со страницами собираются через:

• definePageRunner(...)
• или defineRunner(...), если в модуле одновременно есть и страницы, и виджеты

Для сценариев со страницами используется режим v1-endpoint.

В дескрипторе frontend-части для такого сценария нужно указать runner: "worker". Это требуется для запуска endpoint, который обслуживает страницы и, при необходимости, target-виджеты через единую точку входа.

При регистрации модуля значение worker необходимо передать в поле integrationModule[integrations][embedJs][runner]. Для модулей со страницами legacy-режим iframe не используется.

URL страницы

По текущему поведению CRM страница опубликованного модуля открывается по адресу:

/modules/<moduleCode>/<pageCode>

То есть в адресе страницы используется связка moduleCode + pageCode, где moduleCode — это code интеграционного модуля.

Единая точка входа для виджетов и страниц

Одна интеграция может одновременно иметь target-виджеты и отдельные страницы. Такой подход используется, например, в promoModule из библиотеки примеров.

Такой endpoint должен публиковаться как JS-entrypoint и запускаться с runner: "worker".

Пример:

import {
  definePageRunner,
  defineRunner,
  defineWidgetRunner,
  runEndpoint,
} from '@retailcrm/embed-ui-v1-endpoint/remote'

import PromoPicker from './PromoPicker.vue'
import SettingsPage from './SettingsPage.vue'

runEndpoint(defineRunner({
  widgets: [{
    'order/card:common.after': defineWidgetRunner(PromoPicker),
  }],
  pages: [{
    settings: definePageRunner(SettingsPage),
  }],
}))

Компоновка страниц

Для компоновки интерфейсов страниц в v1-endpoint есть отдельное руководство: layout.md.

В этом разделе формулировки дополнены текущими сведениями о компонентах и размерах из v1-components.

Общие правила

Размеры UiButton в текущей реализации:

Варианты приоритета и семантики задаются через appearance и variant:

Для контентных подложек базовое правило такое:

Базовая сетка расстояний строится на шаге 4px: 4, 8, 12, 16, 20, 24, 28, 32.

1. Страница со списком сущностей

Страница со списком сущностей используется в следующих случаях:

Страница состоит из следующих блоков:

Компонентная основа:

Практические замечания:

2. Страница-карточка

Страница-карточка используется для страницы настроек или карточки сущности, которая состоит из форм.

Страница состоит из следующих блоков:

Компонентная основа:

Практические замечания:

3. Страница с несколькими колонками

Страница с несколькими колонками используется для карточки сущности в редактируемом или нередактируемом режиме, а также в случаях, когда смысловые блоки нужно разнести по нескольким колонкам.

Компонентная основа:

Практические замечания:

4. Страница с collapse-блоками

Страница с collapse-блоками используется для настроек, разбитых на смысловые группы.

Компонентная основа:

Практические замечания:

В Collapse-блоках лучше не размещать:

• Сложные таблицы.
• Другие Collapse-блоки.
• Контент в 2 колонки на разных подложках.

5. UiModalSidebar (шторка)

UiModalSidebar используется, когда нужна небольшая форма по месту, нужно показать дополнительную информацию по месту или сценарий оформляется как карточка небольшой сущности, где немного полей и настроек.

Размеры:

Графические примеры:

Основные составляющие:

Компонентная основа:

Практические замечания:

В шторки не рекомендуется размещать:

• Collapse-блоки.
• Контент в 2 колонки на разных подложках.
• Громоздкие, большие и сложные интерфейсы.

Для таких сценариев лучше делать отдельную полноценную страницу или модальное окно.

6. UiModalWindow (модальное окно)

UiModalWindow используется для отображения вспомогательных больших таблиц по месту, а также для отображения дополнительных настроек по месту, когда шторки уже не хватает.

Размеры:

Графические примеры:

Основные составляющие:

Компонентная основа:

Практические замечания:

Когда использовать страницы

Страницы подходят для сценариев, где модулю требуется:

• отдельный экран внутри CRM;
• собственная структура интерфейса;
• работа с меню и описанием страницы;
• query string и навигация внутри сценария страницы.

Подробно про API навигации хоста, useRouter() и query string см. в статье Навигация и маршрутизация в JS-модулях.