Как добавить кастомный блок главной страницы

Образец (/local/ithive.homepage/blocks/right_block/acme_links.php) - только содержимое карточки:

<?php
        if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) {
            die();
        }
        ?>
        <ul>
            <li><a href="/company/">О компании</a></li>
            <li><a href="/docs/">Документы</a></li>
            <li><a href="/company/structure.php">Структура компании</a></li>
        </ul>
        

Правила сайдбара:

• Сайдбар выводится, только если в настройках главной включена правая колонка (right_block.active = Y), а страница выводится шаблоном bitrix24 (иначе Renderer ничего не выводит).
• Renderer сам кладёт вывод блока в view target sidebar: $APPLICATION->AddViewContent('sidebar', $html, $sort). Блок не должен сам вызывать AddViewContent и выводить обёртку карточки - достаточно вывести содержимое.
• Вывод оборачивается в разметку, идентичную ithive:widget.wrapper:

<div class="widget-mainpage" id="homepage-block-<code>-<N>">
          <div class="widget-mainpage-top"><div class="widget-mainpage-top-title">Название блока</div></div>
          <div class="widget-mainpage-content"><div class="widget-mainpage-content-container">
             ...вывод блока...
          </div></div>
        </div>
        

• Заголовок карточки добавляет модуль: сохранённое администратором название (title), иначе код блока. Свой заголовок в файле блока сайдбара не выводите, иначе он задвоится. Чтобы карточка называлась по-человечески, после выгрузки задайте title (раздел 5).
• Оформление: рамку, отступы и заголовок карточки дают классы widget-mainpage* (стили sidebar.css шаблона bitrix24, страница подключает его сама); содержимое оформляйте своей разметкой (списки, ссылки, <p>), специальных классов контента модуль не предоставляет. Для вида, единого со встроенными виджетами, ориентируйтесь на стандартные файлы /mainpage/right_block/<code>.php и их шаблоны компонентов.
• Сайдбар выводится по возрастанию sort (при совпадении sort действует то же правило, что в центре); в нём же выводятся пользовательские HTML-виджеты.

5. Настройки блока после выгрузки5. Настройки блока после выгрузки

Блок, выгруженный в /local, сразу появляется на странице «Настроить Главную» (вкладки центра и сайдбара) и в homepage.blocks.list, но выключенным: на главной он не виден, пока его не включат. Включается и настраивается там же (галочка «Акт.») или методом homepage.blocks.update (нужны права администратора). Все значения хранятся в настройках сайта (componentsettings), а не в файлах; страница «Настроить Главную» не редактирует rights, mobile, но не теряет их при сохранении; menu и left_menu блока центра редактируются там же (раздел 5.2).

Пример (название, порядок, доступ только администраторам):

curl -X POST "https://{portal}/rest/{user_id}/{webhook_code}/homepage.blocks.update.json" \
          -H "Content-Type: application/json" \
          -d '{"code":"acme_links","zone":"right","fields":{"title":"Полезные ссылки","sort":300,"active":true,"rights":{"admin":true,"groups":[]}}}'
        

rights, mobile, menu, left_menu у встроенных блоков отклоняются (VALIDATION_ERROR); menu/left_menu у блока сайдбара - тоже. Любая ошибка валидации отменяет всё изменение целиком. Метод меняет один блок за вызов; остальные блоки и состояние зон не затрагиваются, недостающие в сохранённых настройках встроенные блоки и флаги зон перед записью берутся из значений по умолчанию.

5.1. Права5.1. Права

Поле rights:

Правила (Block::canView() по эффективным rights из настроек):

• Пустые права (admin = false, groups = []) - блок виден всем, кто видит главную.
• Иначе пользователь должен быть администратором (при admin = true) или состоять хотя бы в одной группе из groups.
• Проверка выполняется при выводе блока на странице, в пункте меню раздела /mainpage/ (пункт показывается, только если блок доступен пользователю; в левом меню портала блок с rights пункта не получает, раздел 5.2), в homepage.blocks.list (недоступные блоки не возвращаются), в homepage.blocks.get и homepage.blocks.data (ACCESS_DENIED), а также в homepage.widgets.list / homepage.widgets.get для локальных блоков (скрытый блок не возвращается, get отвечает NOT_FOUND).
• homepage.blocks.update (только администратор) возвращает блок даже если после сохранения rights вызывающий администратор сам потерял к нему доступ: ответ строится по сохранённым настройкам без проверки прав. Последующие get/list/data для него блок уже скрывают.
• Права скрывают сам блок, но не данные: код блока (шаблон, компонент) отвечает за проверку доступа к тому, что он показывает.
• Снять ограничение: "rights": [].

