Написание сниппетов

Общее представление¶

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

Что такое сниппет?¶

Согласно одному определению, «сниппет» - это «короткий повторяющийся сниппет компьютерного исходного кода». Некоторым людям трудно отличить это от «чанка», поэтому полезная мнемоника может выглядеть так: сниппет это как «PHP», например, sni-P(h)P-et.

Как они работают?¶

Большинство сниппетов кэшируются, то есть они хранятся как временная динамическая функция в кэше. Если они помечены как некэшированные, они не анализируются, пока синтаксический анализатор не выполнит все остальное кэшированное содержимое.

Затем, как только они будут кэшированы, сниппеты затем обрабатываются парсером MODX. У них есть доступ к объекту $modx.

Простой пример¶

Вот базовый пример того, как может выглядеть код сниппета:

<?php
return 'Привет, мир!';
?>

Если вы назвали этот сниппет "helloWorld", вы можете вызвать его, используя [[helloWorld]] в ваших документах, шаблонах или чанках (см. Синтаксис тегов). Вы также можете вызвать сниппет из другого сниппета, используя метод API runSnippet.

Обратите внимание, что мы возвращали код, а не выводили его содержимое. Никогда не используйте echo в сниппете - всегда возвращайте вывод.

Передача значений в сниппет¶

Значения передаются в ваш сниппет с использованием модифицированной нотации типа веб-формы CGI, которая следует за именем сниппета. Если ваш сниппет был назван «mySnippet», вы можете вызвать его, используя что-то вроде этого:

[[!mySnippet? &input=`Привет, мир`]]

И код вашего сниппета может выглядеть примерно так:

<?php
return 'Мой ввод был: ' . $input;
?>

