Jump to main content Jump to doc navigation

Для некоторых написание сниппета MODX может быть их первой пробой пера в програмировании. Вот несколько советов для новичков и опытных разработчиков.

Our Example Snippet

<?php
/**
 * mySnippet
 *
 * ОПИСАНИЕ
 *
 * Этот фрагмент кода умножает числа &x и &y - это демонстрирует
 * некоторые хорошие привычки.
 *
 * СВОЙСТВА:
 *
 * &x требуется целое число
 * &y требуется целое число
 * &z целое число необязательно. По умолчанию: 1
 *
 * ИСПОЛЬЗОВАНИЕ:
 *
 * [[!mySnippet? &x=`5` &y=`7`]]
 *
 */
$x = (int) $modx->getOption('x', $scriptProperties);
$y = (int) $modx->getOption('y', $scriptProperties);
$z = (int) $modx->getOption('z', $scriptProperties, 1);
// Для отладки:
$modx->log(modX::LOG_LEVEL_DEBUG
    , '[mySnippet] вызван на странице '. $modx->resource->id . ' со следующими свойствами: '
    .print_r($scriptProperties, true));
// Проверка Входных Данных
if (!isset($scriptProperties['x']) || !isset($scriptProperties['y'])) {
    $modx->log(modX::LOG_LEVEL_ERROR, '[mySnippet] отсутствуют необходимые свойства &X и &г!');
    return;
}
return $x * $y * $z;
?>

Хорошее имя

Дайте вашему сниппету имя, которое имеет смысл для тех, кто не знаком с ним. Хорошее имя легко запомнить.

Описание

Всегда включите краткое описание, которое объясняет, что делает ваш сниппет. Должно быть достаточно ясно, что незнакомец (например, другой пользователь панели управлеения, не обязательно разработчик) может понять, что делает ваш код, просто прочитав ваше описание.

Comment Block

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

Блок комментариев должен содержать следующие элементы:

ОПИСАНИЕ

Здесь вы можете описать свой код более подробно.

СВОЙСТВА

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

&day целое число число от 0 (воскресенье) до 6 (суббота), представляющее день недели. (обязательное) &is_secure логическое значение 1 использует HTTPS-соединение, 0 использует подключение по протоколу HTTP. По умолчанию: 1 &formatTpl строковое имя блока, используемого для форматирования выходных данных. MyChunk по умолчанию

ИСПОЛЬЗОВАНИЕ

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

Установить Свойства По Умолчанию

Задайте свойства по умолчанию на вкладке свойства сниппета. Вы можете прочитать свойства, переданные сниппету, и задать свойства по умолчанию с помощью метода getOption. Помните, что все фрагменты передаются массив $scriptProperties.

$headTpl = $modx->getOption('headTpl', $scriptProperties, 'myHeadTpl');

Не включайте HTML

Ваш сниппет должен быть максимально чистым от HTML. Если вам нужно отформатировать вывод, используйте сниппет для форматирования вывода. Это важный архитектурный принцип!

$props = array(
    'cow' => 'Moo',
    'pig' => 'Oink',
);
return $modx->getChunk('myChunk', $props);

Используйте плейсхолдеры в чанках

<!-- myChunk -->
Корова говорит "[[+cow]]", а свинья говорит "[[+pig]]".

Не используйте Print или Echo

Никогда не печатайте и не повторяйте значения в вашем фрагменте кода. Фрагменты подобны функциям: они должны возвращать данные. При использовании инструкций print или echo может показаться, что они работают. Они могут иметь неожиданные результаты. Всегда собирайте выходные данные в переменную строку, например $output, и возвращайте эту переменную строку.

Консистенция

Имена переменных: независимо от вашего стиля програмирования, будьте последовательны. Если вы хотите использовать имена переменных camelCase, то убедитесь, что все ваши переменные используют этот стиль.

Отступы: используйте один и тот же стиль отступов.

Ошибки журнала и информация

MODX имеет функцию ведения журнала: используйте это. Смотреть xPDO::log(). Если пользователи забыли включить обязательное свойство, зарегистрируйте ошибку, чтобы пользователи знали об этом.

$modx->log(modX::LOG_LEVEL_ERROR, '[mySnippet] missing the &xyz property!');

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

$modx->log(modX::LOG_LEVEL_DEBUG, '[mySnippet] вызван со следующими свойствами: '.print_r($scriptProperties,true));

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

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

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

  • modmore
  • modmore
  • Jens Wittmann – Gestaltung & Entwicklung
  • Raffy
  • eydolan
  • Digital Penguin
  • Fabian Christen
  • Dannevang Digital
  • deJaya
  • Sepia River Studios
  • Following Sea
  • Anton Tarasov
  • Lefthandmedia
  • Nick Clark
  • Chris Fickling
  • Murray Wood
  • YJ
  • CrewMark
  • Richard

Budget

$305 per month—let's make that $500!

Learn more