5.2. Пункт левого меню5.2. Пункт левого меню

Блок центра может добавить пункт в левое меню портала (и в меню раздела /mainpage/, /mainpage/.left.menu.php). Для этого задайте menu и включите left_menu:

{"menu": {"url": "/company/news/", "title": "Новости компании"}, "left_menu": true}
        

• url: относительный путь, начинающийся с / (но не //), либо https://.... Другие схемы (javascript:, http:, data:) отклоняются.
• title: по умолчанию равен названию блока.
• Ограничение по rights. Левое меню портала задаётся на уровне сайта и не умеет скрывать пункт от отдельных пользователей. Поэтому блок с ограничением rights (администраторы и/или группы) не добавляет пункт в левое меню портала вообще; в меню раздела /mainpage/ пункт показывается только пользователям с доступом к блоку (проверка та же, что при выводе блока). Нужен пункт в меню портала - не ограничивайте блок по rights или ограничьте содержимое самим блоком.
• Когда пункт появляется и исчезает. Модуль сам синхронизирует пункты блоков из /local с левым меню портала при сохранении настроек: в «Настроить Главную», в настройках модуля и при вызове homepage.blocks.update (любое поле) для блока центра. Пункт появляется, когда блок активен, включён left_menu, задана ссылка menu.url и нет rights. Пункт исчезает при снятии флага, выключении блока, удалении ссылки (menu), добавлении rights и удалении записи блока из настроек. Удалили файл блока из /local - пункт уйдёт при следующем сохранении настроек блоков или вызове homepage.menu.refresh. Пункты встроенных блоков и пункты, добавленные администратором портала вручную, синхронизация не меняет; повторное сохранение пункт не дублирует. Текст пункта - название блока (title, оно же lang), иначе menu.title; ссылка - menu.url. Изменения видны после перезагрузки страницы.
• Пункт появляется только у активных блоков центра и только если включён left_menu (его же отмечает администратор флагом «Вывести в левое меню» в «Настроить Главную»; флаг и поле ссылки рядом с ним есть у каждого блока центра из /local, ссылка вводится прямо там и хранится в тех же настройках, что и menu.url). Флаг хранится в componentsettings (left_menu), по умолчанию выключен. Если флаг отмечен, а ссылка пустая или недопустима (правила menu.url: путь на портале или https), «Настроить Главную» не сохраняет изменения и показывает ошибку. Если флаг снят, введённая допустимая ссылка сохраняется, пункт не показывается; очистка поля удаляет menu.
• Название пункта: сохранённое название блока, иначе menu.title.
• Удалить пункт: "menu": [] (флаг left_menu сбрасывается).

5.3. Мобильное приложение5.3. Мобильное приложение

Мобильное приложение (МП) получает список блоков через homepage.blocks.list, а данные блока - через homepage.blocks.data. Клиент МП находится вне этого репозитория; контракт задаёт поле mobile:

mobile.dataMethod для native-json - только имя REST-метода формата <scope>.<entity>.<action> (например acme.news.list). Сервер этот метод не вызывает и PHP-класс по строке не разрешает: имя возвращается приложению в поле dataMethod ответа homepage.blocks.data. Формат Class::method не поддерживается и отклоняется (VALIDATION_ERROR).

Данные блока на стороне сервера поставляет событие ithive.homepage:OnBlockMobileData с параметрами code, zone, userId, siteId. Подписчик отвечает EventResult с параметром data (массив); используется первый ответ с данными, он попадает в data ответа homepage.blocks.data. Если событие данных не дало, а задан dataMethod - возвращается имя метода (data = null); иначе NOT_SUPPORTED.

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
            'ithive.homepage',
            'OnBlockMobileData',
            static function (\Bitrix\Main\Event $event) {
                if ($event->getParameter('code') !== 'acme_memo') {
                    return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::UNDEFINED);
                }
        
                return new \Bitrix\Main\EventResult(
                    \Bitrix\Main\EventResult::SUCCESS,
                    ['data' => ['items' => [['title' => 'Пункт 1']], 'userId' => (int)$event->getParameter('userId')]]
                );
            }
        );
        

