Документация InstantCMS - dev:integration

Введение в интеграцию компонентов

Anonymous (anonymous@undisclosed.example.com) — 2015-12-13T16:36:40+00:00

Введение в интеграцию компонентов

В InstantCMS есть компоненты (контроллеры), которые могут использоваться другим компонентами движка. К ним относятся такие компоненты, как «Генератор RSS», «Поиск», «Лента активности», «Генератор карты сайта» и так далее.

Такие компоненты условно можно разделить на два типа:

встраиваемые
обслуживающие

К встраиваемым относятся компоненты, например, «Комментарии», «Рейтинг». К обслуживающим относятся «Генератор RSS», «Поиск» и подобные.

Например, компонент «Комментарии» может работать на любой странице движка и дополнять функционал текущего компонента возможностью комментировать.

А, к примеру, компонент «Генератор RSS» обслуживает нужный компонент. Т.е. его назначение выводить rss фиды на основе нужных данных.

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

К оглавлению раздела "Интеграция"

К оглавлению документации для разработчиков

Интеграция и работа с очередью

Anonymous (anonymous@undisclosed.example.com) — 2018-04-23T07:14:41+00:00

Интеграция и работа с очередью

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

Ожидает выполнения;
Выполняется;
Ожидает повторного выполнения;
Завершено с ошибкой.

Очередь запускается по CRON при помощи системного планировщика. За одно выполнение запускаются 20 задач очереди. Система очередей интегрирована в компоненты Личные сообщения и Подписки.

Работа с очередью

Вся работа с очередью заключается в большинстве случаев в постановке задания в очередь. Обслуживается это системным классом cmsQueue, в котором все методы статические. Класс можно дополнить/переопределить, в нём используется позднее статическое связывание.

Методы

Все методы класса являются статичными.

cmsQueue::pushOn

pushOn(string  $queue, array  $data, integer  $priority = 1) : integer

Добавляет задание в очередь.

Параметры

Тип	Имя	Описание
string	$queue	Имя очереди.
array	$data	Основные данные очереди.
integer	$priority	Приоритет задания, по умолчанию 1.

cmsQueue::pushOnLater

pushOnLater(string  $queue, array  $data, integer  $priority = 1) : integer

Добавляет задачу в очередь с отсрочкой в секундах или по дате.

Параметры

Тип	Имя	Описание
mixed	$date	Количество секунд для смещения от текущего времени или полная дата.
string	$queue	Имя очереди.
array	$data	Основные данные очереди.
integer	$priority	Приоритет задания, по умолчанию 1.

В обоих случаях в массиве $data передаются непосредственно полезные данные очереди, например:

    cmsQueue::pushOn('email', array(
        'controller' => 'messages',
        'hook'       => 'queue_send_email',
        'params'     => array(
            $to, $letter, $is_nl2br_text
        )
    ));

Массив $data должен содержать ячейки:

controller - название контроллера (обязательно);
hook - название хука контроллера (необязательно);
action - название экшена контроллера (необязательно);
params - параметры, передаваемые в хук или экшен (необязательно).

Должен быть передан либо hook, либо action. Если будет переданы оба параметра, вызовется сначала хук, потом экшен с одинаковыми параметрами params. Обратите внимание, что при выполнении задания в хук или экшен первым параметром всегда будет передаваться текущая попытка выполнения $attempts.

Обработка очереди

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

Исполняющий хук или экшен задания строго может возвращать:

булево true - в этом случае движок будет считать, что задание выполнено успешно и удалит его из очереди;
булево false - задание выполнено, но будет запущено еще раз, пока не будет достигнуто максимальное кол-во перезапусков (по умолчанию 4);
любая строка, которая будет означать текст ошибки выполнения.

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

Пример реализации хука можно посмотреть здесь или здесь.

Интеграция списка заданий очереди в админке

Для удобной интеграции списка очереди, используемой в контроллере, необходимо в контроллере админки объявить следующее свойство (на примере контроллера подписок):

public $queue = array(
    'queues'           => array('subscriptions'), // имена очередей, используемых в контроллере
    'queue_name'       => LANG_SBSCR_QUEUE_NAME,  // общее название этих очередей
    'use_queue_action' => true                    // флаг, разрешающий добавить раздел очередей в админку компонента
);

Для заданий очереди будут доступны действия удаления и перезапуска.

К оглавлению раздела "Интеграция"

