[customExtra] Создание кастомных объектов

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

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

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

До тех пор, пока мне не понадобилось иметь два таких кастомных объекта...

Поэтому сегодня я представляю вашему вниманию обновлённый customExtra.

Описание

После установки компонента, в админке появляется соответствующий раздел. В этом разделе можно увидеть обычную табличку со списком кастомных объектов.

Основные возможности

Все параметры компонента доступны в Настройках системы.

Первая настройка — Отображать табы. В этой настройке можно указать, какие табы вам необходимы. Всего в компоненте доступно 5 табов, различающихся только называниями: Предметы, Заказы, Операции, Медиа и Ссылки.

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

item,order,operation,media,link

Табы будут выведены в админке в том порядке, в котором они следуют в списке. Поэтому вы можете менять расположение табов, просто поменяв порядок в этой настройке.

Каждый таб — это отдельная табличка со своими настройками. У каждого объекта (предмета, заказа и т.д.) есть ID, название, описание и флаг активности (active).

Кроме этих полей в настройках системы можно указать, сколько и каких полей вам нужно добавить — для каждого таба в отдельности. Например, мы можем добавить Заказам два числовых поля и одну текстовую область, а для Ссылок вывести только одно текстовое поле.

Любой объект можно создать с помощью сниппета или плагина — где вам это необходимо:

<?php
$modx->addPackage('customextra', $modx->getOption('core_path').'components/customextra/model/');
$request = $modx->newObject('customExtraOperation');
$request->set('name', $_POST['name']);
$request->set('string1', $_POST['contact']);
$request->set('description', $_POST['text']);
$request->save();
return true;

и созданный объект сразу же появится в табличке. Таким же образом объекты можно и редактировать.

Выводятся объекты с помощью pdoTools

[[pdoResources?
  &class=`customExtraMedia`
  &loadModels=`customextra`
  &sortby=`id`
  &tpl=`tpl.media`
]]

Дополнительный функционал

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

Список чекбоксов: active,published,paid,new,hit,favorite

Два из них по умолчанию отмечены галочкой — Активный (active) и Опубликованный (published).

При выводе на фронтенд объекты можно фильтровать по этим чекбоксам (впрочем, как и по любым другим полям):

[[pdoResources?
  &class=`customExtraItem`
  &loadModels=`customextra`
  &sortby=`id`
  &where=`{"active":1}`
  &tpl=`tpl.items`
]]

Массовые операции — продвинутое использование

Для каждого типа объектов можно указать сниппет для дополнительной кнопки. Эта кнопка появится, если будет найден сниппет, название которого указано в настройках.

При нажатии на кнопку сниппет будет запущен. Если вам необходимо обработать в этом сниппете множество объектов, необходимо разделять обработку на порции. Для этого сниппет должен «сообщить» компоненту о том, что обработка не завершена. Если сниппет вернет false, компонент запустит его еще раз — и так до тех пор, пока не будет получен ответ true.

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

<?php
$modx->addPackage('customextra', $modx->getOption('core_path').'components/customextra/model/');
// Укажем, по сколько объектов обрабатывать за раз
$step = 5;
// Формируем запрос
$q = $modx->newQuery('customExtraOrder', array('new' => 1));
// Посчитаем, сколько всего объектов с отмеченной галочкой в базе
$count = $modx->getCount('customExtraOrder', $q);
// Если «Новых» объектов не найдено, останавливаем выполнение
if ($count == 0) return true;
// Установим лимит
$q->limit($step);
// И получим порцию объектов для обработки
$orders = $modx->getCollection('customExtraOrder', $q);
// Теперь можно обработать полученные объекты
foreach ($orders as $order) {
  $order->set('new', 0);
  $order->save();
}
// Если всего в базе объектов меньше, чем мы обрабатываем за один шаг
if ($count <= $step) {
  // то мы останавливаем обработку
  return true;
} else {
  // если нет - указываем, что обработка не закончена
  return false;
}

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

