Файл манифеста

Манифест — это описание блока в виде массива. Разметка блока задает, как он выглядит, а манифест — что в нем можно менять:

• редактируемые элементы в разметке блока
• стили, доступные в редакторе
• дополнительные атрибуты
• подключаемые ресурсы

У штатных блоков Битрикс24 манифест лежит в файле .description.php рядом с блоком. Приложение передает манифест своего блока при регистрации — в параметре manifest метода landing.repo.register.

Примеры на этой странице записаны PHP-массивом, как в .description.php. В REST-вызов тот же набор ключей передают объектом JSON: параметр manifest объявлен типом object.

Манифест нужен в двух задачах: когда вы собираете собственный блок и когда меняете чужой блок через REST. Во втором случае манифест показывает, какие селекторы принимают методы изменения: ноды из nodes, карточки из cards, атрибуты из attrs, стили из style.

Как получить манифестКак получить манифест

• landing.block.getmanifestfile — исходный манифест шаблона по коду блока, например 01.big_with_text
• landing.block.getmanifest — манифест блока, уже размещенного на странице, со служебными полями и подставленными переводами

Манифест разбирают на штатном блоке: получите список шаблонов методом landing.block.getrepository, а затем запросите манифест нужного блока по его коду. Параметры вызова landing.block.getmanifestfile:

{
    "code": "01.big_with_text"
}

Манифест писать нужно не всегда. Если вы берете готовый блок Битрикс24 и меняете только значения его нод и атрибутов, сразу переходите к методам раздела Работа с блоками.

Пример файла манифестаПример файла манифеста

$manifest = [
    'block' => [
        'name' => 'Текст и изображение в две колонки',
        'section' => ['text_image', 'columns'],
        'type' => ['page', 'store', 'knowledge', 'group'],
        'dynamic' => false,
        'description' => 'Блок с заголовком, текстом, кнопкой и изображением',
    ],
    'cards' => [
        '.landing-block-card' => [
            'name' => 'Колонка',
            'label' => ['.landing-block-node-title'],
        ],
    ],
    'nodes' => [
        '.landing-block-node-title' => [
            'name' => 'Заголовок',
            'type' => 'text',
        ],
        '.landing-block-node-text' => [
            'name' => 'Текст',
            'type' => 'text',
        ],
        '.landing-block-node-button' => [
            'name' => 'Кнопка',
            'type' => 'link',
        ],
        '.landing-block-node-image' => [
            'name' => 'Изображение',
            'type' => 'img',
            'dimensions' => [
                'maxWidth' => 1200,
                'maxHeight' => 1200,
            ],
            'allowInlineEdit' => false,
            'useInDesigner' => true,
        ],
    ],
    'style' => [
        'block' => [
            'type' => ['block-default'],
        ],
        'nodes' => [
            '.landing-block-card' => [
                'name' => 'Колонка',
                'type' => ['columns', 'animation'],
            ],
            '.landing-block-node-title' => [
                'name' => 'Заголовок',
                'type' => ['typo', 'heading'],
            ],
            '.landing-block-node-text' => [
                'name' => 'Текст',
                'type' => 'typo',
            ],
            '.landing-block-node-button' => [
                'name' => 'Кнопка',
                'type' => 'button',
            ],
            '.landing-block-node-image' => [
                'name' => 'Изображение',
                'type' => ['box'],
            ],
        ],
    ],
    'attrs' => [
        '.landing-block-node-text' => [
            [
                'name' => 'Режим отображения',
                'type' => 'dropdown',
                'attribute' => 'data-view',
                'items' => [
                    ['name' => 'Короткий', 'value' => 'short'],
                    ['name' => 'Полный', 'value' => 'full'],
                ],
            ],
        ],
    ],
    'assets' => [
        'css' => ['https://example.com/landing/custom-block.css'],
        'js' => ['https://example.com/landing/custom-block.js'],
        'ext' => ['landing_form'],
    ],
];

Ключи манифестаКлючи манифеста

Манифест блока состоит из набора ключей. Каждый ключ отвечает за отдельную часть описания блока. В одном манифесте используют сразу несколько ключей.

Сам манифест — необязательный параметр метода landing.repo.register: без него блок зарегистрируется, но редактировать в нем будет нечего. Минимальный рабочий набор для своего блока — nodes с редактируемыми элементами. Остальные ключи добавляют по мере надобности.