К оглавлению документации для разработчиков

Интеграция ленты RSS для своего компонента

Anonymous (anonymous@undisclosed.example.com) — 2018-09-17T07:28:48+00:00

Интеграция ленты RSS для своего компонента

В комплекте InstantCMS есть компонент «Генератор RSS», выполняющий генерацию RSS лент на сайте. Архитектура построена таким образом, что позволяет генерировать ленты RSS для любого компонента. Интеграция заключается в:

Создание записи в таблице cms_rss_feeds;
Создании хука rss_feed_list для получения из него данных;
При необходимости, дополнить настройки RSS ленты (её форму) также посредством хуков.

Создание записи в таблице

Если вы делаете компонент, который впоследствии оформите в пакет дополнения, то создание записи в таблице rss_feed_list необходимо делать в установщике пакета.

Типичный SQL запрос на добавление записи выглядит так (на примере компонента «Комментарии»):

INSERT INTO `cms_rss_feeds` (`ctype_name`, `title`, `mapping`, `is_enabled`) VALUES
('comments', 'Комментарии', '---\r\ntitle: target_title\r\ndescription: content_html\r\npubDate: date_pub\r\n', 1);

В поле mapping вы должны в YAML формате указать соответствия полей используемых в самой RSS ленте с полями в вашей записи:

Поле title (в примере выше title соответствует полю target_title в таблице комментариев);
Поле description (в примере выше поле description соответствует полю content_html в таблице комментариев);
Поле pubDate (в примере выше поле pubDate соответствует полю date_pub в таблице комментарие).

Удобнее всего сделать это в массиве, который потом преобразовать в YAML.

Создание хука

Для того, чтобы получить данные для RSS ленты вашего компонента, необходимо создать хук с названием cms_rss_feeds. Обратите внимание, для этого хука не нужно создавать запись в файле manifest.php вашего компонента. Хук вызывается напрямую, в контексте вашего контроллера. Объект $this→request внутри хука будет также в контексте текущего запроса, тип запроса - стандартный.

В хук передаётся один параметр $feed, это массив данных ленты, полученный из базы данных.

Возвращать хук должен массив массивов array($feed, $category, $author). Где, $feed - переданный массив ленты в хук, $category - массив категории, если необходимо, $author - массив данных об авторе, если необходимо.

Если массивы $category и $author в вашем компоненте не актуальны, то они должны быть переданы пустыми, иначе массивы должны содержать:

$category - ячейку title с названием категории;
$author - ячейку nickname с никнеймом пользователя.

$category = array(
    'title' => 'Название категории'
);
$author= array(
    'nickname ' => 'ЮзерНейм'
);

Задача хука заполнить ячейку $feed['items'] списком данных ленты.

Каждая запись в массиве $feed['items'] должна содержать ячейки target_title и page_url с заголовком и абсолютным URL соответственно. Кроме этого, каждая запись должна содержать значения соответствий поля mapping, которые мы указывали в SQL запросе выше.

Хуки на форму RSS ленты в админке

Формирование URL на ленту

Шаблон RSS ленты

К оглавлению раздела "Интеграция"

К оглавлению документации для разработчиков

Интеграция полнотекстового поиска

Anonymous (anonymous@undisclosed.example.com) — 2018-04-23T06:08:25+00:00

Интеграция полнотекстового поиска

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

Подключение хука

Подключение вашего компонента сводится к созданию хука, который работает по параллельной схеме с именем fulltext_search. Обратите внимание, что производится полнотекстовый поиск MySQL. Ваша таблица должна иметь соответствующий индекс типа FULLTEXT (если поиск по нескольким ячейкам, то индекс должен быть составной). Движок таблицы должен быть MyISAM (допускается InnoDB, если ваша версия MySQL поддерживает полнотекстовые индексы InnoDB).

В хук не передаётся параметров. Возвратить хук должен массив с такими ячейками (все обязательные):

return array(
    'name'          => $this->name,
    'sources'       => $sources,
    'table_names'   => $table_names,
    'match_fields'  => $match_fields,
    'select_fields' => $select_fields,
    'filters'       => $filters,
    'item_callback' => function($item, $model, $sources_name, $match_fields, $select_fields){
 
        return array_merge($item, array(
            'url'      => href_to($sources_name, $item['slug'] . '.html'),
            'title'    => $item['title'],
            'fields'   => array(),
            'date_pub' => $item['date_pub'],
            'image'    => ''
        ));
 
    }
);