homepage.blocks.data требует, чтобы блок был активен и доступен пользователю по rights.

6. Что выгрузить и что делать дальше (порядок для пользователя)6. Что выгрузить и что делать дальше (порядок для пользователя)

1. Выгрузите файл блока на портал (FTP/SFTP/scp/файловый менеджер хостинга): /local/ithive.homepage/blocks/center_block/<code>.php (центр) и/или /local/ithive.homepage/blocks/right_block/<code>.php (сайдбар), а свои ассеты и подшаблоны - в любое место в /local, например /local/ithive.homepage/assets/<code>/. Каталоги /local/ithive.homepage/blocks/center_block/ и right_block/ создаёт установка и обновление модуля, если их нет; если при обновлении не хватило прав на запись, создайте их сами.
2. Сбросьте opcache (если включён и не проверяет время изменения файлов): иначе портал может отдавать старую версию файла.
3. Откройте страницу «Настроить Главную»: блок уже в списке, но не активен, sort = 500, название = код. На /mainpage/ он пока не выводится. Если над блоками показана красная ошибка - прочитайте причину (раздел 9).
4. Включите блок (галочка «Акт.» в «Настроить Главную» или homepage.blocks.update с {"active": true}), при необходимости отсортируйте и переименуйте (sort, title). Блок сайдбара виден на главной, если включена правая колонка.
5. При необходимости выставьте права, мобильный контракт и пункт левого меню через homepage.blocks.update (раздел 5).
6. Проверьте homepage.blocks.get (код и зона) и главную под обычным сотрудником.

Изменить блок позже - заменить файл в /local (и сбросить opcache). Удалить блок - удалить файл (запись в настройках остаётся и подхватится, если блок с тем же кодом выгрузят снова).

7. Примеры7. Примеры

Два готовых примера лежат в репозитории модуля: docs/examples/blocks/center_block/example_onboarding_memo.php (центр) и docs/examples/blocks/right_block/example_useful_links.php (сайдбар). Копируйте их в /local/ithive.homepage/blocks/center_block/ и /local/ithive.homepage/blocks/right_block/ соответственно.

8. Обновления модуля и файлы /mainpage/index.php и /mainpage/.left.menu.php8. Обновления модуля и файлы /mainpage/index.php и /mainpage/.left.menu.php

Файлы блоков в /local и их настройки обновление не затрагивает. Файлы вне /local, от которых зависит механизм, - /mainpage/index.php и /mainpage/.left.menu.php портала: они должны быть тонкими (вызывать код модуля).

Тонкий index.php:

<?php
        require($_SERVER["DOCUMENT_ROOT"] . "/bitrix/header.php");
        
        // The homepage logic lives in the module (Ithive\Homepage\Blocks\Renderer) and is updated together with it.
        if (CModule::IncludeModule('ithive.homepage') && class_exists(\Ithive\Homepage\Blocks\Renderer::class)) {
            if (!\Ithive\Homepage\Blocks\Renderer::renderPage(__DIR__, __FILE__)) {
                return;
            }
        }
        
        require($_SERVER["DOCUMENT_ROOT"] . "/bitrix/footer.php"); ?>
        

Автоматическая замена при обновлении. Обновление 12.4.0 (updater.php) для корня портала и каждого активного сайта проверяет /mainpage/index.php и /mainpage/.left.menu.php:

1. Если в файле уже есть вызов модуля (Renderer::renderPage( для index.php, LeftMenu::build( для .left.menu.php) - файл пропускается.
2. Иначе рядом создаётся резервная копия <файл>.bak-<ГГГГММДД> и файл заменяется тонким вариантом из модуля (/bitrix/modules/ithive.homepage/install/public/mainpage/). Заменяется любой файл, в том числе изменённый вручную.
3. Если резервную копию создать не удалось (нет прав на запись в каталог), файл не меняется.

Если клиент менял index.php или .left.menu.php вручную, свои правки после обновления нужно вернуть из резервной копии .bak-<дата> вручную: перенесите их в блоки по этому руководству (для меню - добавьте свои пункты после вызова LeftMenu::build). Отдельных настроек, вкладки в настройках модуля или предупреждений на странице для этого нет.

Левое меню. Тонкий /mainpage/.left.menu.php содержит один вызов:

<?php
        if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();
        $aMenuLinks = [];
        if (\CModule::IncludeModule("ithive.homepage")) {
            $aMenuLinks = \Ithive\Homepage\Blocks\LeftMenu::build(SITE_ID, SITE_DIR);
        }
        

Пункты меню раздела /mainpage/ (встроенных блоков и блоков клиента с menu, с учётом rights) строит класс модуля \Ithive\Homepage\Blocks\LeftMenu, поэтому правки логики меню приходят с обновлением модуля. Пункты в левом меню портала (меню интранета) этот файл не определяет: для блоков клиента их записывает модуль при сохранении настроек (раздел 5.2).

Если блок не появился после обновления. Проверьте, что /mainpage/index.php вызывает Renderer::renderPage( (например, обновление не смогло записать файл из-за прав). Если нет, замените содержимое файла вручную на тонкий вариант выше, образец - /bitrix/modules/ithive.homepage/install/public/mainpage/index.php; для меню - вызов $aMenuLinks = \Ithive\Homepage\Blocks\LeftMenu::build(SITE_ID, SITE_DIR); после подключения модуля. Встроенные блоки по-прежнему выводятся файлами /mainpage/center_block/<code>.php и /mainpage/right_block/<code>.php.

9. Безопасность и диагностика9. Безопасность и диагностика

• REST ничего не пишет и не исполняет. Блоки не создаются и не удаляются через REST, файлы не записываются. homepage.blocks.update меняет только опцию componentsettings; значения (title, sort, rights, mobile, menu) проверяются и не исполняются как код.
• Серверных вызовов по строке из данных нет. mobile.dataMethod - только имя REST-метода, его вызывает приложение, не сервер. Данные для МП поставляет событие ithive.homepage:OnBlockMobileData.
• Единственный динамический include локальных блоков - файл блока <code>.php, который разработчик положил в /local/ithive.homepage/blocks/center_block/ или right_block/ (файловый доступ к серверу = доверенный). Путь файла проверяется realpath строго внутри каталога зоны (при загрузке и при каждом выводе), файл-ссылка отвергается; каталог зоны не может быть символьной ссылкой за пределы /local/ithive.homepage/blocks/.
• В menu.url и mobile.url разрешены только относительные пути и https://.
• Данные пользователя выводите с экранированием (htmlspecialcharsbx()); не подключайте файлы по путям из запроса.
• Права блока (rights) ограничивают видимость блока, но не защищают данные, которые блок получает сам.
• Ошибки показываются на странице, серверный лог модуль не пишет. Блок, который не удалось загрузить (недопустимый код файла, в том числе с __ или с _ в начале/конце; конфликт с кодом встроенного блока любой зоны; нечитаемый файл, файл или каталог зоны - ссылка), пропускается, а над блоками центра показывается ShowError вида «Блок «» (зона: ..., источник: local) не загружен: <причина>» (одна ошибка на пару «зона + код» за запрос; видна всем пользователям). Ошибка при выводе блока (исключение в шаблоне, файл не найден) показывается на месте блока: «Ошибка вывода блока «» (зона: ): <причина>».

Блок «<название>» готов. Файлы:
        - center_block/<code>.php (или right_block/<code>.php)
        - <ассеты, если есть: /local/ithive.homepage/assets/<code>/...>
        
        Куда выгрузить: /local/ithive.homepage/blocks/center_block/<code>.php (или .../right_block/<code>.php)
        Дальше:
        1. Выгрузите файлы на портал (при необходимости сбросьте opcache).
        2. Блок появится в «Настроить Главную» и в homepage.blocks.list выключенным - включите его (галочка «Акт.» или `homepage.blocks.update` с `{"active": true}`) и задайте порядок.
        3. Название/права/меню - homepage.blocks.update (готовый вызов ниже).