Ключ blockКлюч block

Ключ block задает базовые свойства блока. У блока, который приложение регистрирует методом landing.repo.register, название, описание и разделы каталога берутся из полей fields.NAME, fields.DESCRIPTION и fields.SECTIONS, а не отсюда: из ключа block для такого блока читаются только type, subtype и subtype_params.

Поля ключа:

• name — название блока
• section — раздел или массив разделов в каталоге блоков. Актуальные коды разделов можно получить методом landing.block.getrepository
• dynamic — признак поддержки динамического режима у штатного блока. По умолчанию ключ не задают, и блок можно использовать как динамический. Запрещает режим только явное значение false
• subtype — подтип спецблока, одно значение или массив. Если значений несколько, обработчики применяются по очереди и каждый дополняет манифест. Какие подтипы бывают: Специальные блоки
• subtype_params — параметры подтипа. У каждого сценария свои: они перечислены на странице сценария в разделе Специальные блоки
• type — тип сайта, где доступен блок. Поддерживаемые типы сайта:
  • page — обычные сайты и лендинги
  • store — магазины
  • smn — служебный тип сайтов для раздела «Сайты24» в БУС
  • knowledge — базы знаний
  • group — базы знаний групп соцсети
  • vibe — главная страница Битрикс24

Значение page автоматически добавляет к блоку и тип smn. Если ключ type не задавать, блок считается общим и будет доступен во всех типах сайтов. Чтобы убрать блок из каталога, передайте в type строку null или пустую строку — такой блок скрыт.

Ключ nodesКлюч nodes

Ключ nodes описывает элементы, которые можно редактировать как контент. Для указания нод используются CSS-селекторы. В качестве селектора рекомендуется выбирать понятные структурные классы, например с префиксом landing-block-node-.

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

В nodes ключами выступают селекторы редактируемых элементов, а в значениях задаются метка ноды, ее тип и дополнительные параметры. От типа ноды зависит, как именно элемент будет редактироваться в интерфейсе и в каком формате хранится его значение.

Основных типов нод восемь: от текста и изображения до карты и встроенного компонента. Перечень типов, их поля и примеры разметки: Типы нод.

Ключ cardsКлюч cards

Ключ cards описывает карточки. Карточки применяются для повторяемого контента, например списка услуг, сотрудников или элементов галереи.

В cards ключами выступают селекторы повторяемых элементов. Базовые поля описания:

• name — название карточки в форме настроек
• label — селектор ноды или массив селекторов, по которым собирается заголовок карточки в списке

Остальные поля — пресеты, группировка и запреты на действия — относятся к расширенной схеме и разобраны в статье Расширенное описание карточек.

Рекомендации:

• используйте отдельные селекторы карточек и нод
• используйте понятные структурные классы, например landing-block-card-*
• не смешивайте карточки разных селекторов в одном общем родителе без расширенной схемы карточек

Если карточки — это пункты меню и нужны отдельные настройки для корневых и дочерних уровней, вместо cards используют ключ menu.

Ключ styleКлюч style

Ключ style задает, какие стилевые настройки доступны в редакторе. Подпись стилевой группы в интерфейсе берется из ключа name: только значения name попадают в перевод манифеста.

При изменении внешнего вида блоков обычно меняются CSS-классы, а не инлайн-атрибут style у нод. Например, при изменении размера текста система может заменить условный класс g-font-size-12 на g-font-size-16, а не записывать font-size напрямую в style.

Структура:

• style.block — стили блока целиком
• style.nodes — стили отдельных элементов внутри блока по CSS-селекторам

Ниже перечислены группы стилей и параметры, которые каждая из них открывает в редакторе. В type можно передать и отдельный код параметра, например columns, animation, display, background или border-radius.

Набор групп и параметры внутри каждой группы расширяемые: они зависят от подключенных style-манифестов и версии продукта.

Отдельного ключа animation в манифесте нет — анимация подключается как параметр стиля. Чтобы она работала в штатном режиме:

• у ноды должен быть класс js-animation
• в style для этой ноды должен быть указан тип animation
• при необходимости можно сразу добавить класс эффекта, например fadeIn

Ключ attrsКлюч attrs

Ключ attrs описывает дополнительные настройки блока, значения которых сохраняются в DOM-атрибутах элементов, например data-view="short".

