Wiki from ADT Web Solutions - Вклад участника [ru]

Расширение функциональности модулей

2020-11-06T08:28:46Z

Olga: /* Создание кастомных событий внутри шаблона */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

Иногда добавленные таким способом методы выдают ошибку, с одним таким случаем только что столкнулись, второй из возможных - это когда в копируемом методе используются другие методы из файла macros.php в виде $this->название_метода(). При вызове из другого класса метод не обнаруживается.. В этом случае надо заменить вызов на $this->module->название_метода(), не зря же переменная $module была добавлена в кастомный класс.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё довольно далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

=== Организация повторяющегося кода ===

На главной странице мы вывели новости с анонсами, но совсем забыли про собственно раздел новостей, где всё ещё используем макрос lastlist(). Было бы правильно добавить в PhpExtension метод:

<syntaxhighlight lang="php">
/**
* Возвращает список последних новостей
* @param bool|int $newsPageId id ленты новостей
* @return bool|array
*/
public function getNewsList($newsPageId = false) {
if (!$id) {
$templateEngine = $this->getTemplateEngine();
$newsList = $templateEngine->getCommonVar('settings')->newslist;
if (!empty($newsList)) $newsPageId = $newsList[0]->id;
else return false;
}
return $this->macros("news", "newslist", [$newsPageId]);
}
</syntaxhighlight>

Если передан id ленты новостей, то возвращаем массив, если нет - пытаемся найти его в настройках. После этого можем в файле content/home/news.phtml написать:

<syntaxhighlight lang="php">
<?php
$newsList = $this->getNewsList();
?>
</syntaxhighlight>

а в файле news/rubric.phtml:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
$newsList = $this->getNewsList($page->id);
?>
</syntaxhighlight>

=== Когда надо добавлять методы в в класс шаблонизатора? ===

Даже на этих примерах видно, насколько понятней становится код шаблонов. По сути, это все равно обращение к базе в процессе рендеринга. Но выглядит лучше, и код обращений собран в одном файле. Поэтому лучше создавать методы класса, если надо:

* Организовать глобальны переменные
* Убрать из шаблона большие куски кода, особенно содержащие обращения к базе данных
* Ликвидировать повторяющиеся в разных фрагментах шаблона куски кода

== Вместо заключения ==

За рамками этой инструкции остались события, это довольно большая тема, и, к счастью, [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/sobytijnaya_model_umicms/ хорошо документированная].

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

Надеюсь, инструкция помогла на примерах понять архитектуру UMI CMS и принципы построения новых элементов. Самое время [[Что дальше?|перейти к практике]]!

Расширение функциональности модулей

2020-11-06T08:27:30Z

Olga: /* Использование кастомного метода в шаблона */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

Иногда добавленные таким способом методы выдают ошибку, с одним таким случаем только что столкнулись, второй из возможных - это когда в копируемом методе используются другие методы из файла macros.php в виде $this->название_метода(). При вызове из другого класса метод не обнаруживается.. В этом случае надо заменить вызов на $this->module->название_метода(), не зря же переменная $module была добавлена в кастомный класс.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

=== Организация повторяющегося кода ===

На главной странице мы вывели новости с анонсами, но совсем забыли про собственно раздел новостей, где всё ещё используем макрос lastlist(). Было бы правильно добавить в PhpExtension метод:

<syntaxhighlight lang="php">
/**
* Возвращает список последних новостей
* @param bool|int $newsPageId id ленты новостей
* @return bool|array
*/
public function getNewsList($newsPageId = false) {
if (!$id) {
$templateEngine = $this->getTemplateEngine();
$newsList = $templateEngine->getCommonVar('settings')->newslist;
if (!empty($newsList)) $newsPageId = $newsList[0]->id;
else return false;
}
return $this->macros("news", "newslist", [$newsPageId]);
}
</syntaxhighlight>

Если передан id ленты новостей, то возвращаем массив, если нет - пытаемся найти его в настройках. После этого можем в файле content/home/news.phtml написать:

<syntaxhighlight lang="php">
<?php
$newsList = $this->getNewsList();
?>
</syntaxhighlight>

а в файле news/rubric.phtml:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
$newsList = $this->getNewsList($page->id);
?>
</syntaxhighlight>

=== Когда надо добавлять методы в в класс шаблонизатора? ===

Даже на этих примерах видно, насколько понятней становится код шаблонов. По сути, это все равно обращение к базе в процессе рендеринга. Но выглядит лучше, и код обращений собран в одном файле. Поэтому лучше создавать методы класса, если надо:

* Организовать глобальны переменные
* Убрать из шаблона большие куски кода, особенно содержащие обращения к базе данных
* Ликвидировать повторяющиеся в разных фрагментах шаблона куски кода

== Вместо заключения ==

За рамками этой инструкции остались события, это довольно большая тема, и, к счастью, [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/sobytijnaya_model_umicms/ хорошо документированная].

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

Надеюсь, инструкция помогла на примерах понять архитектуру UMI CMS и принципы построения новых элементов. Самое время [[Что дальше?|перейти к практике]]!

Википедия студии ADT Web Solutions

2020-11-06T08:18:25Z

Olga:

= UMI CMS: первые шаги с PHP-шаблонизатором =

''Инструкция для начинающих разработчиков, написанная начинающим разработчиком, который много раз прошёл по этим граблям''

# [[Преимущества UMI CMS]]
# [[Установка UMI CMS Trial]]
# [[Создание сайта на UMI CMS Trial]]
#* [[Структура сайта]]
#* [[Создание "правильного" шаблона для сайта]]
#* [[Добавление возможности Edit-in-place]]
#* [[Создание настроек сайта]]
#* [[Шаблоны данных сайта]]
#* [[Другие модули системы]]
#* [[Шаблон для главной страницы]]
#* [[Расширение функциональности модулей]]
# [[Что дальше?]]

Расширение функциональности модулей

2020-11-06T08:16:48Z

Olga: /* Организация повторяющегося кода */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

=== Организация повторяющегося кода ===

На главной странице мы вывели новости с анонсами, но совсем забыли про собственно раздел новостей, где всё ещё используем макрос lastlist(). Было бы правильно добавить в PhpExtension метод:

<syntaxhighlight lang="php">
/**
* Возвращает список последних новостей
* @param bool|int $newsPageId id ленты новостей
* @return bool|array
*/
public function getNewsList($newsPageId = false) {
if (!$id) {
$templateEngine = $this->getTemplateEngine();
$newsList = $templateEngine->getCommonVar('settings')->newslist;
if (!empty($newsList)) $newsPageId = $newsList[0]->id;
else return false;
}
return $this->macros("news", "newslist", [$newsPageId]);
}
</syntaxhighlight>

Если передан id ленты новостей, то возвращаем массив, если нет - пытаемся найти его в настройках. После этого можем в файле content/home/news.phtml написать:

<syntaxhighlight lang="php">
<?php
$newsList = $this->getNewsList();
?>
</syntaxhighlight>

а в файле news/rubric.phtml:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
$newsList = $this->getNewsList($page->id);
?>
</syntaxhighlight>

=== Когда надо добавлять методы в в класс шаблонизатора? ===

Даже на этих примерах видно, насколько понятней становится код шаблонов. По сути, это все равно обращение к базе в процессе рендеринга. Но выглядит лучше, и код обращений собран в одном файле. Поэтому лучше создавать методы класса, если надо:

* Организовать глобальны переменные
* Убрать из шаблона большие куски кода, особенно содержащие обращения к базе данных
* Ликвидировать повторяющиеся в разных фрагментах шаблона куски кода

== Вместо заключения ==

За рамками этой инструкции остались события, это довольно большая тема, и, к счастью, [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/sobytijnaya_model_umicms/ хорошо документированная].

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

Надеюсь, инструкция помогла на примерах понять архитектуру UMI CMS и принципы построения новых элементов. Самое время [[Что дальше?|перейти к практике]]!

Расширение функциональности модулей

2020-11-06T08:10:20Z

Olga: /* Организация повторяющегося кода */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

=== Организация повторяющегося кода ===

На главной странице мы вывели новости с анонсами, но совсем забыли про собственно раздел новостей, где всё ещё используем макрос lastlist(). Было бы правильно добавить в PhpExtension метод:

<syntaxhighlight lang="php">
/**
* Возвращает список последних новостей
* @param bool|int $newsPageId id ленты новостей
* @return bool|array
*/
public function getNewsList($newsPageId = false) {
if (!$id) {
$templateEngine = $this->getTemplateEngine();
$newsList = $templateEngine->getCommonVar('settings')->newslist;
if (!empty($newsList)) $newsPageId = $newsList[0]->id;
else return false;
}
return $this->macros("news", "newslist", [$newsPageId]);
}
</syntaxhighlight>

Если передан id ленты новостей, то возвращаем массив, если нет - пытаемся найти его в настройках. После этого можем в файле content/home/news.phtml написать:

<syntaxhighlight lang="php">
<?php
$newsList = $this->getNewsList();
?>
</syntaxhighlight>

а в файле news/rubric.phtml:

<syntaxhighlight lang="php">
<?php
$newsList = $this->getNewsList($variables['pageId']);
?>
</syntaxhighlight>

=== Когда надо добавлять методы в в класс шаблонизатора? ===

Даже на этих примерах видно, насколько понятней становится код шаблонов. По сути, это все равно обращение к базе в процессе рендеринга. Но выглядит лучше, и код обращений собран в одном файле. Поэтому лучше создавать методы класса, если надо:

* Организовать глобальны переменные
* Убрать из шаблона большие куски кода, особенно содержащие обращения к базе данных
* Ликвидировать повторяющиеся в разных фрагментах шаблона куски кода

== Вместо заключения ==

За рамками этой инструкции остались события, это довольно большая тема, и, к счастью, [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/sobytijnaya_model_umicms/ хорошо документированная].

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

Надеюсь, инструкция помогла на примерах понять архитектуру UMI CMS и принципы построения новых элементов. Самое время [[Что дальше?|перейти к практике]]!

Расширение функциональности модулей

2020-11-06T08:08:46Z

Olga: /* Организация повторяющегося кода */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

=== Организация повторяющегося кода ===

На главной странице мы вывели новости с анонсами, но совсем забыли про собственно раздел новостей, где всё ещё используем макрос lastlist(). Было бы правильно добавить в PhpExtension метод:

<syntaxhighlight lang="php">
/**
* Возвращает список последних новостей
* @param bool|int $newsPageId id ленты новостей
* @return bool|array
*/
public function getNewsList($newsPageId = false) {
if (!$id) {
$templateEngine = $this->getTemplateEngine();
$newsList = $templateEngine->getCommonVar('settings')->newslist;
if (!empty($newsList)) $newsPageId = $newsList[0]->id;
else return false
}
return $this->macros("news", "newslist", [$newsPageId]);
}
</syntaxhighlight>

Если передан id ленты новостей, то возвращаем массив, если нет - пытаемся найти его в настройках. После этого можем в файле content/home/news.phtml написать:

<syntaxhighlight lang="php">
<?php
$newsList = $this->getNewsList();
?>
</syntaxhighlight>

а в файле news/rubric.phtml:

<syntaxhighlight lang="php">
<?php
$newsList = $this->getNewsList($variables['pageId']);
?>
</syntaxhighlight>

=== Когда надо добавлять методы в в класс шаблонизатора? ===

Даже на этих примерах видно, насколько понятней становится код шаблонов. По сути, это все равно обращение к базе в процессе рендеринга. Но выглядит лучше, и код обращений собран в одном файле. Поэтому лучше создавать методы класса, если надо:

* Организовать глобальны переменные
* Убрать из шаблона большие куски кода, особенно содержащие обращения к базе данных
* Ликвидировать повторяющиеся в разных фрагментах шаблона куски кода

== Вместо заключения ==

За рамками этой инструкции остались события, это довольно большая тема, и, к счастью, [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/sobytijnaya_model_umicms/ хорошо документированная].

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

Надеюсь, инструкция помогла на примерах понять архитектуру UMI CMS и принципы построения новых элементов. Самое время [[Что дальше?|перейти к практике]]!

Расширение функциональности модулей

2020-11-06T07:45:09Z

Olga: /* Организация повторяющегося кода */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

=== Организация повторяющегося кода ===

На главной странице мы вывели новости с анонсами, но совсем забыли про собственно раздел новостей, где всё ещё используем макрос lastlist(). Было бы правильно добавить в PhpExtension метод:

<syntaxhighlight lang="php">
/**
* Возвращает список последних новостей
* @param bool|int $newsPageId id ленты новостей
* @return bool|array
*/
public function getNewsList($newsPageId = false) {
if (!$id) {
$templateEngine = $this->getTemplateEngine();
$newsList = $templateEngine->getCommonVar('settings')->newslist;
if (!empty($newsList)) $newsPageId = $newsList[0]->id;
else {
}
}
return $this->macros("news", "newslist", [$newsPageId]);
}
</syntaxhighlight>

После этого можем

Даже на этих примерах видно, насколько наглядней становится код шаблонов. Конечно, по сути это все равно обращение к базе в процессе рендеринга шаблона. Но выглядит лучше, и код обращений собран в одном файле.

== Вместо заключения ==

За рамками этой инструкции остались события, это довольно большая тема, и, к счастью, [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/sobytijnaya_model_umicms/ хорошо документированная].

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

Надеюсь, инструкция помогла на примерах понять архитектуру UMI CMS и принципы построения новых элементов. Самое время [[Что дальше?|перейти к практике]]!

Расширение функциональности модулей

2020-11-06T07:43:18Z

Olga: /* Получение блоков для главной страницы */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

=== Организация повторяющегося кода ===

На главной странице мы вывели новости с анонсами, но совсем забыли про собственно раздел новостей, где всё ещё используем макрос lastlist(). Было бы правильно добавить в PhpExtension метод:

<syntaxhighlight lang="php">
/**
* Возвращает список последних новостей
* @param bool|int $newsPageId id ленты новостей
* @return bool|array
*/
public function getNewsList($newsPageId = false) {
if (!$id) {
$newsList = $this->getCommonVar('settings')->newslist;
if (!empty($newsList)) $newsPageId = $newsList[0]->id;
else {
}
}
return $this->macros("news", "newslist", [$newsPageId]);
}
</syntaxhighlight>

После этого можем

Даже на этих примерах видно, насколько наглядней становится код шаблонов. Конечно, по сути это все равно обращение к базе в процессе рендеринга шаблона. Но выглядит лучше, и код обращений собран в одном файле.

== Вместо заключения ==

За рамками этой инструкции остались события, это довольно большая тема, и, к счастью, [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/sobytijnaya_model_umicms/ хорошо документированная].

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

Надеюсь, инструкция помогла на примерах понять архитектуру UMI CMS и принципы построения новых элементов. Самое время [[Что дальше?|перейти к практике]]!

Создание настроек сайта

2020-11-05T20:10:01Z

Olga: /* Вывод настроек в шаблоне */

Выбираем в админке раздел "Настройки сайта" и не видим никаких настроек:

[[Файл:Screenshot 2020-10-30 UMI CMS - Настройки.png|обрамить|без]]

Жмём "Создать настройки", и создаём:

[[Файл:Screenshot 2020-10-30 UMI CMS - Создание.png|обрамить|без]]

Название может быть любое, идентификатор - только латиница. Если создаем настройки для русской версии сайта, на английской они видны не будут. Что в принципе логично.

Теперь видим, что настройки появились:

[[Файл:Screenshot 2 UMI CMS - Настройки (2).png|обрамить|без]]

Вопрос только - что с ними делать? Ставим рядом галку, в пиктографическом меню нажимаем "Редактировать" - и видим ту же самую форму, что только что заполнили. Где логотип, где копирайт? Так мы незаметно подошли к большой теме - [[Шаблоны данных сайта|Создание шаблонов данных]].

== Вывод настроек в шаблоне ==

Добавим в настройки логотип и копирайт:

[[Файл:Screenshot 4 UMI CMS - Редактирование.png|обрамить|без]]

Теперь попробуем вывести всё это на страницах сайта.

И тут мы сталкиваемся с очередной засадой UMI CMS. Казалось бы, каждому сайту должен соответствовать какой-то один набор настроек. Но в интерфейсе видим, что этих наборов можно создать сколько угодно. '''Господа разработчики''', может, стоило бы для упрощения ограничить эти возможности? Кто-то вообще использует больше одного набора настроек для конкретной языковой версии сайта? Было бы шикарно получать настройки прямо в массиве $variables, как вы считаете?

Зато есть повод поупражняться с API системы. Один из способов получить настройки - использовать название настроек, в данном случае 'demo':

<syntaxhighlight lang="php">
$settings = $this->getObjectById($this->macros('umiSettings', 'getIdByName', 'demo']));
var_dump($settings);
</syntaxhighlight>

Здесь мы использовали метод getIdByName('...') модуля umiSettings для получения id настроек по названию (это именно название, не идентификатор), а потом получили сам объект настроек при помощи метода getObjectById().

Добавим этот код в самое начало common.phtml. К счастью, в настройках разных языковых версий можно задавать одно и то же название, а то было бы совсем грустно. В общем, получилось. Если добавить на страницу <?= $settings->copyright ?>, то увидим копирайт, который ввели.

Теперь попробуем другой путь, ведь мы не фанаты делать кучу настроек:

<syntaxhighlight lang="php">
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
var_dump($settings);
</syntaxhighlight>

В этом коде был использован самый мощный класс ядра UMI - selector. Он подробно описан в документации. Чего в документации нет, так это - что подставлять в качестве 'object-type'. Но в админке есть где посмотреть: 'Шаблоны данных' - 'Настройки модуля' (ссылка справа вверху). Для начала лучше в этих настройках ничего не менять, но в качестве справочника - бесценно!

Здесь мы ищем селектором те единственные настройки, что соответствуют конкретной языковой версии нашего сайта. Синтаксически это почти SQL-запрос, на мой взгляд, тут всё просто.

UMI CMS в конце каждой страницы выдает время её формирования, что очень удобно. Легко убедиться, что второй способ на 0.001 секунды быстрее, помимо прочих его преимуществ. Конечно, неплохо бы проверить, что хоть какие-то настройки нашлись. Кроме этого, хотелось бы получить настройки в самом начале, а использовать их в произвольных фрагментах нашего шаблона. В результате модифицируем код common.phtml как-то так:

<syntaxhighlight lang="php">
<?php
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$variables['settings'] = array_shift($set->result());
if (empty($variables['settings'])) {
echo $this->translate('no settings');
exit();
}
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Копирайт мы собирались использовать в подвале сайта, поэтому пишем в footer.phtml:

<syntaxhighlight lang="php">
<footer>
<div class="container">
<?= $variables['settings']->copyright ?><?= date("Y") ?>

</div>
</footer>
</syntaxhighlight>

Проверяем результат - всё получилось! Теперь надо разобраться с логотипом. Добавляем <?php var_dump($variables['settings']->logo); ?> в файл header.phtml, и видим, что это объект. Причем - ещё одна засада UMI CMS - все свойства без исключения protected!!! Зато в нем есть все, что нам нужно. Итак, изучаем документацию по классам umiFile и umiImageFile, и новый header.phtml будет выглядеть примерно так:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
$logo = $variables['settings']->logo;
?>
<header>
<nav class="navbar navbar-expand-lg navbar-light bg-light">
<a class="navbar-brand" href="/">
<?php if ($logo): ?>
<img src="/<?= $logo->getFilePath() ?>" title="<?= $logo->getTitle() ?>" alt="<?= $logo->getAlt() ?>">
<?php endif; ?>
</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>

<div class="collapse navbar-collapse" id="navbarSupportedContent">
<ul class="navbar-nav mr-auto">
<?php
foreach ($menuTree['lines'] as $item) {
$dropdown = !empty($item['items']['nodes:item']);
$active = !empty($item['attribute:status']);
if (isset($item['link']) && isset($item['name'])) {
if ($dropdown) {
?>
<li class="nav-item dropdown <?=$active?'active':''?>">
<a class="nav-link dropdown-toggle" href="<?= $item['link'] ?>" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><?= $item['name'] ?></a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
<?php
foreach ($item['items']['item'] as $sub) {
if (isset($sub['link']) && isset($sub['name'])) {
?>
<a class="dropdown-item" href="<?= $sub['link'] ?>"><?= $sub['name'] ?></a>
<?php
}
}
?>
</div>
</li>
<?php
} else {
?>
<li class="nav-item <?=$active?'active':''?>">
<a class="nav-link" href="<?= $item['link'] ?>"><?= $item['name'] ?></a>
</li>
<?php
}
}
}
?>
</ul>
</div>
</nav>
</header>
</syntaxhighlight>

Почему перед адресом изображения стоит '/'? Потому что getFilePath() зачем-то перед адресом ставит точку, хоть адрес возвращает абсолютный. Загадка. В качестве alt и title пробуем получить значения, которые должны были задать в админке при заливке файла. Но поскольку ничего не задали, они будут пустые. А вообще, по-хорошему, надо добавить в настройки еще одно поле - название компании, и выводить именно его.

== Edit-in-place для настроек ==

Теперь осталось добавить возможность изменять эти поля прямо на сайте. В принципе, ничего сложного:

<syntaxhighlight lang="html">
<img umi:object-id="<?= $logo->getId() ?>" umi:field-name="logo" src="/<?= $logo->getFilePath() ?>" title="<?= $logo->getTitle() ?>" alt="<?= $logo->getAlt() ?>">
</syntaxhighlight>

Это для логотипа, а для копирайта:

<syntaxhighlight lang="php">
<span umi:object-id="<?= $logo->getId() ?>" umi:field-name="logo" umi:empty="<?= $this->translate('empty_copyright') ?>">
<?= $variables['settings']->copyright ?>
</span> <?= date("Y") ?>
</syntaxhighlight>

Заметим, что псевдо-атрибуты для id контентных страниц и объектов отличаются, если для полей страниц мы использовали атрибут umi:element-id, то для полей объектов приходится писать umi:object-id. Это отражение внутреннего деления UMI CMS на страницы контента и объекты, за работу с которыми отвечают разные методы.

Также пришлось добавить дополнительный <nowiki><span></nowiki>, чтобы копирайт был в отдельном контейнере.

== Другие модули системы ==

Пока нам для сайта хватало модуля content, немного использовали umiSettings. Однако полезных модулей гораздо больше, и пора наконец [[Другие модули системы|добавить на сайт раздел Новости]].

Создание "правильного" шаблона для сайта

2020-11-05T20:04:50Z

Olga: /* Добавляем меню */

Для компактности HTML кода буду использовать библиотеку Bootstrap4 - пользуйтесь своими любимыми фреймворками, если не нравится. Итак, сделаем код нашего шаблона несколько более полным:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<!DOCTYPE html>
<html>
<head>
<base href="/templates/default/">
<title><?= $page->title ?></title>
<meta charset="utf-8">
<meta name="description" content="<?= $page->description ?>">
<meta name="keywords" content="<?= $page->keywords ?>">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
</head>
<body>
<header>
</header>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<p><?= $page->content ?></p>
</div>
</div>
</div>
</section>
</main>
<footer>
</footer>

<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

В <head> добавили тэг <base ...>, потому что в дальнейшем все, что касается конкретного сайта, планируем хранить в папке конкретного шаблона, в нашем случае default. UMI CMS считает папку шаблона корневой директорией сайта, но это не распространяется на стили, скрипты и картинки.

Теперь главная страница сайта приобрела более "причёсанный" вид:

[[Файл:Screenshot 2020-10-29 Главная.png|обрамить|без]]

Заметим, что Title у страницы пустой, что не слишком хорошо. Можно прописывать это поле для каждой страницы. Но есть способ получше.

== Настраиваем Title и другие SEO-параметры ==

В шаблоне меняем строки заголовка, описания и ключевых слов на:

<syntaxhighlight lang="html">
<title><?= $this->escape($variables['title']) ?></title>
<meta name="description" content="<?= $variables['meta']['description'] ?>">
<meta name="keywords" content="<?= $variables['meta']['keywords'] ?>">
</syntaxhighlight>

и видим теперь заголовок <title>UMI.CMS - Страница 1</title>. Нам "UMI.CMS - " ни разу не нужно. Чтобы настроить параметры по умолчанию, в модулях (под бабочкой) находим раздел SEO, в нем справа вверху видим ссылку "Настройка модуля", жмём и настраиваем, там всё просто. Заменяю "UMI.CMS - " на "Демонстрационный сайт - ".

Чем отличается от прежнего варианта шаблона? Тем, что мы не выводим тупо поле из данных конкретной страницы, а позволяем CMS сформировать для нас эти параметры, используя настройки по умолчанию.

== Делим шаблон на части ==

Чтобы не мучиться с длинной простынёй кода, существует хорошая практика делить его на разумные фрагменты. Скажем, сразу хочется выделить <head>, <header> и <footer>.

В директории /templates/default/php/ создаём поддиректорию layout, а в ней файлы наших фрагментов:

* head.phtml
* header.phtml
* main.phtml
* footer.phtml

Помещаем в эти файлы фрагменты кода шаблонов, например, head.phtml будет выглядеть вот так:

<syntaxhighlight lang="php">
<head>
<base href="/templates/default/">
<title><?= $variables['title'] ?></title>
<meta charset="utf-8">
<meta name="description" content="<?= $variables['meta']['description'] ?>">
<meta name="keywords" content="<?= $variables['meta']['keywords'] ?>">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
</head>
</syntaxhighlight>

А main.phtml вот так:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<p><?= $page->content ?></p>
</div>
</div>
</div>
</section>
</main>
</syntaxhighlight>

Теперь в шаблоне можно просто подключить эти фрагменты:

<syntaxhighlight lang="php">
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Заметим, что в качестве первого параметра при вызове метода render() мы передаем массив $variables конкретной страницы. Второй параметр - это адрес шаблона относительно папки php и без расшмрения ".phtml". Поэтому делать у файлов шаблона именно такое расширение - '''обязательно'''! Иначе не найдет.

== Добавляем меню ==

Выше мы использовали волшебную переменную $this, но для вызова только одного метода - render(). А какие еще методы нам доступны?

Полный список был бы весьма желателен. Но если кратко - все публичные методы модуля '''content''', их описание и код можно посмотреть в /classes/components/content/class.php и /classes/components/content/macros.php, а также системные и сервисные методы, наследуемые этими классами. Методы класса можно использовать непосредственно, макросы - при помощи метода macros().

Нам для сайта надо получить "дерево" меню. Для этого в файл header.phtml добавляем код:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
var_dump($menuTree);
?>
<header>
</header>
</syntaxhighlight>

Первый параметр метода macros() - название модуля, второй - название метода, третий - параметры, передаваемые методу. Список параметров можно посмотреть в коде метода, все макросы хорошо документированы комментариями. В данном случае используем:

* шаблон не задан (шаблон задается в других шаблонизаторах, в PHP не работает)
* 2 уровня вложенности (у нас пока один, но можем потом добавить)
* начиная от корня сайта (можно указать id страницы, и тогда "дерево" будет построено от неё)
* выдавать признак, что есть дочерние страницы
* id текущей страницы передаем, чтобы в результате этот пункт был выделен как активный.

Чтобы изучить возможность добавления второго уровня, добавим вложенную страницу внутрь нашей "Страницы 1". Для этого с разделе "Структура" сайта ставим галочку рядом со "Страница 1" и нажимаем плюс в меню. Назовем ее "Страница 3" и page3 в качестве псевдостатического адреса. Обновляем страницу в браузере - в массиве $menuTree ничего не поменялось!!!

Это очередная засада UMI CMS. Чтобы используемый нами макрос выдавал вложенные страницы, надо в данном случае на "Странице 1" в '''Дополнительных параметрах''' поставить признаки "Меню всегда развернуто" и "Показывать подменю". Понятно, что это вопрос умолчаний, но в современных сайтах чаще используется развернутое меню, управляемое JS, а не как раньше - статическое индивидуальное меню для каждой страницы.

'''Господа разработчики''', может, пора уже облегчить жизнь редакторам сайтов, и изменить настройки? Пусть у всех страниц эти признаки будут по умолчанию включены, как вы считаете?

Полюбовавшись структурой полученного массива, можем теперь вывести нормальное меню сайта:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
?>
<header>
<nav class="navbar navbar-expand-lg navbar-light bg-light">
<a class="navbar-brand" href="/">Логотип</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>

<div class="collapse navbar-collapse" id="navbarSupportedContent">
<ul class="navbar-nav mr-auto">
<?php
foreach ($menuTree['lines'] as $item) {
$dropdown = !empty($item['items']);
$active = !empty($item['status']);
if (isset($item['link']) && isset($item['name'])) {
if ($dropdown) {
?>
<li class="nav-item dropdown <?=$active?'active':''?>">
<a class="nav-link dropdown-toggle" href="<?= $item['link'] ?>" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><?= $item['name'] ?></a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
<?php
foreach ($item['items'] as $sub) {
if (isset($sub['link']) && isset($sub['name'])) {
?>
<a class="dropdown-item" href="<?= $sub['link'] ?>"><?= $sub['name'] ?></a>
<?php
}
}
?>
</div>
</li>
<?php
} else {
?>
<li class="nav-item <?=$active?'active':''?>">
<a class="nav-link" href="<?= $item['link'] ?>"><?= $item['name'] ?></a>
</li>
<?php
}
}
}
?>
</ul>
</div>
</nav>
</header>
</syntaxhighlight>

В этом виде сайт уже почти настоящий. На страницах выводится то, что перед этим мы закинули через админку. Но хотелось бы иметь возможность вносить правки прямо на сайте. UMI CMS дает такую возможность, её надо просто [[Добавление возможности Edit-in-place|внести в наш шаблон]].

Создание "правильного" шаблона для сайта

2020-11-05T20:00:58Z

Olga: /* Делим шаблон на части */

Для компактности HTML кода буду использовать библиотеку Bootstrap4 - пользуйтесь своими любимыми фреймворками, если не нравится. Итак, сделаем код нашего шаблона несколько более полным:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<!DOCTYPE html>
<html>
<head>
<base href="/templates/default/">
<title><?= $page->title ?></title>
<meta charset="utf-8">
<meta name="description" content="<?= $page->description ?>">
<meta name="keywords" content="<?= $page->keywords ?>">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
</head>
<body>
<header>
</header>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<p><?= $page->content ?></p>
</div>
</div>
</div>
</section>
</main>
<footer>
</footer>

<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

В <head> добавили тэг <base ...>, потому что в дальнейшем все, что касается конкретного сайта, планируем хранить в папке конкретного шаблона, в нашем случае default. UMI CMS считает папку шаблона корневой директорией сайта, но это не распространяется на стили, скрипты и картинки.

Теперь главная страница сайта приобрела более "причёсанный" вид:

[[Файл:Screenshot 2020-10-29 Главная.png|обрамить|без]]

Заметим, что Title у страницы пустой, что не слишком хорошо. Можно прописывать это поле для каждой страницы. Но есть способ получше.

== Настраиваем Title и другие SEO-параметры ==

В шаблоне меняем строки заголовка, описания и ключевых слов на:

<syntaxhighlight lang="html">
<title><?= $this->escape($variables['title']) ?></title>
<meta name="description" content="<?= $variables['meta']['description'] ?>">
<meta name="keywords" content="<?= $variables['meta']['keywords'] ?>">
</syntaxhighlight>

и видим теперь заголовок <title>UMI.CMS - Страница 1</title>. Нам "UMI.CMS - " ни разу не нужно. Чтобы настроить параметры по умолчанию, в модулях (под бабочкой) находим раздел SEO, в нем справа вверху видим ссылку "Настройка модуля", жмём и настраиваем, там всё просто. Заменяю "UMI.CMS - " на "Демонстрационный сайт - ".

Чем отличается от прежнего варианта шаблона? Тем, что мы не выводим тупо поле из данных конкретной страницы, а позволяем CMS сформировать для нас эти параметры, используя настройки по умолчанию.

== Делим шаблон на части ==

Чтобы не мучиться с длинной простынёй кода, существует хорошая практика делить его на разумные фрагменты. Скажем, сразу хочется выделить <head>, <header> и <footer>.

В директории /templates/default/php/ создаём поддиректорию layout, а в ней файлы наших фрагментов:

* head.phtml
* header.phtml
* main.phtml
* footer.phtml

Помещаем в эти файлы фрагменты кода шаблонов, например, head.phtml будет выглядеть вот так:

<syntaxhighlight lang="php">
<head>
<base href="/templates/default/">
<title><?= $variables['title'] ?></title>
<meta charset="utf-8">
<meta name="description" content="<?= $variables['meta']['description'] ?>">
<meta name="keywords" content="<?= $variables['meta']['keywords'] ?>">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
</head>
</syntaxhighlight>

А main.phtml вот так:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<p><?= $page->content ?></p>
</div>
</div>
</div>
</section>
</main>
</syntaxhighlight>

Теперь в шаблоне можно просто подключить эти фрагменты:

<syntaxhighlight lang="php">
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Заметим, что в качестве первого параметра при вызове метода render() мы передаем массив $variables конкретной страницы. Второй параметр - это адрес шаблона относительно папки php и без расшмрения ".phtml". Поэтому делать у файлов шаблона именно такое расширение - '''обязательно'''! Иначе не найдет.

== Добавляем меню ==

Выше мы использовали волшебную переменную $this, но для вызова только одного метода - render(). А какие еще методы нам доступны?

Полный список был бы весьма желателен. Но если кратко - все публичные методы модуля '''content''', их описание и код можно посмотреть в /classes/components/content/class.php и /classes/components/content/macros.php, а также системные и сервисные методы, наследуемые этими классами. Методы класса можно использовать непосредственно, макросы - при помощи метода macros().

Нам для сайта надо получить "дерево" меню. Для этого в файл header.phtml добавляем код:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
var_dump($menuTree);
?>
<header>
</header>
</syntaxhighlight>

Первый параметр метода macros() - название модуля, второй - название метода, третий - параметры, передаваемые методу. Список параметров можно посмотреть в коде метода, все макросы хорошо документированы комментариями. В данном случае используем:

* шаблон не задан (шаблон задается в других шаблонизаторах, в PHP не работает)
* 2 уровня вложенности (у нас пока один, но можем потом добавить)
* начиная от корня сайта (можно указать id страницы, и тогда "дерево" будет построено от неё)
* выдавать признак, что есть дочерние страницы
* id текущей страницы передаем, чтобы в результате этот пункт был выделен как активный.

Чтобы изучить возможность добавления второго уровня, добавим вложенную страницу внутрь нашей "Страницы 1". Для этого с разделе "Структура" сайта ставим галочку рядом со "Страница 1" и нажимаем плюс в меню. Назовем ее "Страница 3" и page3 в качестве псевдостатического адреса. Обновляем страницу в браузере - в массиве $menuTree ничего не поменялось!!!

Это очередная засада UMI CMS. Чтобы используемый нами макрос выдавал вложенные страницы, надо в данном случае на "Странице 1" в '''Дополнительных параметрах''' поставить признаки "Меню всегда развернуто" и "Показывать подменю". Понятно, что это вопрос умолчаний, но в современных сайтах чаще используется развернутое меню, управляемое JS, а не как раньше - статическое индивидуальное меню для каждой страницы.

'''Господа разработчики''', может, пора уже облегчить жизнь редакторам сайтов, и изменить настройки? Пусть у всех страниц эти признаки будут по умолчанию включены, как вы считаете?

Полюбовавшись структурой полученного массива, можем теперь вывести нормальное меню сайта:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
?>
<header>
<nav class="navbar navbar-expand-lg navbar-light bg-light">
<a class="navbar-brand" href="/">Логотип</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>

<div class="collapse navbar-collapse" id="navbarSupportedContent">
<ul class="navbar-nav mr-auto">
<?php
foreach ($menuTree['void:lines'] as $item) {
$dropdown = !empty($item['items']['nodes:item']);
$active = !empty($item['attribute:status']);
if (isset($item['link']) && isset($item['name'])) {
if ($dropdown) {
?>
<li class="nav-item dropdown <?=$active?'active':''?>">
<a class="nav-link dropdown-toggle" href="<?= $item['link'] ?>" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><?= $item['name'] ?></a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
<?php
foreach ($item['items']['nodes:item'] as $sub) {
if (isset($sub['link']) && isset($sub['name'])) {
?>
<a class="dropdown-item" href="<?= $sub['link'] ?>"><?= $sub['name'] ?></a>
<?php
}
}
?>
</div>
</li>
<?php
} else {
?>
<li class="nav-item <?=$active?'active':''?>">
<a class="nav-link" href="<?= $item['link'] ?>"><?= $item['name'] ?></a>
</li>
<?php
}
}
}
?>
</ul>
</div>
</nav>
</header>
</syntaxhighlight>

В этом виде сайт уже почти настоящий. На страницах выводится то, что перед этим мы закинули через админку. Но хотелось бы иметь возможность вносить правки прямо на сайте. UMI CMS дает такую возможность, её надо просто [[Добавление возможности Edit-in-place|внести в наш шаблон]].

Создание "правильного" шаблона для сайта

2020-11-05T20:00:23Z

Olga: /* Делим шаблон на части */

