Сниппет Shopkeeper 1.3

Описание

Сниппет выводит корзину заказов двух типов (расширенный и простой). Письмо с заказом можно отправлять на почту и в модуль Shopkeeper (рекомендуется). Товарам можно задавать дополнительные параметры, которые пользователь сможет выбрать. Для создания формы заказа нужно использовать сниппет eForm, для вывода списка товаров - CatalogView или Ditto.

Виджеты для параметров товаров

Для создания виджетов (выпадающий список, радиокнопка, чекбокс) используется модификатор PHx - shk_widget.

Параметры сниппета

Параметр	Описание и значения	Значение по умолчанию	Примечание
&lang	язык	Язык системы управления	В настоящее время доступны языки: `russian`, `english`, `german`, `francais`
&style	стиль корзины	`default` (assets/snippets/shopkeeper/style/default/)	&style=`0` - если не нужен отдельный стилевой файл для корзины
&cartType	тип корзины `full` - расширенный, `small` - простой, `empty` - только очистка корзины без вывода на странице	`full`
&currency	валюта	`руб.`
&priceTV	имя TV-параметра, который используется для цены.	`price`	Если ваш TV для цены имеет название не "price", обязательно укажите это имя в данном параметре.
&orderFormPage	ID страницы с формой заказа	`1`	обязательный параметр
&noJQuery=`1`	если на сайте уже используется библиотека JQuery	`0`
&noConflict=`1`	если на сайте используется другая JS-библиотека (не JQuery), например Mootools, Prototype.	`0`
&noCounter	скрывать (значение `1`) или нет (значение `0`) счетчик товаров при добавлении в корзину	`0`
&linkAllow=`0`	Выводить названия товаров в корзине без ссылок.	`1`	Если этот параметр указан (=`0`) на странице оформления заказа, письмо с составом заказа и список товаров в модуле будут без ссылок.
&stuffCont	CSS-селектор элемента, внутри которого находится информация о товаре.	`div.shk-item`	В предыдущих версиях этот параметр назывался clStuffCont. Пример чанка: chunk_shopStuff.tpl
&debug=`1`	запустить отладку JavaScript-функций (вывод информации)	`0`
&tplPath	путь до папки с чанками	`assets/snippets/shopkeeper/chunks/ru/`
&cartTpl	чанк с шаблоном корзины	`@FILE:chunk_shopCart.tpl`	Чанк содержит сразу 3 шаблона - для пустой, заполненной расширенной и простой корзины. Если чанки хранятся в файлах, можно указать путь с командой "@FILE:". Если чанки созданы в системе управления, то указывается только имя чанка (например &cartTpl=`shopCart`)
&cartRowTpl	чанк шаблона строки с информацией товара в расширенной корзине	`@FILE:chunk_shopCartRow.tpl`
&cartHelperTpl	чанк шаблона "хелпера" - блока, который появляется для подтверждения действий	-
&additDataTpl	чанк для доп. параметров товаров в корзине ([+addit_data+])	-
&orderDataTpl	чанк списка товаров в отчете о заказе ([+orderData+])	-	Используется в письме с отчетом о заказе (eForm &report) и в модуле.
&flyToCart	действие при добавлении товара в корзину. `helper` - появляется блок со счетчиком кол-ва товаров и летит в корзину, `image` - в корзину летит картинка товара `nofly` - в корзину ничего не летит;	`helper`	При &flyToCart=`image` тег <img> должен иметь CSS-класс "shk-image"
&noLoader=`1`	не паказывать прелоадер (анимационная картинка)	`0`
&excepDigitGroup=`1`	разделять числа цен в корзине на разряды	`1`
&changePrice=`1`	при изменении параметров с ценой - изменяется цена товара, а индекс с плюсом не появляется	`0`
&counterField=`1`	добавить ко всем полям <input name="shk-count"> (кол-во товара) стрелки больше/меньше	`0`
&noJavaScript=`1`	Работа без JavaScript.	`0`	Обратите внимание, что в чанке "shopCart" кнопка "Пересчитать" находится внутри тега "noscript". Если используется режим &noJavaScript=`1`, рекомендуется тег "noscript" удалить.
&hideOn	Отключить корзину на странице	`0`	Обычно используется в вызове сниппета краткого вида корзины. Указывается ID страницы с подробным видом корзины (оформление заказа). На этой странице краткий вид корзины будет отключен.

Примеры вызова

