Разработка модулей под OpenCart 4

 

Шпаргалка по изменениям в OpenCart 4, которые необходимо учесть при разработке модулей.

Раньше я делал общий обзор OpenCart 4. А вот более тщательное ознакомление с четверкой я начал с адаптации простого модуля, в котором нету ни модификаций (я буду использовать vQmod), ни событий. Честно говоря, я эту статью писал дольше, чем непосредственно адаптировал модуль. Так что первое впечатление такое: адаптация прошла достаточно легко. Так что пора бы уже и все остальные модули подтягивать. А вот по мере этого буду добавлять дополнительные сведения.

 

Opencart

Основные изменения в коде стандартного модуля

Изменения в контроллере

OpenCart 3 OpenCart 4
class ControllerExtensionModuleAccount extends Controller { namespace Opencart\Admin\Controller\Extension\Opencart\Module;
class Account extends \Opencart\System\Engine\Controller {
protected function validate() { public function save(): void {
  // ...
  $this->response->addHeader('Content-Type: application/json');
  $this->response->setOutput(json_encode($json));
}
private $error = array(); Больше не нужно. Все ошибки обрабатываются сразу в методе save()
if (isset($this->error['warning'])) {
  $data['error_warning'] = $this->error['warning'];
} else {
  $data['error_warning'] = '';
}

Не нужно. Обработка ошибок происходит в методе save(). См также Обработка ошибок

if (($this->request->server['REQUEST_METHOD'] == 'POST') && $this->validate()) { Больше не используется. Сохранение формы происходит путем отправки AJAX-запроса к методу save()
$data['action'] = $this->url->link('extension/module/account', 'user_token=' . $this->session->data['user_token'], true);

// 4.0.0.0
$data['save'] = $this->url->link('extension/opencart/module/account|save', 'user_token=' . $this->session->data['user_token']);

// 4.0.2.0
$data['save'] = $this->url->link('extension/opencart/module/account.save', 'user_token=' . $this->session->data['user_token']);

*Изменения в построении путей влияет на любые ссылки внутри модуля. Ну это и так понятно.

$data['cancel'] = $this->url->link('marketplace/extension', 'user_token=' . $this->session->data['user_token'] . '&type=module', true); $data['back'] = $this->url->link('marketplace/extension', 'user_token=' . $this->session->data['user_token'] . '&type=module');
   
$this->load->model('extension/dashboard/map'); $this->load->model('extension/opencart/dashboard/map');
$results = $this->model_extension_dashboard_map->getTotalOrdersByCountry(); $results = $this->model_extension_opencart_dashboard_map->getTotalOrdersByCountry();
if (isset($this->request->post['module_account_status'])) {
  $data['module_account_status'] = $this->request->post['module_account_status'];
} else {
  $data['module_account_status'] = $this->config->get('module_account_status');
}
$data['module_account_status'] = $this->config->get('module_account_status');

В модели

Добавляются неймспейсы.

OpenCart 3 OpenCart 4
class ModelExtensionDashboardMap extends Model { namespace Opencart\Admin\Model\Extension\Opencart\Dashboard;
class Map extends \Opencart\System\Engine\Model {

Во вьюшке

В OpenCart 4.0.0.0 был FontAwesome 5.15.4 а в OpenCart 4.0.2.0 FontAwesome 6.1.1. Это влияет на классы иконок.

Далее я разбираю diff между OpenCart 3.0.3.8 и сразу OpenCart 4.0.2.0

Измнения во вьюшке, которые нужно учесть при разработке модулей под OpenCart 4

OpenCart 3 OpenCart 4
pull-right float-end
data-toggle="tooltip" data-bs-toggle="tooltip"
<i class="fa fa-save"></i>

<!-- 4.0.0.0 -->
<i class="fas fa-save"></i>

<!-- 4.0.2.0 -->
<i class="fa-solid fa-save"></i>

{{ cancel }}
{{ button_cancel }}
{{ back }}
{{ button_back }}
<ul class="breadcrumb"> <ol class="breadcrumb">
<li><a href="{{ breadcrumb.href }}">{{ breadcrumb.text }}</a></li> <li class="breadcrumb-item"><a href="{{ breadcrumb.href }}">{{ breadcrumb.text }}</a></li>
{% if error_warning %}
<div class="alert alert-danger alert-dismissible"><i class="fa fa-exclamation-circle"></i> {{ error_warning }}
<button type="button" class="close" data-dismiss="alert">&times;</button>
</div>
{% endif %}{% if error_warning %}
— (AJAX)
<div class="panel panel-default"> <div class="card">
<div class="panel-heading">
<h3 class="panel-title"><i class="fa fa-pencil"></i> {{ text_edit }}</h3>
</div>

<!-- 4.0.0.0 -->
<div class="card-header"><i class="fas fa-pencil-alt"></i> {{ text_edit }}</div>

<!-- 4.0.2.0 -->
<div class="card-header"><i class="fa-solid fa-pencil"></i> {{ text_edit }}</div>

<div class="panel-body"> <div class="card-body">
<form action="{{ action }}" method="post" enctype="multipart/form-data" id="form-module" class="form-horizontal">

<form id="form-module" action="{{ save }}" method="post" data-oc-toggle="ajax">

* Если пропустить oc-toggle=»ajax», то форма обработается по старинке с полной загрузкой страницы (по крайней мере в версии 4.0.0.0). Хотя сам .alert в bootstrap 5 немножко изменился.

<div class="form-group"> <div class="row mb-3">
control-label col-form-label
<select name="module_account_status" ... <!-- 4.0.2.0 -->
<input type="checkbox" name="module_account_status" ...

Пути в AJAX-запросах

url: 'index.php?route=extension/imagescanner/module/imagescanner/getNotUsedImagesList

<!-- 4.0.0.0 -->
url: 'index.php?route=extension/imagescanner/module/imagescanner|getNotUsedImagesList

<!-- 4.0.2.0 -->
url: 'index.php?route=extension/imagescanner/module/imagescanner.getNotUsedImagesList

Пути к изображениям

var img_loader = new Image().src='view/image/imagescanner-loader.gif';

var img_loader = new Image().src='extension/imagescanner/admin/view/image/imagescanner-loader.gif';

А оно запрашивает: http://opencart-4000.loc/admin/extension/imagescanner/admin/view/image/imagescanner-loader.gif

Значит надо указать полный путь к файлу:
var img_loader = new Image().src='{{ constant('HTTP_CATALOG') }}extension/imagescanner/admin/view/image/imagescanner-loader.gif';

Обработка ошибок

Чтобы поля с ошибками подсвечивались и к ним были пояснительные подписи, первым действием во вьюшке необходимо вписать пустые контейнеры для текстов ошибок.

<div id="error-field" class="invalid-feedback"></div>

Далее, при обработке формы (к примеру, товара) по AJAX можно получить следующий формат ответа:
{
  "error": {
    "name_1": "Product Name must be greater than 1 and less than 255 characters!",
    "keyword_0_1": "SEO URL keyword required!",
   "warning": "Warning: Please check the form carefully for errors!"
  }
}

Затем оно будет универсально обработано через admin/view/javascript/common.js

$(document).on('submit', 'form[data-oc-toggle=\'ajax\']', function (e) {
...
success: function (json) {
  $('.alert-dismissible').remove();
  $(element).find('.is-invalid').removeClass('is-invalid');
  $(element).find('.invalid-feedback').removeClass('d-block');
  console.log(json);
  if (json['redirect']) {
    location = json['redirect'];
  }
  if (typeof json['error'] == 'string') {
    $('#alert').prepend('<div class="alert alert-danger alert-dismissible"><i class="fas fa-exclamation-circle"></i> ' + json['error'] + ' <button type="button" class="btn-close" data-bs-dismiss="alert"></button></div>');
  }
  if (typeof json['error'] == 'object') {
    if (json['error']['warning']) {
      $('#alert').prepend('<div class="alert alert-danger alert-dismissible"><i class="fas fa-exclamation-circle"></i> ' + json['error']['warning'] + ' <button type="button" class="btn-close" data-bs-dismiss="alert"></button></div>');
    }
    for (key in json['error']) {
      $('#input-' + key.replaceAll('_', '-')).addClass('is-invalid').find('.form-control, .form-select, .form-check-input, .form-check-label').addClass('is-invalid');
      $('#error-' + key.replaceAll('_', '-')).html(json['error'][key]).addClass('d-block');
    }
  }
  if (json['success']) {
    $('#alert').prepend('<div class="alert alert-success alert-dismissible"><i class="fas fa-check-circle"></i> ' + json['success'] + ' <button type="button" class="btn-close" data-bs-dismiss="alert"></button></div>');
    // Refresh
    var url = $(form).attr('data-oc-load');
    var target = $(form).attr('data-oc-target');
     if (url !== undefined && target !== undefined) {

      $(target).load(url);
    }
  }
  // Replace any form values that correspond to form names.
  for (key in json) {
    $(element).find('[name=\'' + key + '\']').val(json[key]);
  }
},
...

TypeError: Cannot access offset of type string on string in при обработке ошибок

В js при обработке ответа AJAX-запроса делается разграничение между полученной строкой и объектом. Все потому, что в простейшем «модуле» (к примеру, account) в ошибки попадает всего лишь строка с текcтом без лишних заморочек. И вот я скопипастил оттуда, а потом увидел, что в товарах идет иначе, и скопипастил кусок кода отсюда. В итоге напоролся на ошибку: TypeError: Cannot access offset of type string on string in …

$json['error'] = $this->language->get('error_text'); // В простейшем модуле присваивается строка
...
if (isset($json['error']) && !isset($json['error']['warning'])) {
  $json['error']['warning'] = $this->language->get('error_warning'); // Пытается строке присвоить индекс массива, а это PHP 8...
}

Собственные библиотеки в составе модуля

Если ваш модуль использует библиотеку, которая обычно загружалась в system/library, то сейчас при распаковке архива она попадет в extnension/modulecode/system/library/.

OpenCart автоматически создает пространства имен, как для контроллеров с моделями, так и для бибилотек:

            [Opencart\Admin\Controller\Extension\Imagescanner] => Array
                (
                    [directory] => .../opencart-4000.loc/extension/imagescanner/admin/controller/
                    [psr4] => 
                )

            [Opencart\Admin\Model\Extension\Imagescanner] => Array
                (
                    [directory] => .../opencart-4000.loc/extension/imagescanner/admin/model/
                    [psr4] => 
                )

            [Opencart\System\Extension\Imagescanner] => Array
                (
                    [directory] => .../opencart-4000.loc/extension/imagescanner/system/
                    [psr4] => 
                )

 

// 4.0.2.0
[Opencart\System\Library\Extension\Imagescanner] => Array
    (
        [directory] => D:/Dev/OpenServer/domains/opencart-4021.loc/extension/imagescanner/system/library/
        [psr4] => 
    )

Обратите внимание, что вариант именования класса библиотеки ImageScanner при подключении  превратится в image_scanner.php (в system/engine/autoloader.php). Тогда как Imagescanner будет соответствовать imagescanner.php. Это при том, что  в контроллере название класса в стиле CamelCase работает ок. А вот почему так — это уже отдельная история.

В файле библиотеки

Зададим пространство имен:
// 4.0.0.0
namespace Opencart\System\Extension\Modulecode\Library;
// 4.0.2.0
namespace Opencart\System\Library\Extension\Imagescanner;

Называем класс:
class Yourclassname {

В файле контроллера

Создаем экземпляр класса библиотеки в нашем контроллере:

// 4.0.0.0
$this->instance = new \Opencart\System\Extension\Modulecode\Library\Yourclassname();
// 4.0.2.0
$this->stdelog = new \Opencart\System\Library\Extension\Imagescanner\Stdelog('imagescanner');

С другой стороны прекрасно отработает и по старинке:
require_once DIR_EXTENSION . 'modulecode/system/library/modulecode.php';
$this->instance = new Yourclassname(); // и не париться :)

 

Папка модуля

На примере присуствутющей после установки папки extension/opencart (где сложены все дефолтные модули) казалось, что в OpenCart 4 появилось понятие «папка поставщика». Но потом выяснилось (см обсуждение на форуме — https://opencartforum.com/topic/183709-razrabotka-moduley-pod-opencart-4-ili-pochemu-daniel-tak-nenavidit-razrabotchikov/), что при попытке установить в ту же папку другой свой же модуль, оно не работает. В общем, оказалось, что это просто папка модуля или, если хотите, папка установочного пакета. К примеру, шаблоны могут запихать файлы всех своих модулей в одну папку по аналогии с OpenCart Default Extensions).

Кстати, если в установочном архиве будут нестандартные пути к файлам (я к примеру, пробовал modulecode/library/file.php на 4.0.0.0), то при удалении модуля из админки папка модуля не удаляется, хотя все стандартные файлы и папки оттуда удалены. То есть, это может создать проблемы при обновлении модуля, ведь в существующую папку модуля установщик записывать не хочет.

И еще с этой папкой есть один приятный момент: чтобы упаковать модуль, достаточно просто скопировать папку и заархивировать. Больше не нужно шустрить все папки и копировать каждый файл по отдельности.

P.S.

Обзор пока что не полный. Буду дописывать…

 

 

Добавить комментарий