Маршруты подсказок

Маршрут подсказок представляет собой пошаговые подсказки, которые рассказывают пользователю о функционале конкретной страницы или карточки.

Подсказки и маршруты подсказок для функциональных областей создаются и редактируются программистами-технологами.

Подробное описание приведено в стандарте и спецификации.

Прикладные программисты размечают контролы и DOM-элементы, на которые можно навесить подсказки.

Разметка контролов и DOM-элементов

Разметка осуществляется путем добавления контролу или DOM-элементу атрибута data-name. Значение атрибута должно быть уникальным в рамках страницы или карточки. Контролы и DOM-элементы, имеющие атрибуты data-qa, являются автоматически размеченными для добавления подсказок при условии уникальности значения атрибута в рамках страницы или карточки.

Пример 1:

<!-- WML -->
<div data-name="demo-HintRoutes__inputContainer"
     class="controls-padding-2xs">
    <Controls.input:Label caption="Label"/>
    <Controls.input:Text placeholder="Поле ввода"/>
</div>

Пример 2:

<!-- WML -->
<Controls.buttons:Button
         attr:data-name="sabyPage-addButton"
         attr:class="sabyPage-MainLayout__addButton ws-flex-shrink-0"
         icon="icon-RoundPlus"
         iconStyle="default"
         buttonStyle="pale"
         iconSize="m"
         viewMode="functionalButton"
         inlineHeight="xl"
         name="addButton"
         readOnly="{{ readOnly }}"
         on:click="_addButtonClickHandler()"/>

Ограничения, накладываемые на разметку

1. Выделение элемента с подсказкой отображается строго по контуру размеченного элемента

Если элемент с атрибутом data-name содержит текст или другой контент, контент должен отделяться отступами.

<!-- Плохо -->
<Controls.buttons:Button
           attr:data-name="demo-HintRoutes__buttonLink"
           viewMode="link"
           caption="Ссылка"/>

<!-- Хорошо -->
<div data-name="demo-HintRoutes__buttonLink" class="controls-padding-s">
   <Controls.buttons:Button
           viewMode="link"
           caption="Ссылка"/>
</div>

2. Размеченный элемент не должен иметь псевдоэлементы ::before и ::after

Это необходимо для корректного выделения обводкой размеченного элемента при отображении подсказки.

3. К размеченному элементу автоматически применяется стиль position: relative при отображении подсказки

Не следует размечать абсолютно позиционируемые DOM-элементы или элементы с position: sticky, так как они будут отображаться некорректно при показе подсказки.

Привязка маршрутов подсказок к отображаемому контенту

Маршруты подсказок привязываются к отображаемому контенту через идентификатор "сущности" entityId. "Сущностью" может быть страница, вкладка, пункт мастера, stack-панель или вкладка в stack-панели.

1. Страницы, вкладки, пункты мастера

Для страниц, вкладок, пунктов мастера в качестве entityId используется идентификатор страницы pageId. Привязка маршрутов осуществляется автоматически.

2. Stack-панели, вкладки в stack-панелях

Для привязки маршрута подсказок к stack-панели или вкладке в stack-панели, нужно передать в опцию rightPanelOptions stack-панели следующие поля:

  • entityId - уникальный идентификатор stack-панели или вкладки в stack-панели.

  • title - заголовок stack-панели или вкладки в stack-панели. Необходим для корректного отображения группировки маршрутов по сущностям в административной панели системы помощи.

Пример:

<!-- WML -->
<Controls.popupTemplate:Stack rightPanelOptions="{{ _rightPanelOptions }}">
    <ws:bodyContentTemplate>
        ...
    </ws:bodyContentTemplate>
</Controls.popupTemplate:Stack>
// TypeScript
...
this._rightPanelOptions = {
    entityId: 'contractor-card',
    title: 'Карточка контрагента'
};

При переключении вкладок в stack-панели нужно слать событие Store 'helpEntityChanged' с параметрами entityId и title вкладки, на которую происходит переключение.

Пример:

// TypeScript
import Store from 'Controls/Store';
...
Store.sendCommand('helpEntityChanged', {
    entityId: 'crm-params-tab',
    title: 'Параметры карточки контрагента'
});

Маршрут подсказок

Если элемент с навешенной на него подсказкой отсутствует в верстке, будет осуществлен автоматический переход к следующему шагу маршрута.

Контролы, размеченные для маршрутов подсказок

Ниже приведены контролы, элементы которых уже размечены для маршрутов подсказок. В качестве значения атрибута data-name используется keyProperty соответствующих элементов.

Совместимость с механизмом всплывающих подсказок системы помощи

Если на странице или карточке есть опубликованный маршрут подсказок, помеченный признаком "Основной", по клику на пункт меню помощи "Помощь на странице" будет запущен этот маршрут. Если маршрутов нет, но настроены всплывающие подсказки, по клику на "Помощь на странице" отобразятся всплывающие подсказки.