[!Shopkeeper? &priceTV=`price` &orderFormPage=`10`!]

[!Shopkeeper? &cartType=`small` &priceTV=`price` &orderFormPage=`10` &changePrice=`1` &counterField=`1` &flyToCart=`nofly`!]

Шаблоны (чанки) и плейсхолдеры

Параметр сниппета	Описание	Плейсхолдеры в шаблоне	Примечание
&cartTpl (&cartType=`full`)	шаблон расширенной корзины	[+inner+] - строка с информацией о товаре (cartRowTpl); [+price_total+] - Общая сумма; [+this_page_url+] - URL текущей страницы; [+empty_url+] - URL для очистки корзины; [+order_page_url+] - URL страницы оформления заказа; [+currency+] - валюта;	Пример: chunk_shopCart.tpl (содержит 3 шаблона корзины) <!--tpl_separator--> - разделитель шаблонов (удалять нельзя)
&cartTpl (&cartType=`small`)	шаблон упрощенной корзины	[+price_total+] - Общая сумма; [+total_items+] - Число выбранных товаров; [+plural+] - слово "товар" во множественном числе в зависимости от числа выбранных товаров; [+this_page_url+] - URL текущей страницы; [+empty_url+] - URL для очистки корзины; [+order_page_url+] - URL страницы оформления заказа; [+currency+] - валюта
&cartRowTpl	шаблон строки с информацией товара в расширенной корзине	[+id+] - ID товара (документа); [+name+] - название товара; [+link+] - ссылка на страницу товара; [+addit_data+] - строка с информацией о доп. параметрах товара; [+price+] - цена; [+price_total+] - цена товара + доп. параметры; [+price_count+] - цена товара * кол-во; [+currency+] - валюта; [+count+] - количество; [+this_page_url+] - URL текущей страницы; [+index+] - номер товара в корзине (от нуля); [+любой TV+] - любой TV-параметр, например [+image+]; [+shk_любой TV+] - любой доп. параметр, выбранный при добавлении товара в корзину (из [+addit_data+]), например [+shk_param1+].	Пример: chunk_shopCartRow.tpl и chunk_shopCartRow2.tpl
&additDataTpl	шаблон для доп. параметров товаров в корзине ([+addit_data+])	[+param+] - имя и цена параметра. Цена указывается в скобках. Если цена = 0, то пишется только название параметра (без скобок); [+name+] - имя параметра; [+price+] - цена параметра;	Пример: chunk_additDataTpl.tpl
&orderDataTpl	шаблон списка товаров в отчете о заказе ([+orderData+])	Все плейсхолдеры чанка &cartRowTpl [+loop+], [+end_loop+] - начало и конец строки данных товаров (цикл).	Пример: chunk_orderDataTpl.tpl
&report (eForm)	шаблон текста письма с составом заказа	[+orderData+] - состав заказа (список покупок); [+orderID+] - номер заказа;	Пример: chunk_shopOrderReport.tpl и chunk_shopOrderReportWebUser.tpl
Страница, на которой вызывается сниппет Shopkeeper		[+totalItems+] - кол-во товара в корзине; [+totalPrice+] - общая цена товара в корзине;

Необходимые CSS-классы, Id и имена полей

Для полноценной работы Shopkeeper необходимы следующие CSS-классы, Id и имена полей:

Шаблон	CSS-классы	id HTML-элементов	Имена полей и кнопок	Примечание
Шаблон вывода информации товара	shk-item - класс "обертывающего" элемента блока с информацией о товаре; shk-image - картинка товара (если используется &flyToCart=`image`); shk-price -класс элемента с ценой товара.	—	shk-id - имя скрытого поля с id товара; shk-count - имя скрытого поля с кол-вом товара.	Пример chunk_shopStuff.tpl
Шаблон корзины	—	shopCart - id "обертывающего" элемента блока корзины; butEmptyCart - id кнопки-ссылки очистки корзины; butOrder - id ссылки на страницу оформление товара.	shk_recount - кнопка "Пересчитать".	Пример chunk_shopCart.tpl
Шаблон строки информации о товаре в корзине	shk-del - кнопка-ссылка удаления товара.	—	count[] - name полей с кол-вом товара.	Пример chunk_shopCartRow.tpl
Шаблон формы заказа	—	—	email - поле "E-mail"; phone - поле "Телефон"	Пример chunk_shopOrderForm.tpl и chunk_shopOrderFormWebUser.tpl

