Центр документации
Карта сайта

Создай визитку сам!


Самоучитель по интеграции дизайна и настройке Amiro.CMS на примере демонстрационной версии пакета Визитка »


Пример интеграции со службой доставки

В настоящем примере будет рассмотрен процесс создания дистрибутива модуля интеграции Amiro.CMS и службы доставки.

Цель - вывести на странице оформления заказа новую службу доставки. Стоимость доставки данная служба должна получать динамически через обращение к собственному веб-сервису.

С помощью "Генератора Решений" создается основа кода дистрибутива. Для этого на форме создания дистрибутива необходимо задать ID дистрибутива, имя дистрибутива, указать название конфигурации, и выставить тип дистрибутива "Служба Доставки".

Тип дистрибутива "Служба Доставки" доступен в модуле "Генератор Решений" начиная с версии 1.4.
Если вы используете более раннюю версию модуля, вам потребуется обновить ее до актуальной.

Статусное сообщение об успешном создании нового дистрибутива укажет на место расположения файлов дистрибутива.

Структура файлов, созданных в дистрибутиве генератором.

_local/modules/data/inst_devtool/my.delivery_service/

code/

AmiClean_MyBestDelivery_Adm.php - Функционал модуля для панели управления. Пустые классы-наследники.
AmiClean_MyBestDelivery_Meta.php - Мета-файл конфигурации. Содержит заголовки и режимы работы.
AmiClean_MyBestDelivery_Rules.php - Файл для модификации настроек модуля. Пустой класс-наследник.
AmiClean_MyBestDelivery_Service.php - Класс веб-сервиса службы доставки. Содержит минимальный функционал.

distrib/

configs/

ami_clean/

my_best_delivery/

code/

Заготовки кода экземпляра модуля
--modId--_Adm.php

--modId--_Rules.php
--modId--_Service.php

db/

declaration/

Файлы для объявления и настройки модуля
declaration.php

options.php
properties.php
rules.php

icons/

Иконка модуля для панели управления
--modId--.gif

locales/

Языковые переменные панели управления
--modId--_client.lng

--modId--_help.lng
--modId--_messages.lng 

rules/

Заголовки и значения настроек модуля
--modId--_rules_captions.lng

--modId--_rules_values.lng 

templates/

commonEventHandlersRegistration.php - Код объявления обработчиков событий
commonEventHandlersDeclaration.php - Код обработчика событий

eshop_order.lng - Языковые переменные добавляемые в системный eshop_order.lng
eshop_shipping_fields.lng - Языковые переменные добавляемые в системный eshop_shipping_fields.lng
eshop_shipping_fields.tpl - Языковые переменные добавляемые в системный eshop_shipping_fields.tpl
install_after.php - Код установки модуля
uninstall_after.php - Код деинсталляции модуля

Файл с манифестом дистрибутива
manifest.xml

 

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

_local/modules/data/inst_devtool/my.delivery_service/manifest.xml

Вносятся изменения в блок information, указывается корректное название дистрибутива на русском и английском языках.

<?xml version="1.0" encoding="utf-8"?>
<package id="my.delivery_service" version="1.0" manifestVersion="1.0">
    <information lang="en">
        <title>The Best Delivery Service Ever</title>
        <description></description>
        <author>Author</author>
        <source>http://my.website.com/</source>
    </information>
    <information lang="ru">
        <title>Самая Лучшая Служба Доставки</title>
        <description></description>
        <author>Автор</author>
        <source>http://my.website.ru/</source>
    </information>
    <installation>
        <install hypermodule="ami_clean" configuration="my_best_delivery" version="1.0" />
    </installation>
    <dependencies>
        <dependency hypermodule="ami_clean" version="1.0" />
    </dependencies>
</package>

 

_local/modules/data/inst_devtool/my.delivery_service/code/AmiClean_MyBestDelivery_Meta.php

Вносятся изменения в описание модуля, заголовки модуля и меню.

<?php
/**
 * AmiClean/MyBestDelivery configuration metadata.
 *
 * @package    Config_AmiClean_MyBestDelivery
 * @subpackage Meta
 */
