Как добавлять JEXL-скрипты в справочник#
В статье описано, как добавлять новые JEXL-скрипты в справочник: как выбрать раздел, как оформить страницу раздела и как правильно оформить сам скрипт. Инструкция нужна, чтобы все страницы справочника выглядели одинаково, пополнялись по одному правилу и оставались удобными для поиска и использования.
Добавление и изменение скриптов выполняется через merge request.
Если у вас нет доступа к репозиторию, нет опыта работы с Git или вы не уверены, как правильно оформить изменения, обратитесь к Гребневу Алексею.
Общий принцип#
Справочник JEXL-скриптов состоит из тематических разделов. Раздел — это отдельная страница, внутри которой собраны скрипты одной тематики.
Раздел обычно включает название, краткое описание и список скриптов. Скрипты внутри раздела идут последовательно одним списком.
Разделение на разделы нужно, чтобы не смешивать на одной странице разные сценарии, упростить поиск нужного примера и поддерживать единый понятный формат справочника.
Порядок добавления#
Определите, подходит ли скрипт в один из текущих разделов.
Если подходит, добавьте его в этот раздел.
Если скрипт явно не подходит ни в один текущий раздел, создайте новый раздел.
Подготовьте описание скрипта.
Вставьте код скрипта в текст страницы.
При необходимости добавьте вспомогательные файлы.
Проверьте оформление.
Создайте merge request.
Разделы справочника#
Как выбрать раздел#
Перед добавлением скрипта определите, подходит ли он в один из текущих разделов.
Ориентируйтесь прежде всего на сценарий использования скрипта, а не на используемые классы, методы или API. Скрипт нужно размещать там, где его будет искать пользователь.
Если скрипт можно логично отнести к нескольким разделам, выберите тот, в котором его ожидаемо искать по задаче.
Что делать, если неясно, в какой раздел добавить скрипт#
Если вы сомневаетесь, не создавайте новый раздел сразу. Укажите это в merge request и при необходимости предложите наиболее подходящий, по вашему мнению, вариант.
Когда создавать новый раздел#
Новый раздел создавайте только тогда, когда вы однозначно понимаете, что скрипт не подходит ни в один текущий раздел.
Не создавайте новый раздел на всякий случай или просто потому, что сомневаетесь. Если скрипт можно логично разместить в существующем разделе, лучше добавить его туда.
Название раздела должно отражать задачу или сценарий использования, а не название класса, таблицы или API.
Пример корректного раздела
Для оформления используйте существующие страницы справочника как шаблон. Пример: Администрирование
Структура скрипта#
Каждый скрипт размещается внутри раздела как отдельный подпункт с заголовком третьего уровня.
В составе скрипта указываются название, описание, место применения, тип и тело скрипта.
Описание должно кратко и понятно объяснять, что делает скрипт, где он применяется и, если это полезно, чем он может служить как пример. Не нужно пересказывать код построчно, писать слишком общие формулировки или добавлять лишнюю теорию.
Место применения указывается в формате пути:
Раздел > Подраздел > Действие
Тип всегда указывается одинаково:
JEXL-скрипт
Тело скрипта вставляется непосредственно в текст страницы и не прикладывается отдельным файлом.
Внутри самого скрипта желательны комментарии, поясняющие основные действия. Они помогают быстрее понять логику примера и снижают риск ошибок при адаптации скрипта.
Добавление вспомогательных файлов#
Если для работы скрипта требуется дополнительный файл, например Excel-шаблон, его необходимо добавить в документацию.
Такие файлы не заменяют тело скрипта. Скрипт всегда вставляется в текст страницы, а вспомогательный файл добавляется отдельно.
Чтобы добавить файл, поместите его в папку attach, назовите латиницей без пробелов и добавьте ссылку в текст страницы.
Инструкция по добавлению файлов: Форматирование текста.
Итог#
Каждый скрипт должен находиться в подходящем разделе, быть оформлен по единому формату, содержать код в тексте страницы и быть понятен без дополнительного контекста.