MODX. xPDO. Плейсхолдеры (Placeholders)

Меню

Отредактировано: 14 Июня 2023

Плейсхолдеры — один из базовых элементов MODX, что-то вроде переменных, которые используются, для отображения хранимой в них информации в чанках и шаблонах. В базовом синтаксисе MODX плейсхолдеры записываются так: [[+placeholder]], при использовании fenom — {$placeholder} или {$_pls['prefix.placeholder']}.

Перед тем как попасть в тег MODX, информация о плейсхолдерах формируется в системном массиве $modx->placeholders. Чтобы добавлять, изменять, или удалять плейсхолдеры, при работе с этим массивом, есть ряд xPDO методов, которые описаны ниже.

Добавление плейсхолдеров

setPlaceholder('name', 'value') — устанавливает один плейсхолдер с именем name и значением value, который будет доступен при вызове [[+name]].
```
$modx->setPlaceholder('berry','blueberry');
```
setPlaceholders(array/object $placeholders, ['prefix']) — устанавливает коллекцию плейсхолдеров, передаваемых с помощью простого ассоциативного массива или объекта. При этом доступ к плейсхолдеру осуществляется через ключи передаваемого массива. У этого метода есть необязательный параметр $namespace, если его установить, то вызов должен также начинаться с имени простраства.
```
$modx->setPlaceholders(array(
   'berry' => 'blueberry',       // [[+goodies.berry]]
   'fruit' => 'kiwi',            // [[+goodies.fruit]]
),'goodies.');
```

toPlaceholder('name', 'value', ['prefix'], ['separator'], [restore]) — устанавливает один плейсхолдер, но работает с ним как с многомерным массивом. В отличие от setPlaceholder имеет 3 дополнительных необязательных параметра:

prefix — используется для указания имени пространства, к которому будет относится плейсхолдер;
separator — устанавливает разделитель между префиксом и ключем (по умолчанию точка '.', но при переопределении '1');

restore — может иметь значение true или false. В случае если установлено true, в результирующий массив добавляется еще 1 ключ [restore] с массивом содержащим предыдущие данные (не все, только ближайшие):

// Простая работа с методом toPlaceholder
$modx->toPlaceholder('berry','blueberry','goodies'); 
// установит плейсхолдер [[+goodies.berry]] со значением 'blueberry'

// переопределим уже установленный плейсхолдер, установим параметр $restore в true (и разделитель точку)
$val = $modx->toPlaceholder('berry','cherry','goodies', '.', true); 
// установит плейсхолдер [[+goodies.berry]] со значением 'cherry', 
// а также создаст массив restore с ключем goodies.berry и значением 'blueberry'
// B переменной $val будет храниться массив:
// array(
//  'keys' => array('goodies.berry')
//  'restore' => array(
//    'goodies.berry' => 'blueberry'
//   )
// )

// В метод можно передавать массив
$val = $modx->toPlaceholder('berry', array('inForest'=>'blueberry','inGarden'=>'cherry'),'goodies')
// получим 2 плейсхолдера - [[+goodies.berry.inForest]] и [[+goodies.berry.inGarden]] 
// со значениями 'blueberry' и 'cherry' соответственно. 
// B переменной $val будет храниться массив:
// array(
//  'keys' => array(
//    'goodies.berry.inForest',
//    'goodies.berry.inGarden'
//   )
// )

toPlaceholders(array/object $placeholders, ['prefix'], ['separator'], [restore]) — устанавливает коллекцию плейсхолдеров, передаваемых с помощью массива или объекта. Дополнительные параметры и принцип работы аналогичен методу toPlaceholder, разница лишь в методе добавления данных:
```
$modx->toPlaceholders(
  array(
    'berry' => 'blueberry',
    'foreign' => array(
      'fruit' => 'kiwi')
  ), 
  'goodies.'
);

// установит 2 плейсхолдера [[+goodies.berry]] и [[+goodies.foreign.fruit]]
```

Получение плейсхолдеров

getPlaceholder('name') — позволяет получить существующий плейсхолдер по указанному ключу:
```
$val = $modx->getPlaceholder('goodies.berry');
```
Можно обратиться к массиву плейсхолдеров напрямую:
```
$val = $modx->placeholders['goodies.berry'];
```

Удаление плейсхолдеров

unsetPlaceholder(key) — удаляет один плейсхолдер, указанный в ключе:
```
$modx->unsetPlaceholder('goodies.berry');
```

unsetPlaceholders(keys) — удаляет коллекцию плейсхолдеров:

// можно указывать 1 плейсхолдер
$modx->unsetPlaceholders(goodies.berry);

// можно указывать элементы массива
$modx->unsetPlaceholders(
   array('goodies.berry','goodies.fruit')
);

// можно указывать пространство имен 'goodies.'
$modx->unsetPlaceholders('goodies.');

Некоторые особенности

При работе с системными плейсхолдерами необходимо указывать дополнительный '+':

$modx->setPlaceholder('+site_url','riwkus.pro');

В некоторых случаях плейсхолдеры нельзя вызвать с использованием тегов MODX, если вы столкнулись с подобной ситуацией, используйте fenom конструкцию {$_modx->getPlaceholder('placeholder')}.

Если возникла необходимость посмотреть какие плейсхолдеры существуют при рендере страницы, можно использовать сниппет viewPlaceholders:

if (!$modx->user->isMember('Administrator')) return;

$placeholders = $prefix ? array() : $modx->placeholders;

if ($prefix) {
    foreach ($modx->placeholders as $key => $ph) {
        if (strpos($key, $prefix) === 0) {
            $placeholders[$key] = $ph;
        }
    }
}    

return '<pre>' . print_r($placeholders, true) . '</pre>';