Для компактности HTML кода буду использовать библиотеку Bootstrap4 - пользуйтесь своими любимыми фреймворками, если не нравится. Итак, сделаем код нашего шаблона несколько более полным:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<!DOCTYPE html>
<html>
<head>
<base href="/templates/default/">
<title><?= $page->title ?></title>
<meta charset="utf-8">
<meta name="description" content="<?= $page->description ?>">
<meta name="keywords" content="<?= $page->keywords ?>">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
</head>
<body>
<header>
</header>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<p><?= $page->content ?></p>
</div>
</div>
</div>
</section>
</main>
<footer>
</footer>

<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

В <head> добавили тэг <base ...>, потому что в дальнейшем все, что касается конкретного сайта, планируем хранить в папке конкретного шаблона, в нашем случае default. UMI CMS считает папку шаблона корневой директорией сайта, но это не распространяется на стили, скрипты и картинки.

Теперь главная страница сайта приобрела более "причёсанный" вид:

[[Файл:Screenshot 2020-10-29 Главная.png|обрамить|без]]

Заметим, что Title у страницы пустой, что не слишком хорошо. Можно прописывать это поле для каждой страницы. Но есть способ получше.

== Настраиваем Title и другие SEO-параметры ==

В шаблоне меняем строки заголовка, описания и ключевых слов на:

<syntaxhighlight lang="html">
<title><?= $this->escape($variables['title']) ?></title>
<meta name="description" content="<?= $variables['meta']['description'] ?>">
<meta name="keywords" content="<?= $variables['meta']['keywords'] ?>">
</syntaxhighlight>

и видим теперь заголовок <title>UMI.CMS - Страница 1</title>. Нам "UMI.CMS - " ни разу не нужно. Чтобы настроить параметры по умолчанию, в модулях (под бабочкой) находим раздел SEO, в нем справа вверху видим ссылку "Настройка модуля", жмём и настраиваем, там всё просто. Заменяю "UMI.CMS - " на "Демонстрационный сайт - ".

Чем отличается от прежнего варианта шаблона? Тем, что мы не выводим тупо поле из данных конкретной страницы, а позволяем CMS сформировать для нас эти параметры, используя настройки по умолчанию.

== Делим шаблон на части ==

Чтобы не мучиться с длинной простынёй кода, существует хорошая практика делить его на разумные фрагменты. Скажем, сразу хочется выделить <head>, <header> и <footer>.

В директории /templates/default/php/ создаём поддиректорию layout, а в ней файлы наших фрагментов:

* head.phtml
* header.phtml
* main.phtml
* footer.phtml

Помещаем в эти файлы фрагменты кода шаблонов, например, head.phtml будет выглядеть вот так:

<syntaxhighlight lang="php">
<head>
<base href="/templates/default/">
<title><?= $variables['title'] ?></title>
<meta charset="utf-8">
<meta name="description" content="<?= $variables['meta']['description'] ?>">
<meta name="keywords" content="<?= $variables['meta']['keywords'] ?>">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
</head>
</syntaxhighlight>

А main.phtml вот так:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<p><?= $page->content ?></p>
</div>
</div>
</div>
</section>
</main>
</syntaxhighlight>

Теперь в шаблоне можно просто подключить эти фрагменты:

<syntaxhighlight lang="html">
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Заметим, что в качестве первого параметра при вызове метода render() мы передаем массив $variables конкретной страницы. Второй параметр - это адрес шаблона относительно папки php и без расшмрения ".phtml". Поэтому делать у файлов шаблона именно такое расширение - '''обязательно'''! Иначе не найдет.

== Добавляем меню ==

Выше мы использовали волшебную переменную $this, но для вызова только одного метода - render(). А какие еще методы нам доступны?

Полный список был бы весьма желателен. Но если кратко - все публичные методы модуля '''content''', их описание и код можно посмотреть в /classes/components/content/class.php и /classes/components/content/macros.php, а также системные и сервисные методы, наследуемые этими классами. Методы класса можно использовать непосредственно, макросы - при помощи метода macros().

Нам для сайта надо получить "дерево" меню. Для этого в файл header.phtml добавляем код:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
var_dump($menuTree);
?>
<header>
</header>
</syntaxhighlight>

Первый параметр метода macros() - название модуля, второй - название метода, третий - параметры, передаваемые методу. Список параметров можно посмотреть в коде метода, все макросы хорошо документированы комментариями. В данном случае используем:

* шаблон не задан (шаблон задается в других шаблонизаторах, в PHP не работает)
* 2 уровня вложенности (у нас пока один, но можем потом добавить)
* начиная от корня сайта (можно указать id страницы, и тогда "дерево" будет построено от неё)
* выдавать признак, что есть дочерние страницы
* id текущей страницы передаем, чтобы в результате этот пункт был выделен как активный.

Чтобы изучить возможность добавления второго уровня, добавим вложенную страницу внутрь нашей "Страницы 1". Для этого с разделе "Структура" сайта ставим галочку рядом со "Страница 1" и нажимаем плюс в меню. Назовем ее "Страница 3" и page3 в качестве псевдостатического адреса. Обновляем страницу в браузере - в массиве $menuTree ничего не поменялось!!!

Это очередная засада UMI CMS. Чтобы используемый нами макрос выдавал вложенные страницы, надо в данном случае на "Странице 1" в '''Дополнительных параметрах''' поставить признаки "Меню всегда развернуто" и "Показывать подменю". Понятно, что это вопрос умолчаний, но в современных сайтах чаще используется развернутое меню, управляемое JS, а не как раньше - статическое индивидуальное меню для каждой страницы.

'''Господа разработчики''', может, пора уже облегчить жизнь редакторам сайтов, и изменить настройки? Пусть у всех страниц эти признаки будут по умолчанию включены, как вы считаете?

Полюбовавшись структурой полученного массива, можем теперь вывести нормальное меню сайта:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
?>
<header>
<nav class="navbar navbar-expand-lg navbar-light bg-light">
<a class="navbar-brand" href="/">Логотип</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>

<div class="collapse navbar-collapse" id="navbarSupportedContent">
<ul class="navbar-nav mr-auto">
<?php
foreach ($menuTree['void:lines'] as $item) {
$dropdown = !empty($item['items']['nodes:item']);
$active = !empty($item['attribute:status']);
if (isset($item['link']) && isset($item['name'])) {
if ($dropdown) {
?>
<li class="nav-item dropdown <?=$active?'active':''?>">
<a class="nav-link dropdown-toggle" href="<?= $item['link'] ?>" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><?= $item['name'] ?></a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
<?php
foreach ($item['items']['nodes:item'] as $sub) {
if (isset($sub['link']) && isset($sub['name'])) {
?>
<a class="dropdown-item" href="<?= $sub['link'] ?>"><?= $sub['name'] ?></a>
<?php
}
}
?>
</div>
</li>
<?php
} else {
?>
<li class="nav-item <?=$active?'active':''?>">
<a class="nav-link" href="<?= $item['link'] ?>"><?= $item['name'] ?></a>
</li>
<?php
}
}
}
?>
</ul>
</div>
</nav>
</header>
</syntaxhighlight>

В этом виде сайт уже почти настоящий. На страницах выводится то, что перед этим мы закинули через админку. Но хотелось бы иметь возможность вносить правки прямо на сайте. UMI CMS дает такую возможность, её надо просто [[Добавление возможности Edit-in-place|внести в наш шаблон]].

Создание "правильного" шаблона для сайта

2020-11-05T19:58:47Z

Olga:

Для компактности HTML кода буду использовать библиотеку Bootstrap4 - пользуйтесь своими любимыми фреймворками, если не нравится. Итак, сделаем код нашего шаблона несколько более полным:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<!DOCTYPE html>
<html>
<head>
<base href="/templates/default/">
<title><?= $page->title ?></title>
<meta charset="utf-8">
<meta name="description" content="<?= $page->description ?>">
<meta name="keywords" content="<?= $page->keywords ?>">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
</head>
<body>
<header>
</header>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<p><?= $page->content ?></p>
</div>
</div>
</div>
</section>
</main>
<footer>
</footer>

<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

В <head> добавили тэг <base ...>, потому что в дальнейшем все, что касается конкретного сайта, планируем хранить в папке конкретного шаблона, в нашем случае default. UMI CMS считает папку шаблона корневой директорией сайта, но это не распространяется на стили, скрипты и картинки.

Теперь главная страница сайта приобрела более "причёсанный" вид:

[[Файл:Screenshot 2020-10-29 Главная.png|обрамить|без]]

Заметим, что Title у страницы пустой, что не слишком хорошо. Можно прописывать это поле для каждой страницы. Но есть способ получше.

== Настраиваем Title и другие SEO-параметры ==

В шаблоне меняем строки заголовка, описания и ключевых слов на:

<syntaxhighlight lang="html">
<title><?= $this->escape($variables['title']) ?></title>
<meta name="description" content="<?= $variables['meta']['description'] ?>">
<meta name="keywords" content="<?= $variables['meta']['keywords'] ?>">
</syntaxhighlight>

и видим теперь заголовок <title>UMI.CMS - Страница 1</title>. Нам "UMI.CMS - " ни разу не нужно. Чтобы настроить параметры по умолчанию, в модулях (под бабочкой) находим раздел SEO, в нем справа вверху видим ссылку "Настройка модуля", жмём и настраиваем, там всё просто. Заменяю "UMI.CMS - " на "Демонстрационный сайт - ".

Чем отличается от прежнего варианта шаблона? Тем, что мы не выводим тупо поле из данных конкретной страницы, а позволяем CMS сформировать для нас эти параметры, используя настройки по умолчанию.

== Делим шаблон на части ==

Чтобы не мучиться с длинной простынёй кода, существует хорошая практика делить его на разумные фрагменты. Скажем, сразу хочется выделить <head>, <header> и <footer>.

В директории /templates/default/php/ создаём поддиректорию layout, а в ней файлы наших фрагментов:

* head.phtml
* header.phtml
* main.phtml
* footer.phtml

Помещаем в эти файлы фрагменты кода шаблонов, например, head.phtml будет выглядеть вот так:

<syntaxhighlight lang="html">
<head>
<base href="/templates/default/">
<title><?= $variables['title'] ?></title>
<meta charset="utf-8">
<meta name="description" content="<?= $variables['meta']['description'] ?>">
<meta name="keywords" content="<?= $variables['meta']['keywords'] ?>">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
</head>
</syntaxhighlight>

А main.phtml вот так:

<syntaxhighlight lang="html">
<?php
$page = $variables['page'];
?>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<p><?= $page->content ?></p>
</div>
</div>
</div>
</section>
</main>
</syntaxhighlight>

Теперь в шаблоне можно просто подключить эти фрагменты:

<syntaxhighlight lang="html">
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Заметим, что в качестве первого параметра при вызове метода render() мы передаем массив $variables конкретной страницы. Второй параметр - это адрес шаблона относительно папки php и без расшмрения ".phtml". Поэтому делать у файлов шаблона именно такое расширение - '''обязательно'''! Иначе не найдет.

== Добавляем меню ==

Выше мы использовали волшебную переменную $this, но для вызова только одного метода - render(). А какие еще методы нам доступны?

Полный список был бы весьма желателен. Но если кратко - все публичные методы модуля '''content''', их описание и код можно посмотреть в /classes/components/content/class.php и /classes/components/content/macros.php, а также системные и сервисные методы, наследуемые этими классами. Методы класса можно использовать непосредственно, макросы - при помощи метода macros().

Нам для сайта надо получить "дерево" меню. Для этого в файл header.phtml добавляем код:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
var_dump($menuTree);
?>
<header>
</header>
</syntaxhighlight>

Первый параметр метода macros() - название модуля, второй - название метода, третий - параметры, передаваемые методу. Список параметров можно посмотреть в коде метода, все макросы хорошо документированы комментариями. В данном случае используем:

* шаблон не задан (шаблон задается в других шаблонизаторах, в PHP не работает)
* 2 уровня вложенности (у нас пока один, но можем потом добавить)
* начиная от корня сайта (можно указать id страницы, и тогда "дерево" будет построено от неё)
* выдавать признак, что есть дочерние страницы
* id текущей страницы передаем, чтобы в результате этот пункт был выделен как активный.

Чтобы изучить возможность добавления второго уровня, добавим вложенную страницу внутрь нашей "Страницы 1". Для этого с разделе "Структура" сайта ставим галочку рядом со "Страница 1" и нажимаем плюс в меню. Назовем ее "Страница 3" и page3 в качестве псевдостатического адреса. Обновляем страницу в браузере - в массиве $menuTree ничего не поменялось!!!