CSS-классы (и id) используются в JS-функциях. Их можно использовать как дополнительные. Пример:
<div class="shop-stuff shk-item">

Оформление заказа

Форма заказа делается при помощи сниппета eForm. При вызове этого сниппета обзательно указать параметры:

&eFormOnBeforeMailSent=`populateOrderData` - функция для заполнения данных о выбранных товарах.

Для того чтобы заказы отправлялись в модуль Shopkeeper, в вызов сниппета eForm добавить параметр &eFormOnMailSent=`sendOrderToManager`.

Пример вызова eForm:

[!eForm? &formid=`shopOrderForm`&tpl=`shopOrderForm`&report=`shopOrderReport`&vericode=`1`&ccsender=`1`&gotoid=`11`&subject=`Новый заказ`&eFormOnBeforeMailSent=`populateOrderData`&eFormOnMailSent=`sendOrderToManager`!]

Подключение системы оплаты

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

$_SESSION['shk_order_id'] - ID заказа в БД;
$_SESSION['shk_payment_method'] - выбранный способ оплаты (список с name="payment" в форме);
$_SESSION['shk_order_price'] - общая цена;
$_SESSION['shk_currency'] - валюта;
$_SESSION['shk_order_user_id'] - ID пользователя (если не зарегистрирован = 0);
$_SESSION['shk_order_user_email'] - адрес электронной почты плательщика (если не зарегистрирован).

События для создания плагинов

OnSHKFrontendInit - инициализация сниппета Shopkeeper во внешней части.
OnSHKgetProductPrice - определение цены товара при добавлении в корзину.
OnSHKChangeStatus - изменение статуса заказа.
OnSHKOrderDescRender - вывод подробной информации о заказе в модуле.
OnSHKMailApprovedForPayment - отправление письма при статусе "Принят к оплате". Плагин может добавлять в письмо доп. информацию ([+plugin+]).
OnSHKcartLoad - загрузка корзины (вывод информации в чанке &cartTpl - [+plugin+]).
OnSHKstatusSendMail - отправка письма о смене статуса.
OnSHKmodRenderTopLinks - вывод ссылок вверху в модуле Shopkeeper.
OnSHKmodPagePrint - вывод страницы модуля. Можно использовать для создания своей страницы (см. пример OnSHKmodPagePrint_plugin_example.txt).
OnSHKbeforeSendOrder - перед отправкой заказа. Можно использовать для изменения полей ($fields).
OnSHKsaveOrder - сохранение заказа.
OnSHKcalcTotalPrice - расчет общей стоимости.

В папке shopkeeper/docs/ есть примеры плагинов.

"Сallback-функции" на JavaScript

setCartActionsCallback - перезагрузка корзины,
fillCartCallback - добавление товара в корзину,
emptyCartCallback - очищение корзины.

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

Две и более цены для одного товара

Для этого нужно создать две или более формы (<form>) и в поле name="shk-id" после ID написать имя TV с ценой.

Пример:

<input type="hidden" name="shk-id" value="[+id+]__price2" />

При submit формы в корзину добавится цена из TV-параметра с именем "price2".

Добавление в корзину данных, не создавая TV-параметры

Пример:

<input type="text" name="test__[*id*]__add" value="дополнительные данные" />

В корзину добавится параметр, который можно выводить в месте вставки плейсхолдера [+test+] (выведется "дополнительные данные").

Товары в каталоге Shopkeeper

Можно сохранять товары в отдельльную таблицу БД (не документы). При хранении товаров в отдельной таблице можно забыть про ограничение на число документов MODx. При этом остается возможность использовать стандартные TV-параметры для товаров и плагины. Для создания и редактирования товаров используется стандартный интерфейс (можно настраивать с помощью плагина ManagerManager). Для вывода товаров на сайте используется сниппет catalogView (см. snippets/catalogView/readme.txt).

Товары можно "вложить" в любой документ (категорию), выбрав в дереве документов. Т.е. категории каталога (структура) создается как и раньше документами MODx, но сами товары будут храниться в отдельной таблице БД.

Если товар из каталога Shopkeeeper, в чанк товара (сниппет catalogView) нужно вставить скрытое поле:

<input type="hidden" name="shk-catalog" value="1" />

