ИНСТРУКЦИЯ ПО РАБОТЕ С СИСТЕМОЙ "LEGEND" (СПРАВКА)

Эта инструкция описывает, как добавлять новые блоки справки (легенды) в систему ACP и выводить их в шаблонах. Система позволяет централизованно управлять описаниями полей и переводами.

Пошаговое руководство

1. ГДЕ ХРАНЯТСЯ ЛЕГЕНДЫ

Все структуры легенд находятся в файле:
`lib/ACP/Legend.pm`

2. КАК ДОБАВИТЬ НОВУЮ ЛЕГЕНДУ

1. Откройте файл `lib/ACP/Legend.pm`.

2. Найдите переменную `%LEGEND`. Это список всех доступных справок.

3. Добавьте новую запись по аналогии с существующими.

Структура записи:

    'имя_легенды' => {                 # Уникальное имя (на латинице), по которому будем вызывать в шаблоне
        title => 'ЗАГОЛОВОК',          # Языковая константа для заголовка (например, HELP)
        items => [                     # Список полей (строк) в справке
            { 
                term => 'НАЗВАНИЕ_ПОЛЯ',      # Языковая константа для названия поля (слева)
                desc => 'ОПИСАНИЕ_ПОЛЯ'       # Языковая константа для описания (справа)
            },
            {
                term => 'ID',                 # Если название - НЕ константа, а просто текст (например, ID или IP)
                desc => 'DESC_ID',
                is_lang_term => 0             # Укажите 0, чтобы система не искала перевод для 'term'
            },
            # ... добавьте столько пунктов, сколько нужно
        ]
    },

3. КАК ДОБАВИТЬ ПЕРЕВОДЫ (ТЕКСТЫ)

Чтобы тексты отображались на русском (или другом языке), их нужно добавить в языковой файл модуля или общий языковой файл.

Пример для модуля Paysys:
Файл: `ACP/modules/Paysys/lng_russian.pl`

Добавьте в конец файла строки:

    $lang{MY_LEGEND_TITLE} = 'Справка по настройке';
    $lang{MY_FIELD_NAME}   = 'Имя пользователя';
    $lang{MY_FIELD_DESC}   = 'Введите уникальное имя пользователя для входа в систему.';
Совет: Используйте префиксы, чтобы не путаться (например, PAYSYS_LEGEND_...)


4. КАК ВЫВЕСТИ ЛЕГЕНДУ В ШАБЛОНЕ

В любом файле шаблона (`.tpl`) просто вставьте специальный тег в то место, где должна появиться карточка справки:

    %LEGEND:имя_легенды%

Где `имя_легенды` — это то имя, которое вы задали в пункте 2 (ключ хеша).

5. ДОПОЛНИТЕЛЬНЫЕ ВОЗМОЖНОСТИ (ЦВЕТА И ВАЖНОСТЬ)

Вы можете украсить легенду, добавив цвета (badges) и пометки обязательных полей.

Параметры:
- `color`: делает название поля цветной плашкой.
  Доступные цвета:
  - 'success' (зеленый)
  - 'danger'  (красный)
  - 'warning' (желтый)
  - 'info'    (голубой)
  - 'primary' (синий)
  - 'secondary' (серый)

- `required`: добавляет красную звездочку (*) после названия поля.

Пример использования в `lib/ACP/Legend.pm`:

    items => [
        { 
            term => 'GREEN_COLOR', 
            desc => 'DESC_GREEN', 
            color => 'success'       # Будет зеленая плашка
        },
        { 
            term => 'RED_COLOR', 
            desc => 'DESC_RED', 
            color => 'danger'        # Будет красная плашка
        },
        { 
            term => 'IMPORTANT_FIELD', 
            desc => 'DESC_IMPORTANT', 
            required => 1            # Добавит звездочку (*)
        },
    ]

6. ПРОИЗВОЛЬНЫЙ ТЕКСТ (ОПИСАНИЕ)

Вы можете добавить блок с произвольным текстом (комментарием) в самом начале справки, перед списком полей. Это удобно для общих инструкций.

Вариант А: Один простой комментарий
Параметр: `comment` (строка)

    'my_legend' => {
        title   => 'HELP',
        comment => 'LEGEND_MY_COMMENT',  # Языковая константа
        items   => [...]
    }

Вариант Б: Несколько комментариев (можно с разными стилями)
Параметр: `comments` (массив)

    'my_legend' => {
        title => 'HELP',
        comments => [
            'LEGEND_FIRST_TEXT',   # Просто текст (будет синим)
            { 
                text => 'LEGEND_WARNING_TEXT', 
                type => 'warning'  # Желтый блок
            },
            { 
                text => 'LEGEND_DANGER_TEXT', 
                type => 'danger'   # Красный блок
            }
        ],
        items => [...]
    }

Доступные типы (`type`) для блоков текста:
- `info` (синий, по умолчанию)
- `warning` (желтый)
- `danger` (красный)
- `success` (зеленый)

В таком виде можно добавить URL для вывода


        url => [
            { link => 'https://stat.ktk-39.ru', text => 'LINK_TO_WIKI' }
        ],


Эти тексты будут выведены в блоках (callout) внутри карточки друг за другом.

ПРИМЕР "ДЛЯ ЧАЙНИКОВ" (ОТ НАЧАЛА ДО КОНЦА)

Задача: Сделать справку для формы "Тестовая форма".

ШАГ 1. Редактируем lib/ACP/Legend.pm
Добавляем внутрь %LEGEND:

    'test_form_help' => {
        title => 'HELP',
        items => [
            { term => 'LOGIN',    desc => 'TEST_LEGEND_LOGIN', required => 1 },
            { term => 'PASSWORD', desc => 'TEST_LEGEND_PASS', required => 1 },
            { term => 'STATUS_OK', desc => 'TEST_LEGEND_OK', color => 'success' },
            { term => 'STATUS_ERR', desc => 'TEST_LEGEND_ERR', color => 'danger' },
        ]
    }

ШАГ 2. Редактируем языковой файл (например, lng_russian.pl)
Добавляем переводы:

    $lang{TEST_LEGEND_LOGIN} = 'Ваш логин для входа. Не используйте пробелы.';
    $lang{TEST_LEGEND_PASS}  = 'Пароль должен быть сложным (минимум 8 символов).';
    $lang{STATUS_OK}         = 'Зеленый статус';
    $lang{TEST_LEGEND_OK}    = 'Все работает хорошо.';
    $lang{STATUS_ERR}        = 'Красный статус';
    $lang{TEST_LEGEND_ERR}   = 'Произошла ошибка.';

ШАГ 3. Вставляем в шаблон (например, test.tpl)
В нужном месте пишем:


    <form>
       ... поля формы ...
    </form>
    %LEGEND:test_form_help%


РЕЗУЛЬТАТ:

В шаблоне появится сворачиваемая синяя карточка "Справка".
Внутри будет список:
- Логин *: Ваш логин для входа...
- Пароль *: Пароль должен быть сложным...
- [Зеленый статус] : Все работает хорошо.
- [Красный статус] : Произошла ошибка.













АСР Казна-39