Это очередная засада UMI CMS. Чтобы используемый нами макрос выдавал вложенные страницы, надо в данном случае на "Странице 1" в '''Дополнительных параметрах''' поставить признаки "Меню всегда развернуто" и "Показывать подменю". Понятно, что это вопрос умолчаний, но в современных сайтах чаще используется развернутое меню, управляемое JS, а не как раньше - статическое индивидуальное меню для каждой страницы.

'''Господа разработчики''', может, пора уже облегчить жизнь редакторам сайтов, и изменить настройки? Пусть у всех страниц эти признаки будут по умолчанию включены, как вы считаете?

Полюбовавшись структурой полученного массива, можем теперь вывести нормальное меню сайта:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
?>
<header>
<nav class="navbar navbar-expand-lg navbar-light bg-light">
<a class="navbar-brand" href="/">Логотип</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>

<div class="collapse navbar-collapse" id="navbarSupportedContent">
<ul class="navbar-nav mr-auto">
<?php
foreach ($menuTree['void:lines'] as $item) {
$dropdown = !empty($item['items']['nodes:item']);
$active = !empty($item['attribute:status']);
if (isset($item['link']) && isset($item['name'])) {
if ($dropdown) {
?>
<li class="nav-item dropdown <?=$active?'active':''?>">
<a class="nav-link dropdown-toggle" href="<?= $item['link'] ?>" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><?= $item['name'] ?></a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
<?php
foreach ($item['items']['nodes:item'] as $sub) {
if (isset($sub['link']) && isset($sub['name'])) {
?>
<a class="dropdown-item" href="<?= $sub['link'] ?>"><?= $sub['name'] ?></a>
<?php
}
}
?>
</div>
</li>
<?php
} else {
?>
<li class="nav-item <?=$active?'active':''?>">
<a class="nav-link" href="<?= $item['link'] ?>"><?= $item['name'] ?></a>
</li>
<?php
}
}
}
?>
</ul>
</div>
</nav>
</header>
</syntaxhighlight>

В этом виде сайт уже почти настоящий. На страницах выводится то, что перед этим мы закинули через админку. Но хотелось бы иметь возможность вносить правки прямо на сайте. UMI CMS дает такую возможность, её надо просто [[Добавление возможности Edit-in-place|внести в наш шаблон]].

Расширение функциональности модулей

2020-11-05T19:48:39Z

Olga: /* Получение блоков для главной страницы */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

Даже на этих примерах видно, насколько наглядней становится код шаблонов. Конечно, по сути это все равно обращение к базе в процессе рендеринга шаблона. Но выглядит лучше, и код обращений собран в одном файле.

== Вместо заключения ==

За рамками этой инструкции остались события, это довольно большая тема, и, к счастью, [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/sobytijnaya_model_umicms/ хорошо документированная].

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

Надеюсь, инструкция помогла на примерах понять архитектуру UMI CMS и принципы построения новых элементов. Самое время [[Что дальше?|перейти к практике]]!

Расширение функциональности модулей

2020-11-05T19:28:43Z

Olga: /* Получение блоков для главной страницы */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

Даже на этих примерах видно, насколько наглядней становится код шаблонов. Конечно, по сути это все равно обращение к базе в процессе рендеринга шаблона. Но выглядит лучше, и код обращений собран в одном файле.

Расширение функциональности модулей

2020-11-05T19:14:41Z

Olga: /* Получение блоков для главной страницы */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

Даже на этих примерах видно, насколько наглядней становится код шаблонов.

Расширение функциональности модулей

2020-11-05T19:08:08Z

Olga: /* Собственный класс сайта */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

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

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

Расширение функциональности модулей

2020-11-05T19:04:15Z

Olga: /* Вызов метода из "чужого" шаблона */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится. Не знаю, кому и зачем это может понадобиться, разве только чтобы в дальнейшем получше запутать себя и коллег.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

Поскольку extensions - это массив, понятно, что таких классов расширений можно добавить сколько угодно. Но нам хватит и одного.

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

Расширение функциональности модулей

2020-11-05T19:01:14Z

Olga: /* Добавление разрешения на выполнение метода */

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight lang="php">
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<syntaxhighlight lang="php">
$line_arr['attribute:anons'] = $element->anons;
</syntaxhighlight>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<syntaxhighlight lang="php">
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</syntaxhighlight>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<syntaxhighlight lang="php">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</syntaxhighlight>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<syntaxhighlight lang="php">
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</syntaxhighlight>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<syntaxhighlight lang="php">
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</syntaxhighlight>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<syntaxhighlight lang="php">
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</syntaxhighlight>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобится добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<syntaxhighlight lang="php">
<?php
$permissions['view'][] = 'newslist';
</syntaxhighlight>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</syntaxhighlight>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<syntaxhighlight lang="php">
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</syntaxhighlight>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

Поскольку extensions - это массив, понятно, что таких классов расширений можно добавить сколько угодно. Но нам хватит и одного.

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<syntaxhighlight lang="php">
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</syntaxhighlight>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<syntaxhighlight lang="php">
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<syntaxhighlight lang="php">
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</syntaxhighlight>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<syntaxhighlight lang="php">
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</syntaxhighlight>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<syntaxhighlight lang="php">
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</syntaxhighlight>

В результате код content/home/index.phtml станет вполне приличным:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

Другие модули системы

2020-11-05T18:48:16Z

Olga: /* Шаблоны для других модулей */

До сих пор на нашем сайте использовался только модуль content. Попробуем немного расширить функциональность сайта.

== Новости на сайте ==

Итак, жмём на бабочку и выбираем раздел "Новости". Новостей, понятно, пока нет, но есть кнопка добавления:

[[Файл:Screenshot 2020-11-02 UMI CMS - Новости и ленты.png|обрамить|без]]

Добавляем ленту новостей:

[[Файл:Screenshot 2 UMI CMS - Добавление ленты новостей.png|обрамить|без]]

Не забываем поставить признак видимости в меню. И наша лента появилась в списке. Что особенно приятно, она же появилась и в структуре:

[[Файл:Screenshot 2020-11-02 UMI CMS - Структура сайта.png|обрамить|без]]

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

[[Файл:Screenshot 2020-11-02 Демонстрационный сайт - Новости.png|обрамить|без]]

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

== Шаблоны для других модулей ==

В рамках одного шаблона сайта можно для каждого модуля подключать свой фрагмент. Сделать это очень просто. Достаточно в файле main.phtml вместо кода

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<div umi:element-id="<?= $page->id ?>" umi:field-name="content" umi:empty="<?= $this->translate('empty_page_content') ?>"><?= $page->content ?></div>
</div>
</div>
</div>
</section>
</main>
</syntaxhighlight>

написать:

<syntaxhighlight lang="php">
<main>
<?= $this->render($variables, "{$variables['module']}/{$variables['method']}") ?>

</main>
</syntaxhighlight>

Код, который раньше был в main.phtml, перенести в файл content.phtml, который создать в директории content/ в папке php нашего шаблона:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<div umi:element-id="<?= $page->id ?>" umi:field-name="content" umi:empty="<?= $this->translate('empty_page_content') ?>"><?= $page->content ?></dib>
</div>
</div>
</div>
</section>
</syntaxhighlight>

и создать также файл rubric.phtml в директории news/ в той же папке php:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<?php
var_dump($variables);
?>
</div>
</div>
</div>
</section>
</syntaxhighlight>

Если снова вывести массив $variables, увидим, что там есть название модуля и метода, который этот массив формирует. То есть мы фактически для каждого модуля нашей системы должны создать свой фрагмент кода, который бы его отображал. А строка <?= $this->render($variables, "{$variables['module']}/{$variables['method']}") ?> этот фрагмент подключит.

Почему список новостей выводится методом rubric, а не list? Видимо, чисто исторически.

Смотрим на выведенный массив $variables - и не видим никаких отличий! Что в общем, логично, новостей-то пока нет.

== Добавляем новости ==

В разделе "Новости" админки ставим галку рядом с новостями, и нажимаем появившуюся как по волшебству кнопку:

[[Файл:Screenshot 3 UMI CMS - Новости и ленты.png|обрамить|без]]

Заполняем открывшуюся форму:

[[Файл:Screenshot 2020-11-02 UMI CMS - Добавление новости.png|обрамить|без]]

Добавим 2 новости, чтобы было не очень пусто. Кстати, можно добавлять новости не только в соответствующем разделе админки, но и в разделе "Структура", точно так же, поставив галку перед разделом "Новости" и нажав плюс.

Когда обновляем страницу новостей, то видим, что в массиве $variables опять ничего не поменялось!!! Казалось бы, метод rubric должен нам вернуть список последних новостей, но он этого не делает. Не знаю, как других, меня это здорово дезориентирует: несмотря на то, что модуль другой, по сути получаем ту же контентную страницу.

Правда, мы можем использовать методы и макросы модуля.

== Шаблон для списка новостей ==

Меняем код нашего фрагмента rubric.phtml как-то так:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
$newsList = $this->macros('news', 'lastlist', [$variables['id']]);
var_dump($newsList);
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<ul class="list-group">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
</li>
<?php
endforeach;
endif;
?>
</ul>
</div>
</div>
</div>
</section>
</syntaxhighlight>

Здесь мы использовали макрос lastlist модуля news, который вернул нам массив, одним из элементов которого является список новостей. Другие элементы содержат вспомогательные параметры для организации списка, в частности, количество новостей на странице (настраивается в админке в "Настройках модуля"). Можно потом использовать для организации постранички (ненавижу термин "пагинация").

Строчку var_dump($newsList); можем убрать. Получилось даже красиво. Жмем на ссылу - и получаем ошибку!

[[Файл:Screenshot 2020-11-02 Неперехваченное исключение.png|без]]

Что вполне понятно, ведь мы не создали шаблон для отображения конкретной новости.

== Шаблон для текста новости ==

Создадим в папке php в разделе news файл item.phtml, о котором и упоминалось в тексте ошибки:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
var_dump($variables);
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<em umi:element-id="<?= $page->id ?>" umi:field-name="publish_time" umi:empty="<?= $this->translate('empty_publish_time') ?>"><?= $page->publish_time ?></em>
</div>
<div class="col-12">
<div umi:element-id="<?= $page->anons ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_anons') ?>"><?= $page->anons ?></div><hr />
</div>
<div class="col-12">
<div umi:element-id="<?= $page->id ?>" umi:field-name="content" umi:empty="<?= $this->translate('empty_page_content') ?>"><?= $page->content ?></div>
</div>
</div>
</div>
</section>
</syntaxhighlight>