Пример использования

Конечно, без примера сложно представить себе функционал, поэтому давайте попробуем представить, что в ТЗ на разработку сайта имеется что-то типа такого:

4.3. Размещение пользователями контента
Необходимо реализовать форму добавления контента. Пользователь должен получить возможность добавлять в общую ленту сущность «Цитата». Добавленная цитата должна быть неопубликованной до тех пор, пока менеджер не одобрит её в админке. После одобрения пользователю отправляется уведомление, а цитата появляется в ленте.

Давайте, реализуем такой функционал.

Устанавливаем customExtra, и в настройках проставляем нули у дополнительных полей (нам достаточно только name и description), а из галочек оставляем только active и new




Ну и в лексиконах заменим слово «Предмет» на «Цитата»

• 
  
• 
  
• 
  

Табличка теперь выглядит подходящим образом




Выведем на сайте форму добавления цитаты:

[[!AjaxForm?
  &form=`form.addQuote`
  &hooks=`saveQuote`
  &validate=`quote:required`
]]

<form action="" method="post" class="ajax_form af_example form-horizontal">
  <div class="control-group">
    <label class="control-label" for="af_quote">[[%af_label_message]]</label>
    <div class="controls">
        <textarea id="af_quote" name="quote" class="span4" rows="5">[[+fi.quote]]</textarea>
        <span class="error_quote">[[+fi.error.message]]</span>
    </div>
  </div>
  <div class="control-group">
    <div class="controls">
      <button type="reset" class="btn btn-default">[[%af_reset]]</button>
      <button type="submit" class="btn btn-primary">[[%af_submit]]</button>
    </div>
  </div>
</form>

И создадим сниппет saveQuote — который будет сохранять цитату

<?php
$modx->addPackage('customextra', $modx->getOption('core_path').'components/customextra/model/');
$quote = $modx->newObject('customExtraItem');
$quote->set('description', strip_tags($_POST['quote']));
$quote->save();
$quote->set('name', 'Цитата № '.$quote->id);
$quote->save();
return true;

Кстати, можно сразу сохранить id пользователя и время создания цитаты:

$quote->set('id1', $modx->user->id);
$quote->set('id2', time());

Кроме того, новые цитаты надо помечать как неактивные (чтобы менеджер их публиковал) и новые (чтобы высылать уведомления)

$quote->set('active', 0);
$quote->set('new', 1);

Можно пробовать добавлять цитаты. Они сразу появятся в табличке:




Чтобы отправлять уведомления, будем использовать дополнительную кнопку. Для этого создаём сниппет sendNotifications и указываем его в системной настройке.

<?php
$modx->addPackage('customextra', $modx->getOption('core_path').'components/customextra/model/');
$step = 1;
// Нам нужны новые опубликованные цитаты
$q = $modx->newQuery('customExtraItem', array('active' => 1, 'new' => 1));
$count = $modx->getCount('customExtraItem', $q);
if ($count == 0) return true;
$q->limit($step);
$quotes = $modx->getCollection('customExtraItem', $q);
foreach ($quotes as $quote) {
  // Реализацию отправки письма вынесем в отдельный сниппет
  $modx->runSnippet('sendEmail', array(
        'toUser' => $quote->id1,
        'quote' => $quote->description
      ));
  // Убираем галочку "Новая" - чтобы не отправить повторно
  $quote->set('new', 0);
  $quote->save();
}
if ($count <= $step) {
  return true;
} else {
  return false;
}

Еще можно поменять надпись на кнопке:




Когда будем выводить цитаты на сайт, главное не забыть заменить все квадратные и фигурные скобки в цитате на соответствующие HTML-коды

Теперь можно показывать заказчику и считать, что функционал реализован.

Где скачать

Первая версия компонента была доступна в репозитории MODX.

Но сейчас функционал стал шире и теперь новая, расширенная и улучшенная версия, доступна в магазине modstore.pro на платной основе.

customExtra 2.0.2-beta