Обратите внимание, что имена переменных в вызывающем бите должны точно соответствовать именам переменных в сниппете (регистр имеет значение, т.е. 'input', а не 'INPUT' или 'Input'. Во-вторых, не забывайте "&" перед потенциальными именами переменных. И, наконец, что не менее важно, обратите внимание, что это обратные кавычки, а не одинарные кавычки!

Чтение значений в ваших сниппетах¶

В общем, вы можете прочитать ваши значения, сославшись на переданные аргументы: &someParameter в вызове преобразуется в $someParameter в коде PHP.

Вы также можете прочитать все параметры, используя встроенный массив $scriptProperties. Это полезно, если ваш сниппет принимает переменные параметры, т.е. он обрабатывает тот же вариант использования, что и PHP-функция func_get_args().

Например, если вы вызываете свой сниппет следующим образом:

[[!mySnippet? &x=`x-ray` &y=`yellow`]]

Тогда массив $scriptProperties будет содержать следующее:

Array(
 'x' => 'x-ray',
 'y' => 'yellow'
)

Взаимодействие с базой данных в сниппетах¶

Доступ к слою базы данных в MODX основан на объектно-реляционной модели (ORM), называемой xPDO для подключения к базе данных, поэтому, чаще всего, вам не придется писать необработанные запросы к базе данных, как вы могли бы делать в других CMS. Обычно вы получаете доступ к данным из базы данных, используя несколько объектов и методов MODX, таких как getObject и getCollection. Это зависит от базовой структуры xPDO.

Почему ОРМ?¶

Вы можете спросить, зачем использовать ОРМ вместо простого SQL? Ну, хотя бы несколько причин ниже:

1. Абстракция SQL - это означает, что вы можете писать код, который работает с различными типами баз данных, такими как MySQL, SQLite, PostgreSQL и т. д., когда MODX расширяется до этих баз данных. Все без необходимости переписывать ни единой строки кода. Это делает его идеальным для авторов плагинов, которые хотят, чтобы их код был исполняемым на самых разнообразных системах.
2. Экранирование параметров - больше не нужно беспокоиться о внедрении SQL; xPDO использует PDO PHP для экранирования всех передаваемых в вызов SQL переменных для предотвращения любых злонамеренных вызовов.
3. Более чистый, короткий код - то, что ранее могло быть сделано в более, чем 40 строках в вызовах функций mysql_ *, теперь можно сделать в 10 строках или менее.

Есть и другие причины, но это для краткости. Давайте посмотрим на несколько примеров:

Пример кода БД¶

Давайте возьмем чанк с названием LineItem и изменим в нем плейсхолдеры (выполненные с помощью синтаксиса [[+placeholderName]]) на некоторые пользовательские значения:

$chunk = $modx->getObject('modChunk',array(
   'name' => 'LineItem',
));
if (!$chunk) return 'Нет такого чанка с названием LineItem!';
return $chunk->process(array(
   'name' => 'G.I. Joe',
   'grenades' => 42,
));

Этот код получит чанк с именем LineItem и вернет его обработанным с установленным плейсхолдером. Переменная $chunk на самом деле представляет собой xPDOObject, который является объектным представлением ресурса.

Как насчет более сложных запросов? Как, скажем, получение первых 10 ресурсов с родителями 23, 24 или 25. И давайте сделаем так, чтобы они не были скрыты от меню или удалены, опубликованы и отсортированы по menuindex. Вот когда мы используем мощный метод $modx->newQuery():

$c = $modx->newQuery('modResource');
$c->where(array(
   'parent:IN' => array(23,24,25),
   'deleted' => false,
   'hidemenu' => false,
   'published' => true,
));
$c->sortby('menuindex','ASC');
$c->limit(10);
$resources = $modx->getCollection('modResource',$c);

Обратите внимание, как мы сначала создаем объект xPDOQuery ($c), используя $modx->newQuery(). Мы передали имя класса, из которого мы хотели построить запрос - здесь 'modResource' или ресурсы - и затем использовали нашу функцию where(), чтобы добавить некоторые ограничения. Затем мы отсортировали и ограничили их.

И, наконец, мы вызвали getCollection, которая - в отличие от getObject - возвращает коллекцию или массив xPDOObjects. Затем мы можем перебирать коллекцию, используя цикл foreach, и делать с элементами коллекции все, что мы хотим.

Дальнейшие подробности о работе с базой данных¶

Чтобы узнать больше о xPDO, прочитайте следующее:

• xPDO в пространстве xPDO
• Получение объектов в xPDO
• Объект xPDOQuery

Рекомендуемые методы и советы¶

Пишите свои сниппеты за пределами менеджера MODX¶

Начиная с 2.2.0, вы можете просто добавить «статический» сниппет: просто сослаться на статический файл.

До 2.2.0 это все еще довольно легко сделать - просто создайте сниппет 'include', но сделайте так, чтобы его содержимое было таким:

if (file_exists($file)) {
   $o = include $file;
} else { $o = 'Файл не найден по адресу: '.$file; }
return $o;

Вы можете использовать сниппет 'include' на странице, например:

[[!include? &file=`/absolute/path/to/my/snippet.php`]]

И запускайте свои cниппеты извне, пока вы их разрабатываете!

Затем вы можете проверить их, чтобы убедиться, что они работают (например, в командной строке bash вы можете использовать команду php -l my_script.php, чтобы проверить скрипт на наличие синтаксических ошибок). В зависимости от вашей среды вы можете также получить несколько полезных сообщений об ошибках, которые помогут вам в отладке. Скопируйте и вставьте код в MODX, только когда вы уверены, что он работает.

Помните, что любой сниппет в файле на вашем веб-сайте может выполнить любой, у кого есть веб-браузер, поэтому не оставляйте его на живом сайте, если вы не разместили код сниппета вне корневого веб-каталога таким образом, чтобы файл не мог быть доступным через Интернет. В MODX Revolution вы можете поместить файлы сниппетов в основной каталог и переместить весь каталог за пределы корневого веб-каталога. Вы также можете поместить тест в сниппет, который заставляет его завершиться, если сниппет не работает внутри MODX. Однако безопаснее всего просто переместить файл или вставить код в сниппет в менеджере и удалить файл.

Не пытайтесь смешивать коды PHP и HTML в сниппете¶

Сниппеты выполняют PHP-код. Они всегда должны начинаться с <?php **<php> <em data-md-type="emphasis">Нельзя смешивать PHP и HTML в сниппете!</em></php>** Например, следующий код работать не будет:

<p>Это ужасная смесь HTML и PHP кода</p>
<?php
return "<p>и PHP!  Не пытайтесь делать так! Это плохая архитектура и не сработает!</p>";
?>

Вы обнаружите, что MODX будет добавлять теги PHP в начало и конец сниппета, создавая неверный синтаксис, например:

<?php //что-нибудь тут ?>

Если вам нужно сделать что-то вроде этого, используйте чанк - выделите PHP в сниппет, загрузите его вывод в плейсхолдер с помощью функций-плейсхолдеров MODX API или обработайте сниппетом, и включите плейсхолдеры сниппета в чанк:

$output = $modx->getChunk('myChunk',array(
  'placeholderOne' => 'test',
  'name' => 'Harry',
  'scar' => 'Lightning',
));
return $output;

Не работайте с работающими сниппетами¶

Если вы пишете новые версии сниппетов, продублируйте старую версию! Таким образом, вы можете вернуться к старой версии кода, если что-то работает неправильно! MODX по своей сути не управляет версиями, поэтому вы должны сделать резервную копию кода самостоятельно.

Используйте свойства по умолчанию¶

Попробуйте добавить свойства по умолчанию для вашего сниппета на вкладку «Свойства», чтобы другой разработчик мог добавить пользовательские наборы свойств для их переопределения.

Смотрите также¶

1. Шаблонизируйте свои сниппеты
2. Добавление CSS и JS на ваши страницы с помощью сниппетов
3. Как написать хороший сниппет
4. Как написать хороший чанк

• modX.runSnippet
• modX.setPlaceholder
• modX.regClientCSS