Ajax в компонентах Bitrix24

В этой статье рассмотрим один из способов организации взаимодействия браузера с сервером c помощью стандартного метода BX.ajax.runComponentAction.

Продолжаем разработку компонента списков. В статье JavaScript в компонентах Bitrix24 мы сделали js скрипт, который описывает поведение элементов меню, но не реализовали отправку запросов на сервер. Этим сейчас и займёмся.

Шаг 1 Подготовка контроллера компонента

Для определения действия (action), к которому обращается метод BX.ajax.runComponentAction, класс компонента должен реализовать интерфейс Bitrix\Main\Engine\Contract\Controllerable.

<?php
  
namespace Aclips\Components;

use Bitrix\Main\Engine\Contract\Controllerable;

class BaseGridComponent extends \CBitrixComponent implements Controllerable
{
    ...
    
    public function configureActions()
    {
        // TODO: Implement configureActions() method.
    }
      
    ...
}

После этого можно добавлять действия в контроллер компонента. Названия методом действий должны иметь суффикс action.

public function deleteAction(int $id): array
{
    $response = [];
  
    ...
      
    return $response;
}

public function createAction(array $params): array
{
    $response = [];
  
    ...
      
    return $response;
}

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

Возврат ошибки через исключение

public function createAction(array $params): array
{
    $response = []; 
    ...
    
    throw new \Exception('Не заполнены обязательные поля');
    
    return $response;
} 

Таким образом можно передать не более 1 сообщения об ошибке (да и исключение — это немного не про то).

Возврат ошибки в результирующем массиве

public function createAction(array $params): array
{
    $response = []; 
    ...
    
    $response = [
      	'error_messages' => [
        	'Не заполнено обязательное поле 1',
          	'Не заполнено обязательное поле 2',
          	...
        ]
    ];
    
    return $response;
} 

Из недостатков:

  • Требуются дополнительные проверки на стороне клиента;
  • статус ответа будет равен значению success.

Возврат ошибок через реализацию интерфейса \Bitrix\Main\Errorable

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

<?php
  
namespace Aclips\Components;

...

use Bitrix\Main\Engine\Contract\Controllerable;
use Bitrix\Main\Error;
use Bitrix\Main\Errorable;
use Bitrix\Main\ErrorCollection;
use Bitrix\Main\ErrorableImplementation;

class BaseGridComponent extends \CBitrixComponent implements Controllerable, Errorable
{
  	// Трейт для реализации методов, требыемых интерфейсом Errorable
  	use ErrorableImplementation;
    ...
    
    public function configureActions()
    {
        // TODO: Implement configureActions() method.
    }
      
    ...
      
    public function createAction(array $params): array
	{
      	// Инициализация коллекции ошибок
      	$this->errorCollection = new ErrorCollection();
      	
      	
    	$response = []; 
    	
      	$this->errorCollection->setError(new Error('Не заполнено обязательное поле 1'));
      	$this->errorCollection->setError(new Error('ОНе заполнено обязательное поле 2'));
    
      	// Если ошибок нет выполняем какое-то действие
      	if(! $this->hasErrors()) {
        	...
        }
      
    	return $response;
	} 
}

Шаг 2 Описание действий

Описываем логику, выполняемую в каждом из действий согласно задачам. Рассмотрим на примере удаления пользователя.

Метод действия удаления
public function deleteUserAction(int $userId): bool
{
      // Инициализация коллекции ошибок
      $this->errorCollection = new ErrorCollection();

	  $result = \CUser::Delete($userId);

      if(!$result) {
        $this->errorCollection->setError(new Error('Произошла ошибка при удалении пользователя'));
        return false;
      }
  
  	  return true;
} 

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

Шаг 3 Отправка запроса

После подготовки компонента к работе с запросами и создания действий, эти действия надо вызвать. Возвращаемся к объекту из файла script.js и изменяем removeUser следующим образом

BX.namespace('Aclips.BaseGrid.List')

BX.Aclips.BaseGrid.List = {
	...
  
    removeUser: function (userId, callback) {
        BX.ajax.runComponentAction('aclips:base.grid', 'removeUser', {
            mode: 'class',
            data: {
                userId: userId,
            }
        }).then(response => {
            // Выполняется при успешном ответе
            if (callback && {}.toString.call(callback) === '[object Function]') {
                callback()
            }
        }, reject => {
            // Выполняется при не успешном ответе
            let errorMessages = reject.errors.map(e => e.message).join('\n')
            alert(errorMessages)
        })
    },
  
    ...
}

Метод BX.ajax.runComponentAction принимает 3 параметра:

  • component — название компонента, в котором размещено действие (компонент должен реализовать интерфейс Controllerable);
  • action — название действия без суффикса (если имя метода removeUserAction, то указываем removeAction);
  • config — объект параметров. Подробно со всеми возможными параметрами можно ознакомиться в документации, особое внимание уделим параметру data — ключи объекта должны полностью повторять названия параметров действия в компоненте.

Шаг 4 проверка

Проверим корректность работы метода удаления сотрудника.

Удаление пользователя с ошибкой
Удаление пользователя без ошибки

Итог

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

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