Расширенное описание карточек

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

Расширенное описание карточек используют, когда в одном наборе карточек требуются:

• разные наборы полей у карточек одного списка, например только телефон или телефон, e-mail и ссылка
• разные варианты верстки для одинаковых объектов
• карточки из заранее заданных пресетов

Если все карточки списка одинаковые, расширенное описание не нужно — достаточно базового описания ключа cards.

Настройку задает автор блока: манифест и разметку передают при регистрации блока методом landing.repo.register. Посмотреть, как ключ cards заполнен в штатном блоке, можно методом landing.block.getmanifestfile.

Базовые принципы карточек и нод описаны в статьях Файл манифеста и Типы нод.

Пример расширенного описания карточкиПример расширенного описания карточки

'cards' => [
    '.landing-block-card' => [
        'name' => 'Контакты',
        'label' => [
            '.landing-block-node-element-icon',
            '.landing-block-node-element-title',
        ],
        'presets' => [
            'telegram' => [
                'name' => 'Telegram',
                'html' => '<html-код-пресета>',
                'values' => [
                    '.landing-block-node-element-title' => 'Telegram',
                    '.landing-block-node-element-text' => 'Any text ...',
                    '.landing-block-node-element-icon' => [
                        'type' => 'icon',
                        'classList' => [
                            'landing-block-node-element-icon',
                            'fa',
                            'fa-telegram',
                        ],
                    ],
                ],
                'disallow' => [
                    '.landing-block-node-element-icon',
                ],
            ],
        ],
    ],
],

Поля расширенного описания карточекПоля расширенного описания карточек

Поля пресетаПоля пресета

Разметка пресетаРазметка пресета

Для связи карточки с пресетом в разметке укажите атрибут data-card-preset с кодом пресета. Значение data-card-preset должно совпадать с ключом пресета в presets.

В разных пресетах внутренняя структура карточки может отличаться. Например, в одном варианте внутри <li> используется ссылка, а в другом вместо ссылки может быть изображение. При этом внешний контейнер карточки рекомендуется сохранять единообразным.

Пример:

<li class="landing-block-node-list-item col g-min-width-65 list-inline-item g-mr-0"
    data-card-preset="telegram">
    <a class="landing-block-node-list-item-link d-block g-py-15 g-px-30 g-bg-telegram--hover g-bg-telegram g-color-white text-center" href="#">
        <i class="landing-block-node-list-item-icon fa fa-telegram"></i>
    </a>
</li>

Как добавить карточку из пресета через RESTКак добавить карточку из пресета через REST

Пресеты применяет метод landing.block.updateCards. В массиве source передайте элемент с типом preset и кодом пресета из манифеста:

"source": [
    {
        "type": "card",
        "value": 0
    },
    {
        "type": "preset",
        "value": "telegram"
    }
]

Массив source задает итоговый состав и порядок карточек блока, поэтому перечисляйте в нем и те карточки, которые нужно сохранить. Если в source указан несуществующий пресет, на его месте окажется пустая карточка.

Через REST из пресета берется только разметка html. Начальные значения из ключа values манифеста подставляются, когда карточку добавляют в редакторе Битрикс24. Через REST их задают вручную: в том же вызове landing.block.updateCards есть собственный ключ values, либо значения записывают потом методом landing.block.updatenodes.

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

Остальные методы карточек пресеты не используют: landing.block.addcard добавляет карточку с переданным HTML, а landing.block.clonecard копирует существующую карточку по селектору.

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

Scope: landing

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

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

• пресеты работают только внутри того селектора карточки, в описании которого они заданы
• метод landing.block.updateCards переписывает содержимое родителя карточек целиком: посторонняя разметка внутри этого контейнера пропадет
• пустой source не удаляет карточки: landing.block.updateCards вернет true и ничего не изменит
• landing.block.updateCards не сверяет переданный селектор с манифестом: он работает с разметкой блока. Манифест нужен только для type: preset — пресет ищется в cards.<селектор>.presets. Селектор, которого нет в cards, метод не отбросит и перезапишет содержимое найденного по нему контейнера
• разметка пресета проходит проверку санитайзером при регистрации блока. Если в manifest.cards[*].presets[*] есть небезопасное содержимое, метод landing.repo.register вернет ошибку PRESET_CONTENT_IS_BAD

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

• Файл манифеста
• Типы нод
• Атрибуты
• Локализация блока
• Обновить карточки блока landing.block.updateCards
• Добавить пользовательский блок в репозиторий landing.repo.register