Написание кастомного макроса для UMI-CMS

Разберем как добавить  кастомный макрос в UMI.CMS.

Для понимания материала требуется знание синтаксиса php и основных принципов ООП . При проблемах с этим рекомендую книгу:
Дмитрий Котеров, Алексей Костарев "PHP5 в подлиннике"
(у меня версия2005 года, скорее всего, сейчас она переиздана и название может немного отличаться)

Сразу предупреждаю: пример будет только для tpl-шаблонизатора и для старого шаблонизатора; в новом все аналогично, просто дольше писать, а он неплохо документирован в официальной справке. По вопросам модификации его под xslt обращайтесь на форум umihelp.ru.

1. Общие сведения

Макросы в UMI.CMS - это публичные методы некоего класса. Класс - это в терминологии пользовательской документации - модуль.. Так, макрос %data getProperty()% означает, что вызывается метод getProperty класса data.

Системные классы находятся в директории /classes/modules/. Кастомные макросы следует помещать в класс __custom.php 

2. Простой текст

Не мудрствуя лукаво выведем на страницу текст "Привет, мир! Это я!"

Для начала определимся как назовем наш макрос. Пусть это будет test. Опять же, не мудрствуя. Поместим его в модуль content.

Зададим функционал макроса. Пусть, если в него не передано имя, он выводит "Привет, мир!", а если передано, то "Привет, мир! Это <имя>". Вызываться макрос будет так: %content test('Вася')%

Открываем /classes/modules/content/__custom.php. Пишем там

public function test($name = false) {
  $s = "Привет, мир";
  if($name) {
    $s .= "Это  {$name}!";
  }

  return $s;
}

Разбираем.

$name = false - задает значение параметра по-умолчанию; нужно в том случае, если разработчик забудет передать в макрос имя; не указав умолчательный параметр получим ошибку.

Обращаю внимание на разницу $s =  и $s .=
Второй оператор не присваивает переменной значение, а дописывает в к имеющемуся.

Завершается макрос оператором return. НИКОГДА не выводите результат через echo, если только не работаете с аяксом.

Теперь надо задать макросу права доступа. Для это дублируем файл /classes/modules/content/permissions.php в /classes/modules/content/permissipns.custom.php, Открываем его.  Видим массив

$permissions = Array(
'content' => 
Array(....), 
'sitetree' => 
Array(....), 
 'tickets' => 
 Array(...)
 );

Ключи массива content, sitetree...  - это категории прав доступа на функционал, тот самый, что отображается в свойствах групп пользователей: //help.docs.umi-cms.ru/rabota_s_modulyami/modul_polzovateli/upravlenie_pravami_dostupa/prava_na_modul_struktura/ - соответствие очевидно из названий: "просмотр...", "управление...(то бишь дерево сайта)"

Имя макроса следует дописать в желаемую группу прав по аналогии с синтаксисом уже внесенных макросов. В нашем случае в массив content, чтобы макрос могли видеть все, а не только те, кто имеет права на управление страницами сайта.

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

Если ничего не получилось - проверяем на синтаксические ошибки: //dev.docs.umi-cms.ru/nastrojka_sistemy/dostupnye_sekcii/sekciya_debug/  - здесь все 0 установить в 1. Теперь инетрпретатор php будет выводить сообщения об ошибках в браузер. 

3. Используем шаблон

В примере выше мы писали текст непосредственно в php. Это приемлемо в простых случаях, но для полноты картины поступим по-взрослому и вынесем его в шаблон.

О TPL-шаблонах рассказывается здесь.

Для своего макроса создадим свой шаблон. В папке /tpls/content/ создать папку custom и в нее помещаем шаблон test.tpl

$FORMS = array();<

$FORMS['test_block_1'] = <<<END
Привет, мир!  %personal%
END;

$FORMS['test_block_2'] = <<<END
Это %name%!
END;

Внимательно прочитайте страницу по ссылке выше - с END нужно обходиться внимательно.
Имя блока test_block  задается произвольно.

Переписываем макрос

public function test($name = false, $template = 'test'){
     $arr1 = array();
     $arr2 = array();
     if($name){
         $arr1['name']  = "Это {$name}!";
     }
     else $arr1['name'] = '';
 
     list($test_block_1, $test_block_2) =  def_module::loadTemplates("content/custom/{$template}",  "test_block_1","test_block_2");
     $arr2['personal'] =  def_module::parseTemplate($test_block_2, $arr1);
     return def_module::parseTemplate($test_block_1,  $arr2);
 }

В шаблоне я задал два блока. Во втором формируется строка с именем юзера, в первом - приветствие целиком. Т.о., сперва следует обработать второй блок и полученный результат подставить в первый. Чтобы отработать сокращенный макрос, например, %name%, нужно в php создать элемент массива с ключом name

Загружаем шаблон, указывая путь к нему без приставки tpls

Загружаем блоки шаблона, перечисляя их друг за другом.

Обрабатываем шаблон, передавая блок шаблона и массив с результатом php-программы.