class AmiClean_MyBestDelivery_Meta extends AMI_HyperConfig_Meta{
    /**
     * Version
     *
     * @var string
     */
    protected $version = '1.0';
    /**
     * Only one instance per config allowed
     *
     * @var bool
     */
    protected $isSingleInstance = TRUE;
    /**
     * Array having locales as keys and captions as values
     *
     * @var array
     */
    protected $aTitle = array(
        'en' => 'The Best Delivery Service Ever',
        'ru' => 'Самая Лучшая Служба Доставки'
    );
    /**
     * Array having locales as keys and meta data as values
     *
     * @var array
     */
    protected $aInfo = array(
        'en' => array(
            'description' => 'Example of Amiro.CMS integration with delivery service',
            'author'      => '<a href="http://my.website.com/" target="_blank">Author</a>'
        ),
        'ru' => array(
            'description' => 'Пример интеграции Amiro.CMS со службой доставки',
            'author'      => '<a href="http://my.website.ru/" target="_blank">Автор</a>'
        )
    );
    /**
     * Array containing captions struct
     *
     * @var array
     */
    protected $aCaptions = array(
        '' => array(
            'header' => array(
                'obligatory' => TRUE,
                'type' => self::CAPTION_TYPE_STRING,
                'locales' => array(
                    'en' => array(
                        'name' => 'Header',
                        'caption' => 'The Best Delivery Admin',
                    ),
                    'ru' => array(
                        'name' => 'Заголовок',
                        'caption' => 'Управление Лучшей Доставкой',
                    ),
                ),
            ),
            'menu' => array(
                'obligatory' => TRUE,
                'type' => self::CAPTION_TYPE_STRING,
                'locales' => array(
                    'en' => array(
                        'name' => 'Menu caption',
                        'caption' => 'The Best Delivery Admin',
                    ),
                    'ru' => array(
                        'name' => 'Заголовок для меню',
                        'caption' => 'Управление Лучшей Доставкой',
                    ),
                ),
            ),
            'description' => array(
                'obligatory' => FALSE,
                'type' => self::CAPTION_TYPE_TEXT,
                'locales' => array(
                    'en' => array(
                        'name' => 'Admin interface start page module description',
                        'caption' => 'Example of Amiro.CMS integration with delivery service',
                    ),
                    'ru' => array(
                        'name' => 'Описание модуля для стартовой страницы интерфейса администратора',
                        'caption' => 'Пример интеграции Amiro.CMS со службой доставки',
                    ),
                ),
            ),
        ),
    );
}


Следующая языковая переменная отвечает за то, как название доставки будет отображаться на форме оформления заказа для пользователя.
_local/modules/data/inst_devtool/my.delivery_service/distrib/configs/ami_clean/my_best_delivery/eshop_shipping_fields.lng

%%_field%en%%
The Best Delivery
%%_field%ru%%
Лучшая Доставка

Для изменения шаблонного названия доставки в панели управления, производится замена строки "MyShipping" в файлах

_local/modules/data/inst_devtool/my.delivery_service/distrib/configs/ami_clean/my_best_delivery/install_after.php
_local/modules/data/inst_devtool/my.delivery_service/distrib/configs/ami_clean/my_best_delivery/uninstall_after.php

define('CUSTOM_SHIPPING_NAME', 'Лучшая Доставка');

а так же в файле 
_local/modules/data/inst_devtool/my.delivery_service/distrib/configs/ami_clean/my_best_delivery/commonEventHandlersDeclaration.php

$shipping_name = 'Лучшая Доставка';

После данных изменений можно попробовать установить модуль интеграции. Это возможно сделать непосредственно из списка модуля "Генератор Решений", воспользовавшись действием "Установить".

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

Это можно сделать на форме редактирования способа доставки в модуле "Доставка".

Эту процедуру можно автоматизировать, добавив код добавления создаваемого метода доставки в набор полей по умолчанию в файле
_local/modules/data/inst_devtool/my.delivery_service/distrib/configs/ami_clean/my_best_delivery/install_after.php

// Получаем id набора по умолчанию
$oItem = AMI::getResourceModel('eshop_shipping_types/table')->getItem();
$oItem->addSearchCondition(
    array(
        'lang' => AMI_Registry::get('lang_data'),
        'is_default' => 1,
        'hidden' => 0
    )
);
$oItem->load();
$typeId = $oItem->getId();
 
// Создаем новый метод доставки в наборе по умолчанию
$oItem = AMI::getResourceModel('eshop_shipping_methods/table')->getItem();
$oItem->setData(
    array(
        'header' => CUSTOM_SHIPPING_NAME,
        'fields' => array('00', '01', CUSTOM_SHIPPING_CODE),
        'types'  => array($typeId)
    )
);
$oItem->save();