Расшифровка ячеек ответа

Название	Описание
name	Название контроллера, например guestbook.
sources	Массив обрабатываемых целей, например `array('guestbook' ⇒ 'Гостевая книга')`. Название цели может совпадать с названием контроллера. Целей может быть несколько.
table_names	Массив таблиц, из которых выбирать данные. Ключом массива должно быть название цели. Для каждой цели указывается своя таблица, например `array('guestbook' ⇒ 'guestbooks')` (таблица `cms_guestbooks`).
match_fields	Массив, ключом которого является название цели, а значением массив полей, которые участвуют непосредственно в полнотекстовой выборке в операторе MATCH. Например, `array('guestbook' ⇒ array('title', 'description'))`. Для каждой цели можно указать свой набор полей.
select_fields	Массив, ключом которого является название цели, а значением массив полей, которые нужно выбрать из таблицы. Например, `array('guestbook' ⇒ array('id', 'slug', 'title', 'description'))`. Для каждой цели можно указать свой набор полей.
filters	Массив, ключом которого является название цели, а значением массив условий и полей для фильтрации. Например, `array('guestbook' ⇒ array(array('condition' ⇒ '=','value' ⇒ 1,'field' ⇒ 'is_pub')))`. В этом случае будет происходить фильтрация по полю `is_pub`, которое должно быть равным 1.
item_callbackck	Анонимная функция, которая обрабатывает ответ из базы данных. В ней доступны переменные: $item - массив записи с полями, которые мы запросили в ячейке select_fields, $model - объект модели класса modelSearch, $sources_name - название цели, например `guestbook` (полезно для формирования url записей), $match_fields и $select_fields в которых содержится массив соответствующих полей, которые мы указали выше. Возвращать эта функция должна несколько обязательных ячеек: url сформированная ссылка на страницу просмотра искомой записи, title - название найденной записи, date_pub - дата записи (без форматирования), image HTML код изображения, если таковое есть. Остальные ячейки не являются обязательными, поэтому при ответе практичнее будет результирующий массив сливать с массивом обязательных ячеек, как показано в PHP коде выше.

Примеры уже готовых хуков вы можете посмотреть в файлах /system/controllers/content/hooks/fulltext_search.php (реализация полнотекстового поиска в компоненте «Контент») и /system/controllers/photos/hooks/fulltext_search.php (полнотекстовый поиск по фотографиям).

Свой шаблон вывода результатов для цели

По-умолчанию, движок для вывода результатов поиска использует шаблон /templates/default/controllers/search/index.tpl.php. Однако, для нужной цели вы можете создать свой шаблон с названием по принципу index_НАЗВАНИЕ_ЦЕЛИ.tpl.php. Например, шаблон /templates/default/controllers/search/index_photos.tpl.php обрабатывает результаты поиска по фотографиям. Шаблон /templates/default/controllers/search/index_guestbook.tpl.php будет обслуживать результаты поиска по компоненту «Гостевая книга» и так далее.

Хуки обработки данных поиска

Помимо описанного выше, после выполнения основного хука, компонент «Поиск» обрабатывает следующие хуки:

Название	Описание
search_CONTROLLER_NAME_data	CONTROLLER_NAME - название контроллера, например guestbook (название хука будет search_guestbook_data). Обрабатывает каждый ответ контроллеров основного хука fulltext_search. В него передаётся то, что вернул заданный контроллер. Полезно использовать для дополнительной фильтрации/дополнения полей в выборку или для иных действий.
content_TARGET_NAME_search_list	TARGET_NAME - название цели, например guestbook (название хука будет content_guestbook_search_list). Обрабатывает результирующий массив данных ответа от поиска.

Название

Описание

search_CONTROLLER_NAME_data

CONTROLLER_NAME - название контроллера, например guestbook (название хука будет search_guestbook_data). Обрабатывает каждый ответ контроллеров основного хука fulltext_search. В него передаётся то, что вернул заданный контроллер. Полезно использовать для дополнительной фильтрации/дополнения полей в выборку или для иных действий.

content_TARGET_NAME_search_list

TARGET_NAME - название цели, например guestbook (название хука будет content_guestbook_search_list). Обрабатывает результирующий массив данных ответа от поиска.

К оглавлению раздела "Интеграция"

К оглавлению документации для разработчиков