Введение
Привет! Меня зовут Павел и я Magento 2 бэкенд-разработчик. В прошлых частях саги о Magento 2 UI Components мы получили общие сведения о UI-компонентах, а также рассмотрели наиболее важные аспекты их конфигурации. Сегодня подробно коснемся некоторых вопросов модификации UI компонентов под свои нужды: изменение внешнего вида, поведения клиентской части, поведения серверной части и пр. Погнали!
Изменение внешнего вида
Начнем с наиболее простой части — изменение внешнего вида. У всех компонентов, имеющих какое либо визуальное представление, внешний вид задается шаблоном. Для примера возьмем шаблон компонента Input:
<input class="admin__control-text" type="text"
data-bind="
event: {change: userChanges},
value: value,
hasFocus: focused,
valueUpdate: valueUpdate,
attr: {
name: inputName,
placeholder: placeholder,
'aria-describedby': noticeId,
id: uid,
disabled: disabled,
maxlength: 255
}"/>Попробуем изменить его, для чего в нашем модуле создадим файл input.html в /view/adminhtml/web/templates/form/element/ нашего модуля и поместим туда следующий текст:
<span>White Rabbit</span><!-- добавим элемент для наглядности -->
<input class="admin__control-text" type="text"
data-bind="
event: {change: userChanges},
value: value,
hasFocus: focused,
valueUpdate: valueUpdate,
attr: {
name: inputName,
placeholder: placeholder,
'aria-describedby': noticeId,
id: uid,
disabled: disabled,
maxlength: 255
}"/>После чего в xml конфигурации, где объявлен наш компонент, укажем новый шаблон для компонента примерно таким образом:
<field name="white_rabbit" sortOrder="10" formElement="input">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
...
<item name="elementTmpl" xsi:type="string">RSHB_WhiteRabbit/form/element/input</item>
...
</item>
</argument>
</field>Очистим кэш и посмотрим, как изменился внешний вид компонента:
Вместе с кастомизацией шаблона мы можем расширить функционал UI-компонента, например, использовать в шаблоне knockout конструкции, которые будут обращаться к кастомным методам JS-компонента.
Кастомизация JS-компонента
Перейдем к более интересному моменту, а именно — к управлению поведением компонента в браузере пользователя. Как мы помним из предыдущей статьи, одной из частей UI-компонента является JS-виджет, который обеспечивает интерактивность компонента и отвечает за его поведение. Многие простейшие компоненты, такие как рассмотренный ранее input, не имеют своей реализации JS-компонента, вместо этого используя общую для всех реализацию abstract (которую можно найти в <magento_root>/vendor/magento/module-ui/view/base/web/js/form/element/abstract.js).
Поэтому, посмотрим на один из самых простых специализированных JS-компонентов — компонент Textarea:
define([
'./abstract'
], function (Abstract) {
'use strict';
return Abstract.extend({
defaults: {
cols: 15,
rows: 2,
elementTmpl: 'ui/form/element/textarea'
}
});
});Как мы видим, данный компонент расширяет реализацию abstract и вносит минимум изменений, а именно, задает размеры поля по умолчанию и его шаблон (тот самый, который мы обсуждали ранее).
У нас есть два пути модификации JS-компонента.
В первом случае, если мы хотим кардинально изменить поведение компонента, то можно написать новый JS-компонент, и указать его в xml конфигурации UI-компонента вместо использующегося по умолчанию. Для этого в нашем модуле создадим файл textarea.js по адресу view/adminhtml/web/js/form/element/, поместим туда модифицированный JS-компонент, а затем укажем его в xml конфигурации следующим образом:
<field name="white_rabbit" sortOrder="10" formElement="textarea">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
...
<item name="component" xsi:type="string">RSHB_WhiteRabbit/js/form/element/textarea</item>
...
</item>
</argument>
</field>Стоит заметить, что если нет нужды переписывать весь компонент, то достаточно его расширить, если вносимые изменения незначительны:
define([
'Magento_Ui/js/form/element/textarea'
], function (MagentoTextarea) {
'use strict';
return MagentoTextarea.extend({
sayHello: function () {
alert('Hello!');
return this;
},
});
});Так мы добавили нашему компоненту функцию sayHello которую можно использовать по своему смотрению.
Альтернативой полной замене JS-компонента может служить миксин к базовому JS-компоненту. В отличие от описанного ранее, данный метод поменяет поведение всех экземпляров компонента в системе, это следует держать в голове при выборе способа модификации JS-компонента.
Чтобы изменить поведение компонента при помощи миксина, необходимо создать миксин и указать его в requirejs. Для примера, применим миксин к базовому компоненту form, для чего поместим файл requirejs-config.js в /view/base/ нашего модуля:
var config = {
'config': {
'mixins': {
'Magento_Ui/js/form/form': {
'RSHB_WhiteRabbit/form-hook': true
}
}
}
};И далее разместим в /view/base/web/form-hook.js нашего модуля код мисксина:
define([], function () {
'use strict';
return function (Form) {
return Form.extend({
initialize: function () {
this._super();
console.log('The mixin from White Rabbit!');
}
});
}
});Таким образом, мы дополнили функцию инициализации компонента Form нашим кодом, и теперь каждый раз при выводе компонента Form в консоли будет выводиться строка “The mixin from White Rabbit!”.
PHP-классы
Теперь рассмотрим модификацию серверной части UI-компонента. Для этой цели служат кастомные классы компонентов и PHP-модификаторы (о последних поговорим позже).
Представим ситуацию, когда в базе у нас лежит значение int, которое определяет, включен некий параметр, или нет (значения 1 или 0, аналогично булевым true-false). При использовании стандартного класса column в гриде, мы увидим в колонке значения 1 или 0, в зависимости от значения в базе. Если мы хотим выводить эти значения как “Включено” или “Выключено”, нам необходимо подменить класс компонента, например:
<?php
...
class OnOff extends \Magento\Ui\Component\Listing\Columns\Column
{
/**
* OnOff constructor
*
* @param ContextInterface $context
* @param UiComponentFactory $uiComponentFactory
* @param array $components
* @param array $data
*/
public function __construct(
ContextInterface $context,
UiComponentFactory $uiComponentFactory,
array $components = [],
array $data = []
) {
parent::__construct($context, $uiComponentFactory, $components, $data);
}
/**
* @param array $dataSource
* @return array
*/
public function prepareDataSource(array $dataSource)
{
if (isset($dataSource['data']['items'])) {
foreach ($dataSource['data']['items'] as $id => $item) {
$whiteRabbit = $item['white_rabbit'];//Находим поле с нужным именем whi
$item['white_rabbit'] = (bool)$whiteRabbit ? 'On' : 'Off';
$dataSource['data']['items'][$id] = $item;
}
}
return $dataSource;
}
}Как мы видим, кастомный класс компонента меняет значения 1 и 0 на “Включено” и “Выключено”.
Стоит помнить, что при изменении значения в колонке нужно также изменять значения в фильтрах (если для колонки предусмотрен фильтр). Для этого следует указать Source класс со значениями, которые соответствуют значениям “Включено” и “Выключено” в нашем примере. Код Source класса:
<?php
...
class OnOff implements \Magento\Framework\Option\ArrayInterface
{
/**
* @return array
*/
public function toOptionArray(): array
{
return [['value' => 1, 'label' => __('On')], ['value' => 0, 'label' => __('Off')]];
}
/**
* @return array
*/
public function toArray(): array
{
return [0 => __('Off'), 1 => __('On')];
}
}Кстати, в М2 есть ряд предопределенных Source классов для наиболее распространенных задач, например, значения Yes/No, перечень категорий товаров и пр.
PHP-модификаторы
Еще одним любопытным способом изменить или дополнить поведение серверной части UI-компонента (а именно, его дата-провайдера) — PHP модификаторы. Они применяются в случаях, когда статическое объявление PHP класса в XML конфигурации по каким-то причинам не подходит, или может вызвать избыточное дублирование кода.
PHP модификатор должен реализовывать Magento\Ui\DataProvider\Modifier\ModifierInterface и должен содержать два метода: modifyData() и modifyMeta(). Посмотрим пример такого модификатора:
<?php
...
class WhiteRabbitModifier implements Magento\Ui\DataProvider\Modifier\ModifierInterface
{
/**
* {@inheritdoc}
*/
public function modifyMeta(array $meta)
{
$meta['test_fieldset_name'] = [
'arguments' => [
'data' => [
'config' => [
'label' => __('Label For Fieldset'),
'sortOrder' => 50,
'collapsible' => true
]
]
],
'children' => [
'test_field_name' => [
'arguments' => [
'data' => [
'config' => [
'formElement' => 'select',
'componentType' => 'field',
'options' => [
['value' => 'test_value_1', 'label' => 'Test Value 1'],
['value' => 'test_value_2', 'label' => 'Test Value 2'],
['value' => 'test_value_3', 'label' => 'Test Value 3'],
],
'visible' => 1,
'required' => 1,
'label' => __('Label For Element')
]
]
]
]
]
];
return $meta;
}
/**
* {@inheritdoc}
*/
public function modifyData(array $data)
{
return $data;
}
}Как мы видим, при помощи модификатора можно изменить данные и мета-данные UI-компонента.
Для того, чтобы модификатор заработал, его нужно добавить в пул модификаторов дата-провайдера через di.xml таким способом:
<virtualType name="RSHB\WhiteRabbit\DataProvider\Modifier\WhiteRabbitPool" type="Magento\Ui\DataProvider\Modifier\Pool">
<arguments>
<argument name="modifiers" xsi:type="array">
<item name="modifier_name" xsi:type="array">
<item name="class" xsi:type="string">RSHB\WhiteRabbit\Modifier\WhiteRabbitModifier</item>
<item name="sortOrder" xsi:type="number">10</item>
</item>
</argument>
</arguments>
</virtualType>
<type name="RSHB\WhiteRabbit\Ui\DataProvider\WhiteRabbitDataProvider">
<arguments>
<argument name="pool" xsi:type="object">RSHB\WhiteRabbit\DataProvider\Modifier\WhiteRabbitPool</argument>
</arguments>
</type>Заключение
Мы рассмотрели основные аспекты модификации UI-компонентов под свои нужды. На этом цикл статей об UI-компонентах я считаю закрытым, возникающие вопросы по нюансам работы можно задавать в комментариям к соответствующим статьям.
Пишите код с удовольствием! До встречи.