И что же мы видим? В массиве $variables всё та же контентная страница, однако все поля, характерные для новости, в объекте присутствуют, хоть и не видны. Заметим, что дата получилась в формате umiDate, судя по всему, это внутреннее представление базы данных, для преобразования её в нужный формат можно воспользоваться [http://api.docs.umi-cms.ru/spravochnik_po_klassam_yadra_umicms/utilitarnye_klassy/umidate/ соответствующими методами]. Макрос 'lastlist' списка новостей ранее вернул дату в timestump. Вот так оно тут всё неожиданно...

== Шаблон для 404 ==

Теперь наберем в браузере адрес http://umi.example.com/abrakadabra - что получилось? Конечно, ошибка!

[[Файл:Screenshot 3 Неперехваченное исключение.png|без]]

Зато понятно, как её исправить - надо в php/content/ создать файл notfound.phtml, например, вот такой:

<syntaxhighlight lang="php">
<?php
var_dump($variables);
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $variables['header'] ?></h1>
</div>
</div>
</div>
</section>
</syntaxhighlight>

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

Вообще удобно сделать страницу 404 прямо на сайте, чтобы была возможность править контент в админке, а не в шаблоне. Для этого можно создать такую страницу, сделать её скрытой, в настройках сайта добавить поле типа "Ссылка на дерево", указать в этом поле адрес страницы 404, а в этом шаблоне брать оттуда контент. Но оставлю это для [[404 страница|отдельного упражнения]].

== Какие вообще нужны шаблоны? ==

В первую очередь нужны шаблоны модулей, используемых на сайте. В зависимости от редакции набор модулей разный, но, как правило нужны:

* content/
** content/content.phtml
** content/nofound.phtml
* news/
** news/rubric.phtml
** news/item.phtml
** news/subject.phtml - если использовать категории новостей
* users/ - довольно большой пакет шаблонов с формами регистрации и авторизации, которых мы пока не касались.
** users/registrate.phtml
** users/registrate_done.phtml
** users/activate.phtml
** users/login.phtml
** users/login_do.phtml
** users/logout.phtml
** users/forget.phtml
** users/forget_do.phtml
* search/ - если использовать поиск по сайту
** search/result.phtml
** search/search_do.phtml

И, наконец, хотелось бы сделать отдельный шаблон для главной страницы сайта. Но это лучше [[Шаблон для главной страницы|выделить в отдельную тему]].

Шаблон для главной страницы

2020-11-05T15:25:08Z

Olga:

Как правило, стартовая страница сайта отличается от остальных. Как отразить эту особенность в нашем шаблоне?

Вообще-то очень просто. В массиве $variables есть элемент 'is-default', который мы можем проверить. И если он true, то подтягиваем шаблон главной. Если нет - страницы нужного модуля. Вставим эту проверку в файл main.phtml:

<syntaxhighlight lang="php">
<main>
<?php
if ($variables['is-default']) echo $this->render($variables, "content/home/index");
else echo $this->render($variables, "{$variables['module']}/{$variables['method']}");
?>
</main>
</syntaxhighlight>

В объекте $variables['page'] тоже есть такое свойство, но получить его невозможно. Оно, конечно, private. Всегда будет false.

И надо создать в папке php фрагмент шаблона content/home/index.phtml, который подключаем. Для начала пусть будет просто контентная страница:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<div umi:element-id="<?= $page->id ?>" umi:field-name="content" umi:empty="<?= $this->translate('empty_page_content') ?>"><?= $page->content ?></div>
</div>
</div>
</div>
</section>
</syntaxhighlight>

== Добавление блоков ==

Обычно на главную страницу стараются запихнуть весь контент сайта. Наверно потому, что не надеются, что пользователь настолько заинтересуется, что пройдет куда-то ещё.

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

[[Файл:Screenshot 5 UMI CMS - Редактирование типа данных.png|обрамить|без]]

Чтобы к этому не возвращаться, добавим все поля, которые хотели, в частности, ссылки на дерево для новостей и 404 ошибки, а также название компании. Новости уже есть, осталось в настройках выбрать нужный раздел, а вот 404 страницы нет, [[404 страница|создадим её]].

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

=== Разбиваем шаблон на блоки ===

Чтобы не тащить простыню кода, разделим content/home/index.phtml на фрагменты по блокам:

<syntaxhighlight lang="php">
<?php
echo $this->render($variables, "content/home/intro");
echo $this->render($variables, "content/home/news");
echo $this->render($variables, "content/home/contacts");
?>
</syntaxhighlight>

=== Вводный текст ===

Фрагмент content/home/intro.phtml останется аналогом контентной страницы:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<div umi:element-id="<?= $page->id ?>" umi:field-name="content" umi:empty="<?= $this->translate('empty_page_content') ?>"><?= $page->content ?></div>
</div>
</div>
</div>
</section>
</syntaxhighlight>

=== Новости ===

Фрагмент для новостей content/home/news.phtml:

<syntaxhighlight lang="php">
<?php
$newsListSettings = $variables['settings']->newslist;
if (!empty($newsListSettings)) $newsPageId = $newsListSettings[0]->id;
else $newsPageId = false;
$newsList = $this->macros('news', 'lastlist', [$newsPageId]);
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h2>Что нового?</h2>
</div>
<div class="col-12">
<ul class="list-group">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
</li>
<?php
endforeach;
endif;
?>
</ul>
</div>
</div>
</div>
</section>
</syntaxhighlight>

=== Контакты ===

Фрагмент для контактов content/home/contacts.phtml:

<syntaxhighlight lang="php">
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h2>Контакты</h2>
</div>
<div class="col-12">
<div class="row">
<div class="col-6">
<h3><?= $this->translate('address') ?></h3>
</div>
<div class="col-6">
<h3 umi:object-id="<?= $variables['settings']->id ?>" umi:field-name="address" umi:empty="<?= $this->translate('empty_address') ?>"><?= $variables['settings']->address ?></h3>
</div>
</div>
<div class="row">
<div class="col-6">
<h3><?= $this->translate('phone') ?></h3>
</div>
<div class="col-6">
<h3 umi:object-id="<?= $variables['settings']->id ?>" umi:field-name="phone" umi:empty="<?= $this->translate('empty_phone') ?>"><?= $variables['settings']->phone ?></h3>
</div>
</div>
</div>
</div>
</div>
</section>
</syntaxhighlight>

Не забываем пополнять файлы i18n/i18n.ru.php и i18n/i18n.en.php новыми языковыми константами, которые появляются в шаблонах нашего сайта. Также добавили разметку для Edit-in-place, и теперь можем внести адрес и телефон прямо на "морде" сайта.

== Организация блоков на главной странице ==

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

Кто-то из новых разработчиков задал аналогичный вопрос в группе, получил много ответов, которые его не устроили по причине сложной реализации. Что он сделал после этого? У него была верстка, вся такая из разноцветных блоков. Он в "Шаблонах данных" добавил дочерний шаблон в "Раздел сайта", назвал его "Главная", и добавил туда кучу полей типа HTML-текст с кодом section1, section2 и т.д. После чего скопировал код соответствующих блоков из верстки, и вставил в эти поля. Шаблон главной у него при этом получился, видимо, такой:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<?= ($page->section1)?$page->section1:'' ?>
<?= ($page->section2)?$page->section2:'' ?>
...
</syntaxhighlight>

А что, так можно было??? Конечно, можно. Но некрасиво, и нельзя поменять блоки местами.

Мне больше нравится другой способ. Создаём в разделе главной страницы несколько подразделов, например, вот так:

[[Файл:Screenshot 22 UMI CMS - Структура сайта.png|обрамить|без]]

Псевдостатические адреса задаём intro, news и contacts соответственно. После чего шаблон главной страницы приобретает вид:

<syntaxhighlight lang="php">
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
$resourcesDir = cmsController::getInstance()->getResourcesDirectory();

foreach ($blocks as $page) {
$page['settings'] = $variables['settings'];
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</syntaxhighlight>

Кода получилось немного больше, но в следующей статье исправим этот недостаток. Подключили класс umiHierarchy, выбрали все дочерние страницы, выбрали соответствующие объекты и наполнили массив $blocks. Да, еще добыли путь к корневой папке нашего шаблона, чтобы не задавать статикой. В качестве данных передаём в render() массив $page, куда добавили $variables['settings'], чтобы не потерять настройки. Вообще это лучше делать по-другому, но об этом чуть позже.

Теперь надо поменять немного шаблоны блоков, чтобы брать оттуда контент соответствующих подразделов.

=== Вступительный текст ===

В метод render() мы уже передаем не $variables, а элемент массива, содержащий данные подраздела. Здесь название массива по-прежнему будет $variables, но содержимое будет уже другим. Поэтому:

<syntaxhighlight lang="php">
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $variables['id'] ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $variables['h1'] ?></h1>
</div>
<div class="col-12">
<div umi:element-id="<?= $variables['id'] ?>" umi:field-name="content" umi:empty="<?= $this->translate('empty_page_content') ?>"><?= $variables['content'] ?></div>
</div>
</div>
</div>
</section>
</syntaxhighlight>

=== Остальные шаблоны ===

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

<syntaxhighlight lang="php">
<h2 umi:element-id="<?= $variables['id'] ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $variables['h1'] ?></h2>
</syntaxhighlight>

=== В чем преимущество? ===

Редактор сайта получает больше возможностей для изменения контента главной, можно использовать Edit-in-place для исправления заголовков блоков, можно менять блоки местами. Попробуйте и убедитесь.

Вообще я обычно использую 2 уровня вложенности подразделов, чтобы внутри каждого из блоков отображать список дочерних блоков. Это очень удобно для программирования современных сайтов, где есть блоки "Наши преимущества", "Наша команда" и "Отзывы наших клиентов", содержащие свои списки данных. Понятно, что кроме заголовка и контента можно добавлять картинки, пиктограммы, анонсы - всё, что только может понадобиться.

Но есть и недостаток - много кода в шаблоне. Хорошим тоном в UMI считается, если в шаблоне вообще не используется API. Это правильно и с точки зрения MVC. Поэтому пора перейти к [[Расширение функциональности модулей|созданию кастомных методов и функций]].

Другие модули системы

2020-11-05T15:23:15Z

Olga: /* Шаблоны для других модулей */

До сих пор на нашем сайте использовался только модуль content. Попробуем немного расширить функциональность сайта.

== Новости на сайте ==

Итак, жмём на бабочку и выбираем раздел "Новости". Новостей, понятно, пока нет, но есть кнопка добавления:

[[Файл:Screenshot 2020-11-02 UMI CMS - Новости и ленты.png|обрамить|без]]

Добавляем ленту новостей:

[[Файл:Screenshot 2 UMI CMS - Добавление ленты новостей.png|обрамить|без]]

Не забываем поставить признак видимости в меню. И наша лента появилась в списке. Что особенно приятно, она же появилась и в структуре:

[[Файл:Screenshot 2020-11-02 UMI CMS - Структура сайта.png|обрамить|без]]

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

[[Файл:Screenshot 2020-11-02 Демонстрационный сайт - Новости.png|обрамить|без]]

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

== Шаблоны для других модулей ==

В рамках одного шаблона сайта можно для каждого модуля подключать свой фрагмент. Сделать это очень просто. Достаточно в файле main.phtml вместо кода

<syntaxhighlight lang="html">
<?php
$page = $variables['page'];
?>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<div umi:element-id="<?= $page->id ?>" umi:field-name="content" umi:empty="<?= $this->translate('empty_page_content') ?>"><?= $page->content ?></div>
</div>
</div>
</div>
</section>
</main>
</syntaxhighlight>

написать:

<syntaxhighlight lang="php">
<main>
<?= $this->render($variables, "{$variables['module']}/{$variables['method']}") ?>

</main>
</syntaxhighlight>

Код, который раньше был в main.phtml, перенести в файл content.phtml, который создать в директории content/ в папке php нашего шаблона:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<div umi:element-id="<?= $page->id ?>" umi:field-name="content" umi:empty="<?= $this->translate('empty_page_content') ?>"><?= $page->content ?></dib>
</div>
</div>
</div>
</section>
</syntaxhighlight>

и создать также файл rubric.phtml в директории news/ в той же папке php:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<?php
var_dump($variables);
?>
</div>
</div>
</div>
</section>
</syntaxhighlight>

Если снова вывести массив $variables, увидим, что там есть название модуля и метода, который этот массив формирует. То есть мы фактически для каждого модуля нашей системы должны создать свой фрагмент кода, который бы его отображал. А строка <?= $this->render($variables, "{$variables['module']}/{$variables['method']}") ?> этот фрагмент подключит.

Почему список новостей выводится методом rubric, а не list? Видимо, чисто исторически.

Смотрим на выведенный массив $variables - и не видим никаких отличий! Что в общем, логично, новостей-то пока нет.

== Добавляем новости ==

В разделе "Новости" админки ставим галку рядом с новостями, и нажимаем появившуюся как по волшебству кнопку:

[[Файл:Screenshot 3 UMI CMS - Новости и ленты.png|обрамить|без]]

Заполняем открывшуюся форму:

[[Файл:Screenshot 2020-11-02 UMI CMS - Добавление новости.png|обрамить|без]]

Добавим 2 новости, чтобы было не очень пусто. Кстати, можно добавлять новости не только в соответствующем разделе админки, но и в разделе "Структура", точно так же, поставив галку перед разделом "Новости" и нажав плюс.

Когда обновляем страницу новостей, то видим, что в массиве $variables опять ничего не поменялось!!! Казалось бы, метод rubric должен нам вернуть список последних новостей, но он этого не делает. Не знаю, как других, меня это здорово дезориентирует: несмотря на то, что модуль другой, по сути получаем ту же контентную страницу.

Правда, мы можем использовать методы и макросы модуля.

== Шаблон для списка новостей ==

Меняем код нашего фрагмента rubric.phtml как-то так:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
$newsList = $this->macros('news', 'lastlist', [$variables['id']]);
var_dump($newsList);
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<ul class="list-group">
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
</li>
<?php
endforeach;
endif;
?>
</ul>
</div>
</div>
</div>
</section>
</syntaxhighlight>

Здесь мы использовали макрос lastlist модуля news, который вернул нам массив, одним из элементов которого является список новостей. Другие элементы содержат вспомогательные параметры для организации списка, в частности, количество новостей на странице (настраивается в админке в "Настройках модуля"). Можно потом использовать для организации постранички (ненавижу термин "пагинация").

Строчку var_dump($newsList); можем убрать. Получилось даже красиво. Жмем на ссылу - и получаем ошибку!

[[Файл:Screenshot 2020-11-02 Неперехваченное исключение.png|без]]

Что вполне понятно, ведь мы не создали шаблон для отображения конкретной новости.

== Шаблон для текста новости ==

Создадим в папке php в разделе news файл item.phtml, о котором и упоминалось в тексте ошибки:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
var_dump($variables);
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1 umi:element-id="<?= $page->id ?>" umi:field-name="h1" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<em umi:element-id="<?= $page->id ?>" umi:field-name="publish_time" umi:empty="<?= $this->translate('empty_publish_time') ?>"><?= $page->publish_time ?></em>
</div>
<div class="col-12">
<div umi:element-id="<?= $page->anons ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_anons') ?>"><?= $page->anons ?></div><hr />
</div>
<div class="col-12">
<div umi:element-id="<?= $page->id ?>" umi:field-name="content" umi:empty="<?= $this->translate('empty_page_content') ?>"><?= $page->content ?></div>
</div>
</div>
</div>
</section>
</syntaxhighlight>

И что же мы видим? В массиве $variables всё та же контентная страница, однако все поля, характерные для новости, в объекте присутствуют, хоть и не видны. Заметим, что дата получилась в формате umiDate, судя по всему, это внутреннее представление базы данных, для преобразования её в нужный формат можно воспользоваться [http://api.docs.umi-cms.ru/spravochnik_po_klassam_yadra_umicms/utilitarnye_klassy/umidate/ соответствующими методами]. Макрос 'lastlist' списка новостей ранее вернул дату в timestump. Вот так оно тут всё неожиданно...

== Шаблон для 404 ==

Теперь наберем в браузере адрес http://umi.example.com/abrakadabra - что получилось? Конечно, ошибка!

[[Файл:Screenshot 3 Неперехваченное исключение.png|без]]

Зато понятно, как её исправить - надо в php/content/ создать файл notfound.phtml, например, вот такой:

<syntaxhighlight lang="php">
<?php
var_dump($variables);
?>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $variables['header'] ?></h1>
</div>
</div>
</div>
</section>
</syntaxhighlight>

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

Вообще удобно сделать страницу 404 прямо на сайте, чтобы была возможность править контент в админке, а не в шаблоне. Для этого можно создать такую страницу, сделать её скрытой, в настройках сайта добавить поле типа "Ссылка на дерево", указать в этом поле адрес страницы 404, а в этом шаблоне брать оттуда контент. Но оставлю это для [[404 страница|отдельного упражнения]].

== Какие вообще нужны шаблоны? ==

В первую очередь нужны шаблоны модулей, используемых на сайте. В зависимости от редакции набор модулей разный, но, как правило нужны:

* content/
** content/content.phtml
** content/nofound.phtml
* news/
** news/rubric.phtml
** news/item.phtml
** news/subject.phtml - если использовать категории новостей
* users/ - довольно большой пакет шаблонов с формами регистрации и авторизации, которых мы пока не касались.
** users/registrate.phtml
** users/registrate_done.phtml
** users/activate.phtml
** users/login.phtml
** users/login_do.phtml
** users/logout.phtml
** users/forget.phtml
** users/forget_do.phtml
* search/ - если использовать поиск по сайту
** search/result.phtml
** search/search_do.phtml

И, наконец, хотелось бы сделать отдельный шаблон для главной страницы сайта. Но это лучше [[Шаблон для главной страницы|выделить в отдельную тему]].

2020-11-05T15:13:43Z

Olga:

Для компактности HTML кода буду использовать библиотеку Bootstrap4 - пользуйтесь своими любимыми фреймворками, если не нравится. Итак, сделаем код нашего шаблона несколько более полным:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<!DOCTYPE html>
<html>
<head>
<base href="/templates/default/">
<title><?= $page->title ?></title>
<meta charset="utf-8">
<meta name="description" content="<?= $page->description ?>">
<meta name="keywords" content="<?= $page->keywords ?>">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
</head>
<body>
<header>
</header>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<p><?= $page->content ?></p>
</div>
</div>
</div>
</section>
</main>
<footer>
</footer>

<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

В <head> добавили тэг <base ...>, потому что в дальнейшем все, что касается конкретного сайта, планируем хранить в папке конкретного шаблона, в нашем случае default. UMI CMS считает папку шаблона корневой директорией сайта, но это не распространяется на стили, скрипты и картинки.

Теперь главная страница сайта приобрела более "причёсанный" вид:

[[Файл:Screenshot 2020-10-29 Главная.png|обрамить|без]]

Заметим, что Title у страницы пустой, что не слишком хорошо. Можно прописывать это поле для каждой страницы. Но есть способ получше.

== Настраиваем Title и другие SEO-параметры ==

В шаблоне меняем строки заголовка, описания и ключевых слов на:

<syntaxhighlight lang="php">
<title><?= $this->escape($variables['title']) ?></title>
<meta name="description" content="<?= $variables['meta']['description'] ?>">
<meta name="keywords" content="<?= $variables['meta']['keywords'] ?>">
</syntaxhighlight>

и видим теперь заголовок <title>UMI.CMS - Страница 1</title>. Нам "UMI.CMS - " ни разу не нужно. Чтобы настроить параметры по умолчанию, в модулях (под бабочкой) находим раздел SEO, в нем справа вверху видим ссылку "Настройка модуля", жмём и настраиваем, там всё просто. Заменяю "UMI.CMS - " на "Демонстрационный сайт - ".

Чем отличается от прежнего варианта шаблона? Тем, что мы не выводим тупо поле из данных конкретной страницы, а позволяем CMS сформировать для нас эти параметры, используя настройки по умолчанию.

== Делим шаблон на части ==

Чтобы не мучиться с длинной простынёй кода, существует хорошая практика делить его на разумные фрагменты. Скажем, сразу хочется выделить <head>, <header> и <footer>.

В директории /templates/default/php/ создаём поддиректорию layout, а в ней файлы наших фрагментов:

* head.phtml
* header.phtml
* main.phtml
* footer.phtml

Помещаем в эти файлы фрагменты кода шаблонов, например, head.phtml будет выглядеть вот так:

<syntaxhighlight lang="php">
<head>
<base href="/templates/default/">
<title><?= $variables['title'] ?></title>
<meta charset="utf-8">
<meta name="description" content="<?= $variables['meta']['description'] ?>">
<meta name="keywords" content="<?= $variables['meta']['keywords'] ?>">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
</head>
</syntaxhighlight>

А main.phtml вот так:

<syntaxhighlight lang="php">
<?php
$page = $variables['page'];
?>
<main>
<section>
<div class="container">
<div class="row">
<div class="col-12">
<h1><?= $page->h1 ?></h1>
</div>
<div class="col-12">
<p><?= $page->content ?></p>
</div>
</div>
</div>
</section>
</main>
</syntaxhighlight>

Теперь в шаблоне можно просто подключить эти фрагменты:

<syntaxhighlight lang="php">
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</syntaxhighlight>

Заметим, что в качестве первого параметра при вызове метода render() мы передаем массив $variables конкретной страницы. Второй параметр - это адрес шаблона относительно папки php и без расшмрения ".phtml". Поэтому делать у файлов шаблона именно такое расширение - '''обязательно'''! Иначе не найдет.

== Добавляем меню ==

Выше мы использовали волшебную переменную $this, но для вызова только одного метода - render(). А какие еще методы нам доступны?

Полный список был бы весьма желателен. Но если кратко - все публичные методы модуля '''content''', их описание и код можно посмотреть в /classes/components/content/class.php и /classes/components/content/macros.php, а также системные и сервисные методы, наследуемые этими классами. Методы класса можно использовать непосредственно, макросы - при помощи метода macros().

Нам для сайта надо получить "дерево" меню. Для этого в файл header.phtml добавляем код:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
var_dump($menuTree);
?>
<header>
</header>
</syntaxhighlight>

Первый параметр метода macros() - название модуля, второй - название метода, третий - параметры, передаваемые методу. Список параметров можно посмотреть в коде метода, все макросы хорошо документированы комментариями. В данном случае используем:

* шаблон не задан (шаблон задается в других шаблонизаторах, в PHP не работает)
* 2 уровня вложенности (у нас пока один, но можем потом добавить)
* начиная от корня сайта (можно указать id страницы, и тогда "дерево" будет построено от неё)
* выдавать признак, что есть дочерние страницы
* id текущей страницы передаем, чтобы в результате этот пункт был выделен как активный.

Чтобы изучить возможность добавления второго уровня, добавим вложенную страницу внутрь нашей "Страницы 1". Для этого с разделе "Структура" сайта ставим галочку рядом со "Страница 1" и нажимаем плюс в меню. Назовем ее "Страница 3" и page3 в качестве псевдостатического адреса. Обновляем страницу в браузере - в массиве $menuTree ничего не поменялось!!!

Это очередная засада UMI CMS. Чтобы используемый нами макрос выдавал вложенные страницы, надо в данном случае на "Странице 1" в '''Дополнительных параметрах''' поставить признаки "Меню всегда развернуто" и "Показывать подменю". Понятно, что это вопрос умолчаний, но в современных сайтах чаще используется развернутое меню, управляемое JS, а не как раньше - статическое индивидуальное меню для каждой страницы.

'''Господа разработчики''', может, пора уже облегчить жизнь редакторам сайтов, и изменить настройки? Пусть у всех страниц эти признаки будут по умолчанию включены, как вы считаете?

Полюбовавшись структурой полученного массива, можем теперь вывести нормальное меню сайта:

<syntaxhighlight lang="php">
<?php
$pageId = isset($variables['pageId'])?$variables['pageId']:0;
$menuTree = $this->macros('content', 'menu', [0, 2, 0, true, $pageId]);
?>
<header>
<nav class="navbar navbar-expand-lg navbar-light bg-light">
<a class="navbar-brand" href="/">Логотип</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>

<div class="collapse navbar-collapse" id="navbarSupportedContent">
<ul class="navbar-nav mr-auto">
<?php
foreach ($menuTree['void:lines'] as $item) {
$dropdown = !empty($item['items']['nodes:item']);
$active = !empty($item['attribute:status']);
if (isset($item['link']) && isset($item['name'])) {
if ($dropdown) {
?>
<li class="nav-item dropdown <?=$active?'active':''?>">
<a class="nav-link dropdown-toggle" href="<?= $item['link'] ?>" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><?= $item['name'] ?></a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
<?php
foreach ($item['items']['nodes:item'] as $sub) {
if (isset($sub['link']) && isset($sub['name'])) {
?>
<a class="dropdown-item" href="<?= $sub['link'] ?>"><?= $sub['name'] ?></a>
<?php
}
}
?>
</div>
</li>
<?php
} else {
?>
<li class="nav-item <?=$active?'active':''?>">
<a class="nav-link" href="<?= $item['link'] ?>"><?= $item['name'] ?></a>
</li>
<?php
}
}
}
?>
</ul>
</div>
</nav>
</header>
</syntaxhighlight>

В этом виде сайт уже почти настоящий. На страницах выводится то, что перед этим мы закинули через админку. Но хотелось бы иметь возможность вносить правки прямо на сайте. UMI CMS дает такую возможность, её надо просто [[Добавление возможности Edit-in-place|внести в наш шаблон]].

2020-11-05T14:22:08Z

Olga:

Некоторые методы UMI CMS оставляют желать лучшего. Например, метод lastlist модуля news не возвращает значение поля anons новости, который может понадобиться в списке новостей. Можно ли с этим что-то сделать?

== Кастомные методы стандартных модулей ==

Открываем директорию /classes/components/news и видим там файлы macros.php и customMacros.php. В файле macros.php находим функцию lastlist(), копируем её и целиком вставляем в customMacros.php после строки public $module;.

Находим там кусок кода:

<syntaxhighlight>
$line_arr = [];
$line_arr['attribute:id'] = $element_id;
$line_arr['node:name'] = $element->getName();
$line_arr['attribute:link'] = $umiLinksHelper->getLinkByParts($element);
$line_arr['xlink:href'] = 'upage://' . $element_id;
$line_arr['void:header'] = $lines_arr['name'] = $element->getName();
</syntaxhighlight>

Там и правда не добавляется анонс. Поэтому вставляем одну строчку:

<pre>
$line_arr['attribute:anons'] = $element->anons;
</pre>

Все эти ''node:'' и ''attribute:'' предназначены для других шаблонизаторов, но лучше их сохранить для общности.

Открываем главную страницу нашего сайта - и видим ошибку "Ошибка (Error): Class 'Service' not found"! Правда, с этим понятно, что делать, надо в начале файла customMacros.php вставить "use UmiCms\Service;", вот так:

<pre>
<?php
use UmiCms\Service;

/** Класс пользовательских макросов */
class NewsCustomMacros {

/** @var news $module */
public $module;
...
}

</pre>

Больше ошибок не возникнет, и теперь при вызове метода lastlist() получим также и элемент массива 'anons'. Если изменим в файле content/home/news.phtml код цикла вот так:

<pre>
<?php
if (!empty($newsList['items'])):
foreach ($newsList['items'] as $item):
?>
<li class="list-group-item">
<em><?= date("d.m.Y", $item['publish_time']) ?></em>
<a href="<?= $item['link'] ?>"><h3 umi:element-id="<?= $item['id'] ?>" umi:field-name="name" umi:empty="<?= $this->translate('empty_page_name') ?>"><?= $item['name'] ?></h3></a>
<div umi:element-id="<?= $item['id'] ?>" umi:field-name="anons" umi:empty="<?= $this->translate('empty_news_anons') ?>"><?= $item['anons'] ?></div>
</li>
<?php
endforeach;
endif;
?>
</pre>

то увидим также и текст анонсов. Можно просто набрать в браузере http://umi.example.com/udata://news/lastlist/7/.json и увидеть изменения.

Что будет, если внести исправления сразу в файл macros.php? Очевидно, что все исправления будут потеряны при очередном обновлении системы.

Сразу замечу, что переопределять стандартные методы - '''ОЧЕНЬ ДУРНАЯ ПРАКТИКА'''. Если с сайтом будет работать другой программист, ему придется потратить кучу сил и времени на поиск ошибки, ведь он будет уверен, что вызывается стандартный метод. Поэтому '''ВСЕГДА''', скопировав код стандартного метода, '''ПЕРЕИМЕНОВЫВАЙТЕ ЕГО'''! Пусть этот метод будет целиком и полностью кастомным, и это будет видно уже при вызове. И тогда возникает следующая задача - настройка разрешений.

=== Настройка разрешений для выполнения метода ===

Да, переопределение метода - нехороший поступок, но когда мы так делаем, автоматически избегаем множества проблем. Дело в том, что в UMI CMS есть сложная система разрешений, для каждого модуля существует собственный набор, посмотреть его можно в папке модуля в файле permissions.php.

Когда мы создаем метод с новым именем, то он не будет выполняться, т к отсутствует в файле permissions.php. Но это можно исправить, создав в той же папке модуля файл permissions.custom.php.

Предположим, по аналогии с методом lastlist() мы создали метод newslist(), куда внесли все необходимые нам изменения. Если посмотреть содержимое файла permissions.php, увидим, что это массив:

<pre>
/** Группы прав на функционал модуля */
$permissions = [
/** Права на просмотр новостей */
'view' => [
'lastlist',
'listlents',
'rubric',
/** ... и так далее, не буду приводить его целиком */
]
];
</pre>

По логике, нам надо добавить один элемент в массив $permissions['view'], поэтому в файле permissions.custom.php пишем:

<pre>
<?php
$permissions['view'][] = 'newslist';
</pre>

Интересный факт: даже если название метода содержит буквы с разной капитализацией, в этом массиве все нужно писать маленькими буквами. Не спрашивайте, почему.

Пока всё просто? Это только кажется. В каждом модуле структура и ключи массива разрешений разные, и в них нет никакой системы. Хорошо, если метод должен быть общедоступным, как правило, можно угадать, в какой именно массив его добавлять. Сложнее, если доступ можно давать только авторизоваанным пользователям, и то не всем. Так что - удачи!

=== Использование кастомного метода в шаблона ===

Теперь меняем в файле content/home/news.phtml имя метода:

<pre>
$newsList = $this->macros('news', 'newslist', [$newsPageId]);
</pre>

и увидим то, что планировали. И даже есть вызовем этот метод просто в строке URL, на пример, так:

http://umi.example.com/udata://news/newslist/7/.json

(где 7 - это id ленты новостей, на других сайтах может быть другой), то получим json-массив с элементом anons.

== Кастомные методы внутри шаблона ==

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

И что приятно, начиная с версии 2.8.5 системы [http://api.docs.umi-cms.ru/razrabotka_nestandartnogo_funkcionala/razrabotka_sobstvennyh_makrosov_i_modulej/novyj_format_rasshireniya_funkcionala/ это можно сделать]! Для этого создаем внутри нашего шаблона папку classes, внутри неё папку modules, в ней папку с именем модуля, например, news, а там - файл class.php, где создаем отдельный класс. Имя класса должно быть 'имямодуля_custom', а имена методов не должны совпадать с именами стандартных методов модуля. Таким образом, получим файл classes/modules/news/class.php с кодом:

<pre>
<?php

/** Класс пользовательских методов */
class news_custom extends def_module {

}
?>
</pre>

В этот файл можно добавлять свои методы, которые могут быть использованы в шаблоне при помощи вызова $this->macros('news', 'имя_метода', [массив_параметров_метода] ). Что приятно, в class.php уже не нужно подключать 'use UmiCms\Service;', его уже подключает def_module.

=== Добавление разрешения на выполнение метода ===

Тут тоже понадобиться добавлять разрешения. К счастью, для этого достаточно в той же директории classes/modules/news/ создать файл permissions.php, куда внести тот же код, что ранее использовали в permissions.custom.php:

<pre>
<?php
$permissions['view'][] = 'newslist';
</pre>

=== Создание кастомного метода ===

Перенесём наш метод newslist() из кастомных макросов в этот новый класс. Не буду приводить тут его код, он в точности тот же.

Из кастомных макросов этот метод можно убрать, можно также удалить файл /classes/components/news/permissions.custom.php, ведь мы уже добавили разрешения в классы шаблона. В нашем фрагменте шаблона content/home/news.phtml ничего не меняем.

Если набрать в браузере ту же ссылку http://umi.example.com/udata://news/newslist/7/.json (не забываем поменять id ленты новостей, это только у меня он 7), то увидим массив новостей с анонсом, да и на сайте все прекрасно выводится.

=== Создание кастомных событий внутри шаблона ===

До создания собственных событий ещё очень далеко. Просто для общности надо отметить, что события тоже можно создать внутри шаблона, в той же папке /classes/components/news/ в файле events.php.

=== Вызов метода из "чужого" шаблона ===

Шаблонов на сайте может быть несколько, и в одном шаблоне сайта получить доступ к методу из другого шаблона, вообще говоря, нельзя. Но есть хитрый хак. Если запрашивать данные, например, AJAXом через udata:, то можно в строке запроса в конце добавить параметр '?template_id={id шаблона}', и всё получится.

== Собственный класс сайта ==

До сих пор мы рассматривали очень правильный с точки зрения MVC путь создания своих методов. Однако есть более простой и быстрый, но немного менее "канонический" способ, доступный только для PHP-шаблонизатора. Это создание класса расширения шаблонизатора.

Для начала создадим в директории php папку library. В данном случае название может быть любым. А в ней файл PhpExtension.php с вот таким кодом:

<pre>
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

}
</pre>

Далее, открываем файл config.ini, который перед этим создали в папке шаблона, там уже есть настройки для "причёсывания" отдаваемых методами массивов, и добавляем туда 2 строчки:

<pre>
[php-templater]
extensions[] = "/templates/default/php/library/PhpExtension"
</pre>

'''Важно!''' Имя класса в принципе может быть любым, но имя файла, содержащего этот класс, а также путь к файлу, прописанный в конфиге, должны в точности его повторять, вплоть до капитализации.

Поскольку extensions - это массив, понятно, что таких классов расширений можно добавить сколько угодно. Но нам хватит и одного.

Все публичные методы этого класса теперь будут доступны в шаблоне при помощи волшебной переменной $this. Но лучше это посмотреть на примере.

=== Добавление глобальных переменных ===

Ранее мы сделали одну не очень красивую вещь - добавили полученные прямо в шаблоне настройки к массиву $variables, и вынуждены были и дальше передавать их в методе render(), чтобы не потерялись. Значительно лучше было бы создать какие-то глобальные переменные, которые были бы доступны в любом фрагменте нашего шаблона.

Итак, добавляем в наш класс расширения следующие функции:

<pre>
<?php

/** Сервисные классы, которые понадобятся для выполнения методов */
use UmiCms\Classes\System\Utils\Captcha\Strategies\GoogleRecaptcha;
use UmiCms\Service;

/** Расширение php шаблонизатора для шаблона default */
class PhpExtension extends ViewPhpExtension {

/**
* Инициализирует общие переменные для шаблонов.
* @param array $variables глобальные переменные запроса
*/
public function initializeCommonVariables($variables) {
$templateEngine = $this->getTemplateEngine();
$templateEngine->setCommonVar('domain', $variables['domain']);
$templateEngine->setCommonVar('lang', $variables['lang']);
$templateEngine->setCommonVar('settings', $this->requestSettingsContainer($variables));
}

/**
* Запрашивает актуальный объект настроек и возвращает его
* @param array $variables глобальные переменные запроса
* @return bool|iUmiObject
*/
public function requestSettingsContainer($variables) {
$set = new selector('objects');
$set->types('object-type')->name('umiSettings', 'settings');
$set->where('domain_id')->equals($variables['domain-id']);
$set->where('lang_id')->equals($variables['lang-id']);
$set->limit(0, 1);
$settings = $set->result();
if (is_array($settings)) return $settings[0];
return false;
}

}
</pre>

Здесь использовали методы базового класса ViewPhpExtension для работы с глобальными переменными. Вставим вызов метода initializeCommonVariables() в файл common.phtml:

<pre>
<?php
$this->initializeCommonVariables($variables);
?>
<!DOCTYPE html>
<html>
<?= $this->render($variables, 'layout/head') ?>
<body>
<?= $this->render($variables, 'layout/header') ?>
<?= $this->render($variables, 'layout/main') ?>
<?= $this->render($variables, 'layout/footer') ?>

<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
</body>
</html>
</pre>

Теперь для получения значения этих переменных в любом фрагменте шаблона достаточно написать $this->getCommonVar('имя переменной'). Например, файл footer.phtml приобретет следующий вид:

<pre>
<?php
$settings = $this->getCommonVar('settings');
?>
<footer>
<div class="container">
<span umi:object-id="<?= $settings->id ?>" umi:field-name="copyright"><?= $settings->copyright ?></span> <?= date("Y") ?>
</div>
</footer>
</pre>

Аналогичным образом меняем остальные фрагменты шаблона, где используются настройки. Теперь их не надо добавлять к массиву $variables.

=== Получение блоков для главной страницы ===

При помощи класса PhpExtension можем улучшить код ещё одного фрагмента - content/home/index.phtml. Добавляем в класс метод getHomePageBlocks():

<pre>
/**
* Возвращает информацию для главной страницы по блокам
* @param array $variables глобальные переменные запроса
* @return bool|array
*/
public function getHomePageBlocks($variables) {
$blocks = [];
$hierarchy = umiHierarchy::getInstance();
$children = $hierarchy->getChildrenTree($variables['pageId'], false, false, 1);
foreach ($children as $id => $val) {
$element = $hierarchy->getElement($id);
if ($element instanceof umiHierarchyElement) {
$blocks[$id]['id'] = $element->id;
$blocks[$id]['name'] = $element->name;
$blocks[$id]['h1'] = $element->h1;
$blocks[$id]['altName'] = $element->altName;
$blocks[$id]['content'] = $element->content;
}
}
return $blocks;
}
</pre>

Следовало бы ещё cmsController::getInstance()->getResourcesDirectory(); убрать в PhpExtension, для красоты, вот так:

<pre>
/**
* Возвращает путь до директории шаблона
* @return bool|string
*/
public function getTemplateDirectory() {
return cmsController::getInstance()->getResourcesDirectory();
}
</pre>

В результате код content/home/index.phtml станет вполне приличным:

<pre>
<?php
/**
* Главная страница:
* - Блок с вступительным текстом
* - Блок "Новости"
* - Блок "Контакты"
* Для удаления блока достаточно снять
* у соответствующего раздела признак "Отображать в меню"
* Для добавления блока надо добавить блок в структуру
* раздела и создать в папке content/home файл шаблона
* с именем как в поле "Псевдостатический адрес"
*
*/
$blocks = $this->getHomePageBlocks($variables);
$resourcesDir = $this->getTemplateDirectory();

foreach ($blocks as $page) {
if (isset($page['altName'])) {
if ($resourcesDir && file_exists($resourcesDir . 'php/content/home/' . $page['altName'] . '.phtml')) echo $this->render($page, 'content/home/' . $page['altName']);
else echo '<div class="alert alert-danger">Отсутствует шаблон: ', $resourcesDir, 'content/home/', $page['altName'], '.phtml</div>';
}
}
?>
</pre>