У каждой настройки задают имя DOM-атрибута в поле attribute и тип поля в редакторе в поле type — от текстового поля и выпадающего списка до палитры, выбора изображения и динамического источника данных. Ключ attrs описывают в четырех местах манифеста: в корне, внутри style.nodes, внутри style.block и внутри cards. От места зависит, в какой форме редактора появится поле.

Полный перечень типов, их поля и места описания: Атрибуты.

Ключ menuКлюч menu

Ключ menu используется, когда нужно многоуровневое меню с отдельными настройками корневых и дочерних пунктов. Развилку с ключом cards смотрите в разделе Ключ cards.

Пример многоуровневого меню:

'menu' => [
    '.landing-block-node-menu' => [
        'item' => '.landing-block-node-menu-item',
        'name' => 'Меню',
        'root' => [
            'ulClassName' => 'landing-block-node-menu navbar-nav',
            'liClassName' => 'landing-block-node-menu-item nav-item',
            'aClassName' => 'landing-block-node-menu-link nav-link',
        ],
        'children' => [
            'ulClassName' => 'landing-block-node-menu navbar-nav',
            'liClassName' => 'landing-block-node-menu-item nav-item',
            'aClassName' => 'landing-block-node-menu-link nav-link',
        ],
        'nodes' => [
            '.landing-block-node-menu-link' => [
                'name' => 'Ссылка',
                'type' => 'link',
            ],
        ],
    ],
]

Основные поля:

• ключ массива .landing-block-node-menu — селектор корневого <ul>
• item — селектор элементов <li>
• name — название меню в интерфейсе
• root — классы для корневого уровня меню:
  • ulClassName для контейнера <ul>
  • liClassName для пунктов <li>
  • aClassName для ссылок <a>
• children — классы для дочерних уровней меню:
  • ulClassName для вложенного <ul>
  • liClassName для вложенных <li>
  • aClassName для ссылок <a> в дочерних пунктах
• nodes — редактируемые элементы внутри пункта меню, например ссылка

В одном манифесте можно описать несколько многоуровневых меню, то есть несколько корневых селекторов в menu.

Ключ assetsКлюч assets

Ключ assets задает JS- и CSS-ресурсы, которые подключаются при добавлении блока на страницу.

• css — внешние CSS-файлы
• js — внешние JS-файлы
• ext — расширения ядра Битрикс24

Если один и тот же файл уже подключен другим блоком, повторно он не добавляется. Зависимости расширений перечислять не нужно: Битрикс24 подключает их сам.

Расширения, которые используют блоки:

Есть еще расширение landing.widgetvue — оно обслуживает Vue-виджеты на главной странице Битрикс24. В assets.ext его не указывают: обработчик подтипа widgetvue сам собирает блоку и assets, и nodes, и style.

Если скрипт использует библиотеки, которые загружаются ядром, инициализацию лучше оборачивать в BX.ready(...), чтобы код выполнялся после системных подключений:

BX.ready(function () {
    // здесь расширения из assets.ext уже подключены
});

Ключи lang_original и langКлючи lang_original и lang

Ключи lang_original и lang задают локализацию подписей в манифесте блока.

• lang_original — исходный язык фраз в манифесте
• lang — набор переводов по языкам

Рекомендации:

• задавайте lang_original в соответствии с фактическим языком манифеста
• используйте одинаковые фразы-ключи в lang, как в исходном манифесте

Переводятся только значения ключей name. Перечень таких подписей: Какие подписи участвуют в переводе.

Подробнее: Локализация блока.

Права и ограниченияПрава и ограничения

Scope: landing

Кто может выполнять метод: в зависимости от метода

Ограничения:

• манифест штатного блока Битрикс24 через REST изменить нельзя. Методы landing.block.* меняют размещенный блок, а не описание его шаблона
• разметку своего блока передают отдельно от манифеста — в поле fields.CONTENT метода landing.repo.register. Селекторы из nodes, cards и attrs должны существовать в этой разметке, иначе настройке не к чему привязаться
• в assets.ext подключают только те расширения ядра, которые доступны в окружении блока

Продолжите изучениеПродолжите изучение

• Типы нод
• Атрибуты
• Расширенное описание карточек
• Локализация блока
• Специальные блоки: обзор сценариев
• Интерактивные блоки: обзор сценариев
• Получить файл манифеста блока landing.block.getmanifestfile
• Добавить пользовательский блок в репозиторий landing.repo.register