Новый формат расширения функционала

С версии 2.8.5 в системе появился новый способ организации php-скриптов, расширяющих функционал системы. Теперь для каждого шаблона на сайте можно писать свои кастомные макросы, расширяющие функционал стандартных модулей. При этом не нужно писать все макросы в один файл __custom.php - можно распределять их по отдельным скриптам, подключая в один главный, так же как это сделано в стандартных модулях. Потом эти скрипты можно легко переносить в другие шаблоны, подключать, поддерживать и вносить необходимые правки.

Структура файлов

Новый формат расположения папок и файлов, относящихся к шаблонам и расширению функциональности сайта, предполагает наличие в корне сайта папки ~/templates/, в которой, в свою очередь, находятся директории шаблонов (их количество не ограничено) ~/templates/{имя_шаблона}/. В каждой из них может находиться собственная папка /classes/modules/, содержащая папки с именами модулей (/content/, /catalog/ и т.д.), в которые необходимо поместить файл class.php, который будет подключаться автоматически.

Пример скрипта

Рассмотрим новый формат расширения функциональности на примере модуля Структура:
Для начала, создадим файл class.php в папке модуля content того шаблона, который используется на нашем сайте - ~/templates/newTemplate/classes/modules/content/class.php. В этом файле нам нужно указать, что наш класс будет расширять стандартный класс "def_module". Имя создаваемого класса произвольно, однако мы рекомендуем использовать конструкции, подобные приведенному в примере имени класса, во избежание совпадения имени ваших классов с существующими в системе.

Важно:

Нельзя использовать в качестве имен классов и методов названия системных классов и методов!

Добавим новый макрос:

<?php
    class content_custom extends def_module {

        public function testMenu() {
            $temp = array(
                'foo' => 'foo',
                'bar' => 'bar'
            );

            return def_module::parseTemplate('', $temp);
        }

    };
?>

Обратите внимание, что файлы ~/classes/modules/custom.php и ~/classes/modules/{имя_модуля}/__custom.php продолжают подключаться как и прежде.

Права доступа

Теперь мы можем использовать макрос content::testMenu в нашем шаблоне. Пока что он доступен только супервайзеру. Для того чтобы открыть макрос всем пользователям - создаём стандартную запись в файле permissions.php (рекомендуем ознакомиться с Cистемой прав доступа UMI.CMS), в той же директории что и class.php:

<?php
    $permissions['content'][] = 'testMenu';
?>

Обратите внимание на порядок подключения файлов с правами: Первым делом система производит поиск в файле ~/classes/modules/{имя_модуля}/permissions.custom.php, затем в файле ~/classes/modules/{имя_модуля}/permissions.php, и только потом в ~/templates/{имя_шаблона}/classes/modules/{имя_модуля}/permissions.php.

События

Работа с "Событиями" теперь также доступна в файле ~/templates/{имя_шаблона}/classes/modules/{имя_модуля}/events.php. Обратите внимание на порядок подключения файлов с перехватчиками событий: Первым делом система производит поиск в файле ~/templates/{имя_шаблона}/classes/modules/{имя_модуля}/events.php, затем в файле ~/classes/modules/{имя_модуля}/custom_events.php, и затем в ~/classes/modules/{имя_модуля}/events.php.
Такая последовательность подключения файлов даёт разработчику возможность прервать цепочку событий (для этого используется специальное системное исключение (throw new breakException();), что позволяет "перебить" системные события пользовательскими.

Распределение кода

Теперь, для удобной работы с кодом, мы рекомендуем распределить его по нескольким php-файлам. Допустим, мы создали файл temp.php в той же директории, что и class.php. Внесли в него некий код (ещё один макрос):

<?php
    class content_custom_temp {

        public function testMenu2() {
            $temp = array(
                'foo' => 'foo',
                'bar' => 'bar',
                'baz' => 'baz'
            );
            
            return def_module::parseTemplate('', $temp);
        }

    };
?>

Затем мы подключаем новый класс content_custom_temp в файле class.php - создаём функцию __construct, в которой принимаем экземпляр класса (в данном случае - экземпляр класса "content") из переменной $self:

<?php
    class content_custom extends def_module {

        public function __construct($self) {
            $self->__loadLib("/temp.php", (dirname(__FILE__)));
            $self->__implement("content_custom_temp");
        }

        public function testMenu() {
            $temp = array(
                'foo' => 'foo',
                'bar' => 'bar'
            );

            return def_module::parseTemplate('', $temp);
        }

    };
?>

И прописываем второй созданный макрос в файле permissions.php:

<?php
    $permissions['content'][] = 'testMenu';
    $permissions['content'][] = 'testMenu2';
?>

Теперь оба наших макроса можно использовать в шаблоне сайта.
Обратите внимание, что при использовании на сайте шаблонов нового формата, работа расширений функциональности (PHP) происходит следующим образом: при вызове вашего макроса через протокол udata (site.ru/udata://content/testMenu) и "напрямую" (site.ru/content/testMenu), отрабатывать будут те php-скрипты, которые находятся в той же директории (~/templates/{имя_шаблона}/), что и шаблон, назначенный "Основным" для данного домена.
В случае необходимости вызвать напрямую макрос из шаблона, не назначенного основным - следует добавить к строке вызова параметр "?template_id={идентификатор шаблона в админ-панели}".
При вызове же макроса на странице, будут отрабатывать php-скрипты, принадлежащие шаблону данной страницы.