API: Инструкции
Использование сниппетов
Для чего нужны сниппеты?
Сниппеты позволяют интегрировать любой ваш PHP и HTML-код непосредственно в среду визуальной верстки для написания собственных решений (например, вывести список страниц универсального модуля).
Сниппет всегда воспринимается компилятором как PHP-код, поэтому для исполнения PHP-скриптов обязательно наличие PHP-тегов (в стандартной конфигурации включена поддержка коротких тегов <? и ?>), но как и в любом php-файле вы также можете использовать HTML-теги.
Пример простейшего сниппета для получения списка страниц и их ID:
<?
$items = $this->smartriver->page(['where' => ['confirm' => 1]]);
if($items['status'] == 'ok'){?>
<ul>
<?
foreach($items['response'] as $item){
?>
<li><?=$item['name'].' (ID '.$item['id'].')'?></li>
<?
}
?>
</ul>
<?
}
?>
Сниппеты бывают двух типов: произвольные и виджеты.
Произвольные сниппеты не взаимодействуют с окружающей средой визуальной верстки и всегда остаются в рамках заданных высоты и ширины (необходимо, когда контент должен быть статичным), виджеты же, наоборот, взаимодействуют со средой визуальной верстки и могут увеличиваться или уменьшаться по высоте, при этом толкая объекты (необходимо при построении списков и других подобных элементов).
Также в сниппеты можно передавать параметры (делается это через элемент визуальной верстки, перечисление параметров идет через запятую).
Получить эти параметры в сниппете можно через символ #. Все параметры лучше присваивать в начале кода, во избежание непредвиденных ситуаций
Пример сниппета с параметрами:
<?
$param_1 = #param_1;$param_2 = #param_2;
$param_3 = #param_3;
print_r($param_1);print_r($param_2);
print_r($param_3);
?>
$param_1, $param_2, $param_3 - это переменные, которые вы будете использовать в своем PHP коде, #param_1, #param_2, #param_3 - это своего рода теги параметров, переданных через визуальную верстку, неважно как вы их назовете (но, рекомендуется аналогично php-переменным, чтобы не было путаницы), важен лишь порядок, т.е. #param_1 идет первым в визуальной верстке, #param_2 - вторым и т.д.
Для получения ID текущей страницы (раздела, новости, товара и т.д.) необходимо использовать свойство $this->id. Оно доступно для использования в любом сниппете. Например, чтобы получить данные текущей страницы, на которой размещен созданный Вами сниппет, достаточно вызвать метод
$this->smartriver->page(['where' => ['id' => $this->id]]);
Каждый сниппет является изолированной сущностью, поэтому для использования переменных из одного сниппета в другом, следует включать в логику объект $this->storage и помещать в него необходимые свойства, например:
$this->storage->param1 = 'test';
Также предусмотрено свойство $this->module, используемое для получения названия модуля, и свойство $this->element для получения текущего объекта (применимо только для каталога: товар, раздел или бренд).
Использование MVC
Что такое MVC.
MVC - это стандартная схема распределения данных Model-View-Controller, при которой каждый из этих трех компонентов выполняет свою роль: модель - набор инструментов для взаимодействия с вашим модулем, представление (вьюшка) - отображение данных пользователю, контроллер - интерпретатор действий пользователя, который оповещает модель о необходимости тех или иных действий.
Движок SE4 дает возможность создавать любой из этих трех компонентов и связывать их друг с другом, таким образом позволяя создавать свои полноценные модули, которые могут иметь собственную логику и более расширенный функционал для вашего сайта.
При создании контроллера (как основного компонента вашего модуля) подразумевается, что будет создана и модель, поэтому для удобства в конструкторе сразу есть строка (изначально закомментированная), подключающая модель с аналогичным именем.
Также необходимо иметь ввиду, что название вашего контроллера это прямая ссылка исполняющего скрипта, поэтому контроллеры с некоторыми именами невозможно будет создать, т.к. они зарезервированы системой. Например, при создании контроллера flight, перейти к исполнению индексного (index) скрипта можно по ссылке https://your_site/flight. Если же необходимо вызвать другой метод, например start, то ссылка будет иметь вид https://your_site/flight/start
Для того, чтобы вывести данные пользователю, достаточно создать представление (вьюшку) и наполнить ее своей HTML-версткой.
В контроллере отобразить вьюшку можно используя метод
$this->load->view('flight', ['passanger' => $passanger, 'seat' => $seat]);
где первый параметр - это название вашей вьюшки в системе SE4, а второй - массив данных, которые необходимо передать из контроллера во вьюшку.
Все методы, описанные в документации по API SmartRiver доступны для использования в контроллерах и моделях при условии корректного подключения, описанного на странице введения. Необходимо помнить о том, что если SmartRiver уже подключен в контроллере, который запускает вашу модель, то в этой модели повторное подключение не требуется.
Более детальная информация по работе с MVC по ссылкам:
Контроллеры - https://codeigniter.com/userguide3/general/controllers.html
Модели - https://codeigniter.com/userguide3/general/models.html
Вьюшки - https://codeigniter.com/userguide3/general/views.html
Использование Active Record
Что такое Active Record.
Active Record - это один из популярных способов доступа к данным, которые содержатся в Базе Данных сайта.
Использовать Active Record можно как в сниппетах так и в контроллерах и моделях.
Для использования Active Record в сниппете не нужно совершать никаких дополнительных действий, можно начать использовать методы сразу.
Для использования Active Record в контроллерах и моделях необходимо сначала установить соединение с БД, используя конструкцию:
$this->load->database();
Обычно это делается в конструкторе (__construct) - если речь идет о контроллере. Таким образом, в любой вашей модели, связанной с этим контроллером, не нужно будет производить каких-либо дополнительных действий и Active Record будет также доступен и там.
Все методы Active Record содержатся в объекте $this->db
Константы из руководства:
- YOUR_QUERY - любой корректный SQL-запрос
- DB_TABLE - таблица из вашей БД с которой идет взаимодействие
- SELECT - строка с набором полей для выборки из БД
1) Выполнение произвольного SQL-запроса (необходимо в случае, если ни один из методов Active Record или SmartRiver вам не подходит и нужно написать что-то уникальное):
Стандартное выполнение
$this->db->query(YOUR_QUERY);
Если необходимо получить массив данных (только для выборки)
$this->db->query(YOUR_QUERY)->result_array();
Если необходимо получить объект данных (только для выборки)
$this->db->query(YOUR_QUERY)->result();
Если необходимо получить одиночный объект (только для выборки)
$this->db->query(YOUR_QUERY)->row();
2) Получение скомпилированного запроса на добавление данных
$sql = $this->db->set($data)->get_compiled_insert(DB_TABLE);
$sql - полученная строка с запросом
$data - массив данных для вставки
Чтобы выполнить полученный запрос, необходимо использовать метод из п.1, т.е $this->db->query($sql);
Получить ID только что созданного элемента можно с помощью метода $this->db->insert_id();
3) Получение скомпилированного запроса на обновление данных
$sql = $this->db->where($where)->set($data)->get_compiled_update(DB_TABLE);
$sql - полученная строка с запросом
$where - массив с условиями обновления
$data - массив данных для обновления
Чтобы выполнить полученный запрос, необходимо использовать метод из п.1, т.е $this->db->query($sql);
4) Непосредственное добавление записи
$this->db->insert(DB_TABLE, $data);
$data - массив данных для вставки
Получить ID только что созданного элемента можно с помощью метода $this->db->insert_id();
5) Непосредственное обновление записи
$this->db->where($where)->update(DB_TABLE, $data);
$where - массив с условиями обновления
$data - массив данных для обновления
6) Получение данных
массив данных
$this->db->where($where)->select(SELECT)->get(DB_TABLE)->result_array();
объект данных
$this->db->where($where)->select(SELECT)->get(DB_TABLE)->result();
одиночный объект
$this->db->where($where)->select(SELECT)->get(DB_TABLE)->row();
7) Удаление записи
$this->db->where($where)->delete(DB_TABLE);
$where - массив с условиями удаления
Более детальная информация о всех существующих методах Active Record текущей версии движка доступна по ссылке.
Использование колбэков
Что такое колбэк?
Колбэк (сallback) - это функция или обработчик, который вызывается при определенных событиях или состояниях (например, при успешной отправке заказа или оплате) и предоставляет доступ к соответствующим переменным, содержащим данные формы или основные данные операции.
В среде Smart Engine вам доступны следующие колбэки:
1) JavaScript-Callback на успешную отправку формы обратной связи содержит в себе 2 переменные:
| dataset |
набор data-атрибутов вида data-se-attribute, которые переданы в форму обратной связи для расширения функционала. |
| request |
объект, содержащий данные формы обратной связи для последующей обработки. Включает контактные данные клиента (например, имя, телефон, электронная почта) и все остальные поля формы (в виде массива). |
| system |
объект, содержащий в себе системные данные формы: id - идентификатор формы; caller - идентификатор вызова; href - ссылка, откуда вызвана форма; page - название страницы, откуда вызвана форма. |
2) PHP-Callback на успешную отправку формы обратной связи содержит в себе 3 переменные:
| $feedback |
массив основных данных формы (например, ID, название и др.), доступ к которым осуществляется через индексы массива, например, $feedback['id'], $feedback['name'] и т.д. Дополнительные данные можно просмотреть, выведя массив на печать. |
| $request |
основные (системные) поля, установленные в ФОС (например, ФИО, телефон, электронная почта). Доступ осуществляется через индексы массива, например, $request['name'], $request['phone'], $request['email']. |
| $fb_field |
все остальные поля формы. |
3) JavaScript-Callback на успешную отправку заказа содержит в себе 3 переменные:
| orderId |
ID заказа. |
| cart |
объект корзины. |
| request |
объект, содержащий данные формы оформления заказа, такие как контактные данные клиента (например, имя, телефон, электронная почта) и все остальные поля формы (в виде массива). |
4) PHP-Callback на успешную отправку заказа содержит в себе 5 переменных:
| $orderId |
ID заказа. |
| $cart |
массив корзины. |
| $payment |
ID выбранного способа оплаты. |
| $delivery |
ID выбранного способа доставки. |
| $fb_field |
массив всех данных формы оформления заказа. |
5) PHP-Callback на успешную оплату заказа содержит в себе 3 переменные:
| $id |
ID системы оплаты. |
| $seId |
ID заказа в системе Smart Engine. |
| $orderId |
ID заказа в системе оплаты. |
Использование JS-ивентов
Что такое ивент?
Ивент (event) — это событие, которое происходит в процессе выполнения программы. События могут быть вызваны различными действиями пользователя или изменениями состояния элементов на веб-странице.
1) se.cart.update — этот ивент срабатывает при любом изменении корзины, таком как добавление, изменение или удаление товаров, изменение способа доставки, системы оплаты или применение купона. Чтобы получить необходимые данные о корзине вы можете использовать объект __SE.tpl.cart.data.
Пример использования:
$('body').on('se.cart.update', function () {
console.log(__SE.tpl.cart.data);
});
2) se.cart.error — этот ивент срабатывает при возникновении ошибки при оформлении заказа. При срабатывании этого ивента вы можете использовать объект __SE.tpl.cart.error, который содержит следующие параметры:
| data |
данные, необходимые для анализа ошибки (при их наличии). |
| fields |
ошибочные поля формы (при их наличии). |
| status |
статус ошибки, для идентификации типа ошибки. |