Чтобы в модуле Shopkeeper (в админке) появилась ссылка "Каталог", нужно в конфигурации указать ID категории каталога (документ MODx) по умолчанию.
Также необходимо настроить конфигурацию плагина SaveToSHK — указать ID шаблона товаров и ID TV-параметра цены.

Важно!

На странице формирования заказа сниппет Shopkeeper должен вызываться раньше eForm.
В чанке формы заказа обязательно добавить скрытое поле
<input type="hidden" name="reportTpl" value="shopOrderReport" />
где shopOrderReport - это название чанка с шаблоном отчета (параметр &report сниппета eForm).
Сниппет можно вызывать на странице несколько раз, но корзина выводится только в месте первого вызова. Второй и последующие вызовы игнорируются. Если у Вас корзина на страницах каталога товаров находится в правой колонке шаблона, а на странице оформления заказа вызов сниппета вставлен в контент страницы, то на этой странице корзина будет выведена только в ценральной колонке (в правой вызов сниппета можно не убирать).
Рекомендуется использовать ЧПУ (семантические URL). В шаблонах сайта рекомендуется использовать <base href="[(site_url)]" /> (внутри <head>) и относительные пути.
Если чанки хранятся в файлах (используется команда @FILE:), проверьте кодировку этих файлов. Она должна быть такая же как у вашего сайта.
Рекомендуется установить плагин PHx (http://modx.com/extras/package/phx).
В чанке chunk_shopOrderFormWebUser.tpl для примера он используется для заполнения скрытых полей данными авторизованного пользователя.
Для вывода корзины (сниппета) в разных местах рекомендуется создавать разные шаблоны для страниц или использовать плагин PHx.
Если используется умножение цены товара на цену доп.параметра, в шаблоне информации о товаре (chunk_shopStuff.tpl и chunk_shopToCart.tpl) поле с ID товара (<input type="hidden" name="shk-id" value="[*id*]" />) должно быть выше доп.параметров по HTML-коду.
Рекомендуется имена TV-параметров и чанков писать на латинице.
Рекомендованная кодировка - UTF-8.
Для работы необходим PHP версии не ниже 5.0. На PHP 5.3 пока не тестировалось.
Для версии Shopkeeper 1.3.3 и выше для безопасности рекомендуется важные параметры сниппета Shopkeeper указывать в его свойствах в панели администрирования (строка «Параметры по умолчанию»). Эти параметры будут иметь приоритет. Пример: &changePrice=Изменять цену;string;1 &cartTpl=Чанк корзины;string;@FILE:chunk_shopCart.tpl

Все примеры прилагаются (папка shopkeeper/chunks/).

Примеры чанков в папке shopkeeper/chunks/

chunk_shopCart.tpl - чанк корзины. Может быть использован как значение параметра &cartTpl при вызове Shopkeeper. Чанк содержит сразу 3 шаблона - для пустой, заполненной расширенной и простой корзины.
chunk_shopCartRow.tpl - чанк шаблона строки с информацией товара в расширенной корзине.
chunk_shopCartRow2.tpl - -//- пример с картинкой (TV - image) и условием PHx.
chunk_shopStuff.tpl - чанк краткой информации о товаре. Может быть использован как значение параметра &tpl при вызове Ditto.
chunk_shopStuff_2.tpl - -//- пример с двумя ценами для одного товара (продажа и прокат).
chunk_shopToCart.tpl - может быть использован в шаблоне страницы подробного описания товара или можно вставлять вызов чанка {{shopToCart}} в визуальный редактор.
chunk_shopCartHelper.tpl - чанк шаблона "хелпера" - блока, который появляется для подтверждения действий.
chunk_additDataTpl.tpl - шаблон для доп. параметров товаров в корзине.
chunk_shopOrderForm.tpl - чанк форма оформление заказа. Может быть использован как значение параметра &tpl при вызове eForm.
chunk_shopOrderFormWebUser.tpl - чанк форма оформление заказа для зарегистрированных пользователей.
chunk_shopOrderReport.tpl - чанк письма с информацией о заказе. Может быть использован как значение параметра &report при вызове eForm.
chunk_shopOrderReportWebUser.tpl - чанк письма с информацией о заказе для зарегистрированных пользователей.
chunk_FormSignup.tpl - пример чанка с шаблоном формы регистрации для сниппета WebSignup.
chunk_weblogin.tpl - пример чанка с шаблоном формы авторизации сниппета WebLogin.
chunk_orderDataTpl.tpl - шаблон списка товаров в отчете о заказе ([+orderData+])