Как подготовить пользовательский шаблон

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Пользовательский шаблон — это готовая заготовка сайта или страницы, которую можно добавить в мастер создания сайтов. Мастер — это экран, на котором пользователь Битрикс24 выбирает оформление при создании нового сайта или страницы. Свой шаблон появляется в этом списке после того, как приложение его зарегистрирует.

Шаблон создают на основе уже готового сайта или страницы из раздела Сайты. Сначала сайт экспортируют — выгружают его структуру в набор данных, который можно сохранить и передать дальше. Затем этот набор регистрируют методами landing.demos.* из приложения Битрикс24.

Scope: landing

Кто может вызывать методы раздела: пользователь с правом Просмотр в разделе Сайты

Когда использовать пользовательский шаблон

Используйте пользовательский шаблон, если нужно:

  • добавить собственный шаблон в мастер создания сайтов
  • распространять готовый сайт или страницу через приложение
  • повторно использовать один и тот же набор страниц, блоков и настроек

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

Если шаблон распространяется как приложение с сайтом, смотрите статьи Установка шаблонов сайтов и Требования к сайтам перед публикацией.

Как устроен пользовательский шаблон

Шаблон собирается из трех частей, связанных между собой:

  • исходный сайт или страница — основа шаблона, ее готовят в разделе Сайты
  • экспорт — структура сайта в виде данных, которую создает метод landing.site.fullExport
  • зарегистрированный шаблон — запись, которая появляется в мастере после вызова landing.demos.register

Методы раздела отвечают за отдельные шаги работы с шаблоном:

  • landing.demos.register — регистрирует шаблон в мастере создания сайта и страницы
  • landing.demos.getList — возвращает зарегистрированные шаблоны и позволяет проверить результат регистрации. Если метод вызван из приложения, в ответ попадают только шаблоны этого приложения
  • landing.demos.getSiteList — возвращает шаблоны сайтов, которые доступны в мастере для выбранного типа сайта. В список попадают и встроенные шаблоны Битрикс24, и подходящие шаблоны, которые вы зарегистрировали. Например, для типа store метод вернет шаблоны интернет-магазинов
  • landing.demos.getPageList — то же самое, но для шаблонов отдельных страниц
  • landing.demos.unregister — удаляет зарегистрированный шаблон

Как подготовить шаблон

Перед экспортом проверьте сам сайт:

  • страницы связаны между собой корректно
  • используются нужные блоки и темы
  • изображения и внешние ресурсы доступны по рабочим URL
  • название, описание и preview-данные подготовлены для шаблона. Preview-данные — это картинки предпросмотра, по которым шаблон узнают в списке мастера

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

Как зарегистрировать шаблон

Порядок работы такой:

  1. Создайте сайт или страницу, которые станут основой шаблона
  2. Экспортируйте сайт методом landing.site.fullExport — он вернет структуру сайта в виде данных
  3. Сохраните результат экспорта на стороне приложения
  4. При установке приложения передайте сохраненные данные в landing.demos.register. Обычно результат fullExport передают без ручной перестройки структуры
  5. Проверьте результат методом landing.demos.getList: шаблон должен появиться в списке и в мастере создания сайта или страницы

Что возвращают методы:

  • landing.demos.register — массив числовых идентификаторов шаблонов, которые он создал или обновил
  • landing.demos.getList — список шаблонов. У каждого есть внешний код XML_ID, название TITLE, тип TYPE и другие поля. Выборку можно сузить параметрами select, filter, order, limit и offset

Что учитывать перед регистрацией

Тип шаблона. В данных шаблона есть поля type и tpl_type. Поле type задает назначение шаблона: page — страницы, store — магазины, knowledge — базы знаний, group — группы, mainpage — главные страницы. Поле tpl_type задает место шаблона в мастере: S — шаблон сайта, P — шаблон страницы. Проверьте оба поля в структуре, которую передаете в landing.demos.register.

Состав экспорта. Обычно в регистрацию передают полный результат landing.site.fullExport. Если структуру меняют вручную, проверьте, что в ней сохранены обязательные поля и карта страниц items. Если не заполнить обязательное поле code с внешним кодом шаблона, метод вернет ошибку BX_EMPTY_REQUIRED.

Проверка безопасности. Перед регистрацией Битрикс24 проверяет содержимое шаблона. Если в нем найден небезопасный код, метод вернет ошибку CONTENT_IS_BAD, и шаблон не зарегистрируется.

Preview-данные. Подготовьте preview, preview2x, preview3x и preview_url, если шаблон должен отображаться в списке и в предпросмотре.

Внешний код шаблона. Чтобы удалить шаблон, нужен его внешний код. Получите его так:

  • при регистрации внешний код задают в поле code метода landing.demos.register — он сохраняется как XML_ID шаблона
  • если код не сохранили, его можно получить методом landing.demos.getList в поле XML_ID
  • передайте этот код в параметр code метода landing.demos.unregister

Если шаблона с таким кодом нет, unregister вернет false. Если шаблон сайта и шаблон страницы зарегистрированы с одним и тем же кодом, удаление может затронуть обе связанные записи.

URL предпросмотра

preview_url задает страницу предпросмотра шаблона в мастере. Этот URL можно передать при экспорте сайта через landing.site.fullExport. Затем его используют при регистрации шаблона.

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

Следите, чтобы ссылка предпросмотра оставалась доступной. Иначе в мастере не откроется страница предпросмотра.

Изображения и внешние ресурсы

При экспорте сайта изображения и другие внешние ресурсы могут сохраниться как абсолютные ссылки. После установки шаблона они будут загружаться с исходного адреса. Это будет продолжаться, пока пользователь не заменит их своими файлами.

Если шаблон распространяется в другие Битрикс24, заранее проверьте:

  • что все URL доступны извне
  • что изображения не зависят от временного хранилища
  • что preview-картинки не будут удалены

Локализация шаблона

Название и описание шаблона можно локализовать при регистрации. Для этого в landing.demos.register используют параметры lang и lang_original.

Если шаблон должен отображаться в Битрикс24 с разными языками, подготовьте локализационный массив заранее. Подробности смотрите в статье Локализация шаблона.

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

Предыдущая
Обзор методов
Следующая
Локализация