А изменяя значения передаваемые в поле fields при создании метода доставки, можно изменять набор полей выводимый на форме оформления заказа при выборе данного способа доставки.

Перейдя на публичную часть сайта и положив товар в корзину можно приступать к оформлению заказа.

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

Данные о стоимости доставки принимаются от веб-сервиса модуля. За получение и отображение данных отвечает небольшой блок JavaScript, расположенный в файле
_local/modules/data/inst_devtool/my.delivery_service/distrib/configs/ami_clean/my_best_delivery/eshop_shipping_fields.php 

При внесении правок в уже установленном модуле интеграции, правки вносятся в шаблон templates/eshop_shipping_fields.tpl

Для демонстрации возможности передачи данных с формы в сервис расчета стоимости доставки, на форму добавлено поле my_shipping_data_custom. Если в данное поле будет введено числовое значение, оно будет использоваться в качестве стоимости доставки. Иначе стоимость доставки будет взята случайная.

<script type="text/javascript">
function updateMyShippingDeliveryCost(){
    // Если выбран наш способ доставки
    if(AMI.$("[data-ami-custom-shipping$='|']").attr('checked')){
        // Читается значение поля my_shipping_data_custom
        var my_shipping_data = AMI.$('[name=my_shipping_data_custom]').val();
        // Отправлются данные веб-сервису модуля
        AMI.$.getJSON(window.frontBaseHref + 'ami_service.php?service=ami_webservice&action=my_shipping.get_delivery_cost&appToken=app_token_public&version=1.1&modId=&my_shipping_data=' + my_shipping_data, {}, function(data){
            if(typeof(data.data.errorCode) != 'undefined'){
                switch(data.data.errorCode){
                    case 'OK':
                        // В случае корректного ответа обновляются данные о стоимости доставки на странице
                        var deliveryCost = data.data.delivery_cost;
                        var Order = AMI.Eshop.Order;
                        var key = Order.getCurrentShippingKey();
                        var Total = Order.prices_ajax_response_array[key].total;
                        var driver = Order.prices_ajax_response.drivers[Order.payment_method];
                        if (driver){
                            driver.pay_amount = AMI.Eshop.formatMoney(Total.price_value + deliveryCost);
                        }
                        Total.grand_total = AMI.Eshop.formatMoney(Total.price_value + deliveryCost);
                        Total.shipping_value = deliveryCost;
                        Total.shipping = AMI.Eshop.formatMoney(deliveryCost);
                        Order.toggleResultToHidden();
                        Order.updatePricesFromAjaxData();
                        Order.toggleResultToVisible();
                        break;
                    case 'ERR_FAIL':
                        // В случае ошибки - выводится сообщение
                        alert(data.data.errorMessage);
                        break;
                }
            }else{
                alert('Invalid response format');
            }
        });
    }
}
 
// Добавляется пересчет стоимости заказа при смене доставки и изменении значения поля my_shipping_data_custom
AMI.$("[name=get_type]").click(updateMyShippingDeliveryCost);
AMI.$("[name=my_shipping_data_custom]").change(updateMyShippingDeliveryCost);
 
</script>

На стороне сервера за логику расчета стоимости доставки отвечает метод handleGetDeliveryCostAction класса AmiClean_MyBestDelivery_Service:

_local/modules/data/inst_devtool/my.delivery_service/code/AmiClean_MyBestDelivery_Service.php

public function handleGetDeliveryCostAction($name, array &$aEvent){
    $oRequest = AMI::getSingleton('env/request');
    $data = $oRequest->get('my_shipping_data');
    if(strlen($data) && !(int)$data){
        // Если передано не числовое значение в поле my_shipping_data, то ответ - ошибка
        $this->oWebService->error(AmiClean_Webservice_Service::ERR_FAIL, 'Invalid data value');
    }
 
    // Здесь может быть расположен код вычисления стоимости доставки
    // ...
 
    // Например, возврат переданного или случайного значения
    $aEvent['delivery_cost'] = (int)$data ? $data : rand(100, 999);
 
    $this->oWebService->ok($aEvent);
    return $aEvent;
}

Если для расчета стоимости доставки необходимо обращение к стороннему сервису, рекомендуется выполнять его из сервисного класса с использованием возможностей AMI_HttpRequest.

Установка и настройка Руководство пользователя Интеграция дизайна Разработчикам (API)
 2000 – 2021 © Amiro.CMS Все права защищены.