Magento 2. Ui Grid

Абсолютно всі користувачі Magento 2 звернули увагу на оновлений інтерфейс адмін панелі. У цій статті я хотів би розглянути новий інтерфейс Grid сторінок і головне, як можна створити свою власну Grid сторінку з докладним описом.

Зміст
Огляд
Створення экстеншена
Ui Component
Editor
Columns
Examples
Необхідно пам'ятати
Висновок
Огляд
Magento 2 має 2ма типами Grid сторінок. Тим, до яких ми звикли в Magento 1 і абсолютно новим, Ui Grid, якщо я можу їх так називати, які засновані на нових Ui елементах.



Це досить стандартна grid станиця, вона практично така ж як в Magento 1, а тепер перейдемо до Ui Grid.



Ви можливо помітили багато нових елементів на цій сторінці, у той час як Magento 1 екран зазвичай виглядає ось так:



Куди поділися фільтри, ви можете запитати, щоб їх побачити, просто натисніть кнопку «Filters».



Як адміністратор ви можете не тільки переглядати записи з бази даних, як це було в Magento 1, але і модифікувати список стовпців, їх позиції, список доступних фільтрів та багато іншого прямо з адмін панелі.



До речі кажучи, це так само працює на EAV Grid сторінках (зразок списку товарів або списку користувачів). Додавши новий атрибут, ви можете додати колонку з його значенням.

Ви так само можете зберегти ваші зміни для того, щоб повернутися до них пізніше, або просто перемикатися між різними збереженими станами для виконання тих чи інших дій.



Якщо у вас на сторінці дуже багато записів, а ви прокрутили сторінку досить далеко, то заголовки полів і необхідні кнопки будуть відображатися зверху.



Інша приємна особливість це повнотекстовий пошук на grid сторінках (можете подивитися CMS grid сторінку або сторінку зі списком користувачів).



Ви можете ввести будь-який текст туди і якщо знайшлася хоч 1 запис з аналогічним контентом, то вона буде показана.

Ще 1 крута річ – це нарешті додані колонки з зображеннями. Ви можете побачити приклад такого стовпця на сторінці зі списком продуктів. За кліком на зображенні показана повна версія зображення цього продукту.



Остання фіча, про яку я хочу розповісти – це інлайн редактор. Іншими словами, тепер якщо ви натиснете на сходинку, то ви зможете її відредагувати не відкриваючи сторінку редагування.



Ви так само можете це робити через редагування декількох записів (mass action). Просто позначте рядок і виберіть «edit» в меню «Дії».



Завдяки новій архітектурі адмін панелі Magento, всі ці дії не вимагають перезавантаження сторінок. Це означає, що ви побачите результат ваших дій практично миттєво.

Створення экстеншена
Всі нові фічі виглядають багатообіцяюче, але як їх використовувати? Це трохи складне питання по причині не достатку деталей, повних прикладів коду в офіційній документації (вона зараз в процесі заповнення, що добре). Це б допомогло розробникам впроваджувати нові фічі швидше і повністю розуміти що ж робить їх код, а не в сліпу копіювати з гугла. Для того, щоб виправити це, давайте дивитися повний процес впровадження Ui Grid в абстрактний экстеншен.

Перш за все, наш экстеншен повинен мати приблизно таку структуру:

  • {NameSpace}/{ExtensionName}/registration.php
  • {NameSpace}/{ExtensionName}/etc/module.xml
  • {NameSpace}/{ExtensionName}/etc/di.xml
  • {NameSpace}/{ExtensionName}/etc/acl.xml
  • {NameSpace}/{ExtensionName}/etc/adminhtml/menu.xml
  • {NameSpace}/{ExtensionName}/etc/adminhtml/routes.xml
  • {NameSpace}/{ExtensionName}/Model/{Посилання}.php
  • {NameSpace}/{ExtensionName}/Model/ResourceModel/{Посилання}.php
  • {NameSpace}/{ExtensionName}/Model/ResourceModel/{Посилання}/Collection.php
  • {NameSpace}/{ExtensionName}/Model/ResourceModel/{Посилання}/Grid/Collection.php
  • {NameSpace}/{ExtensionName}/Setup/InstallSchema.php
  • {NameSpace}/{ExtensionName}/Controller/Adminhtml/Index/Index.php
  • {NameSpace}/{ExtensionName}/view/adminhtml/layout/{frontnameId}_index_index.xml
  • {NameSpace}/{ExtensionName}/view/adminhtml/ui_component/{entity_grid_listing}.xml
* {entity_grid_listing} унікальний ідентифікатор вашої конфігурації ui component, Magento мерджит xml файли по імені, хороша ідея іменувати їх як {посилання}_grid_listing, як зроблено в CMS сторінках (page_grid_listing).

У прикладі:

  • {NameSpace} — Test,
  • {ExtensionName} — UiGrid,
  • {Посилання} – Grid.
Список файлів повинен бути знайомий Magento розробникам, нові файли серед них:

  • {NameSpace}/{ExtensionName}/Model/ResourceModel/{Посилання}/Grid/Collection.php
  • {NameSpace}/{ExtensionName}/view/adminhtml/ui_component/{entity_grid_listing}.xml
І так само пара нових рядків у наступних файлах конфігурацій:

  • {NameSpace}/{ExtensionName}/view/adminhtml/layout/{frontnameId}_index_index.xml
  • {NameSpace}/{ExtensionName}/etc/di.xml
Давайте швидко пройдемося по основним файлів.

registration.php, module.xml повинні містити інформацію для оголошення нашого модуль, вміст файлів ви можете побачити в будь-якому Magento 2 экстеншене.

registration.php
\Magento\Framework\Component\ComponentRegistrar::register(
\Magento\Framework\Component\ComponentRegistrar::MODULE,
'Test_UiGrid',
__DIR__
);
module.xml
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
<module name="Test_UiGrid" setup_version="0.1.0"/>
</config>

acl.xml, menu.xml, routes.xml повинні мати інформацію про посиланнях і меню в адмін панелі, щоб можна було дістатися до вашої Grid сторінки.

acl.xml
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
<acl>
<resources>
<resource id="Magento_Backend::admin">
<resource id="Test_UiGrid::test" title="Test" translate="title" sortOrder="30">
</resource>
</resource>
</resources>
</acl>
</config>
menu.xml
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Backend:etc/menu.xsd">
<menu>
<add id="Test_UiGrid::test" title="Test" translate="title" module="Test_UiGrid" sortOrder="20" dependsOnModule="Test_UiGrid" resource="Test_UiGrid::test"/>
<add id="Test_UiGrid::test_uigrid" title="UiGrid" translate="title" module="Test_UiGrid" sortOrder="10" parent="Test_UiGrid::test" action="uigrid" resource="Test_UiGrid::test"/>
</menu>
</config>
routes.xml
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
<router id="admin">
<route id="uigrid" frontName="uigrid">
<module name="Test_UiGrid" />
</route>
</router>
</config>

Index.php Controller – звичайний адмін контролер, не володіє ніякими особливими методами.

Index.php
namespace Test\UiGrid\Controller\Adminhtml\Index;

use Magento\Framework\Controller\ResultFactory;
use Magento\Framework\App\Action\Action;
use Magento\Framework\View\Result\Page;

class Index extends Action
{
public function execute()
{
return $this->resultFactory->create(ResultFactory::TYPE_PAGE);
}
}

InstallSchema.php – повинен володіти інструкціями для того, щоб створити необхідні таблиці, які в подальшому буде використовувати ваш модуль.

Ваші Model, ResourceModel та model Collection можуть не мати якихось особливих методів, але повинні володіти звичайними методами, щоб зв'язати вашу модель ресурс моделлю, ресурс модель з БД і модель колекції з ними обома.

Model
namespace Test\UiGrid\Model;

use Magento\Framework\Model\AbstractModel;
use Test\UiGrid\Model\ResourceModel\Grid;

class Grid extends AbstractModel
{
protected function _construct()
{
$this->_init(Grid::class);
}
}
ResourceModel
namespace Test\UiGrid\Model\ResourceModel;

use Magento\Framework\Model\ResourceModel\Db\AbstractDb;

class Grid extends AbstractDb
{
protected function _construct()
{
$this->_init('uigrid', 'entity_id');
}
}
Collection
namespace Test\UiGrid\Model\ResourceModel\Grid;

use Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection;
use Test\UiGrid\Model\Grid;
use Test\UiGrid\Model\ResourceModel\Grid as GridResource;

class Collection extends AbstractCollection 
{
protected function _construct()
{
$this->_init(Grid::class, GridResource::class);
}
}

Готуємо дані для Ui Component
uigrid_index_index.xml — layout файл. Зверніть увагу на контейнер з ім'ям «content». Це найважливіша річ в цьому файлі. Ім'я тега uiComponent повинно відповідати імені вашого {entity_grid_listing}.xml файлу в ui_component папці.

uigrid_index_index.xml
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<head>
<title>UiGrid</title>
</head>
<body>
<referenceBlock name="menu">
<action method="setActive">
<argument name="itemId" xsi:type="string">Test_UiGrid::test_uigrid</argument>
</action>
</referenceBlock>
<referenceContainer name="content">
<uiComponent name="uigrid_grid_listing"/>
</referenceContainer>
</body>
</page>

di.xml — містить інформацію про data source collection для вашого Ui Component.

di.xml
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
<type name="Magento\Framework\View\Element\UiComponent\DataProvider\CollectionFactory">
<arguments>
<argument name="collections" xsi:type="array">
<item name="uigrid_grid_listing_data_source" xsi:type="string">Test\UiGrid\Model\ResourceModel\Grid\Grid\Collection</item>
</argument>
</arguments>
</type>
</config>

Ця інформація буде використана Magento для того, щоб підготувати дані для вашої Grid сторінки. Простіше кажучи, зазначений у di.xml клас — це просто колекція з кількома додатковими методами для роботи з search criteria і так далі. Давайте подивимося на цей клас по ближче.

{NameSpace}/{ExtensionName}/Model/ResourceModel/{Entity}/Grid/Collection.php
namespace Test\UiGrid\Model\ResourceModel\Grid\Grid;

use Test\UiGrid\Model\ResourceModel\Grid\Collection as GridCollection;
use Magento\Framework\Search\AggregationInterface;
use Magento\Framework\Api\Search\SearchResultInterface;
use Magento\Framework\View\Element\UiComponent\DataProvider\Document;
use Test\UiGrid\Model\ResourceModel\Grid;
use Magento\Framework\Api\SearchCriteriaInterface;

class Collection extends GridCollection implements SearchResultInterface
{
protected $aggregations;

protected function _construct()
{
$this->_init(Document::class, Grid::class);
}

public function getAggregations()
{
return $this->aggregations;
}

public function setAggregations($aggregations)
{
$this->aggregations = $aggregations;
}

public function getAllIds($limit = null, $offset = null)
{
return $this->getConnection()->fetchCol($this->_getAllIdsSelect($limit, $offset), $this->_bindParams);
}

public function getSearchCriteria()
{
return null;
}

public function setSearchCriteria(SearchCriteriaInterface $searchCriteria = null)
{
return $this;
}

public function getTotalCount()
{
return $this->getSize();
}

public function setTotalCount($totalCount)
{
return $this;
}

public function setItems(array $items = null)
{
return $this;
}
}

Зверніть увагу, що колекція повинна имплементить Magento\Framework\Api\Search\SearchResultInterface інтерфейс і розширювати вашу оригінальну колекцію (насправді це робить роботу з даними простіше і вам не доведеться впроваджувати безліч інших методів). Всі методи і властивості за винятком _construct можуть бути скопійовані з Magento\Cms\Model\ResourceModel\Block\Grid\Collection, більше вони вам не знадобляться. Метод _construct особливий. Ви повинні зробити так, щоб колекція використовувала Magento\Framework\View\Element\UiComponent\DataProvider\Document об'єкт як модель і вашу ресурс модель як, власне, ресурс модель для спілкування з БД.

Ui Component
Ui Component — це ui_component/{entity_grid_listing}.xml файл, який надає інформацію про grid таблиці і про те як дані повинні бути в ній представлені.

З початку вам варто подивитися module-cms/view/adminhtml/ui_component/cms_block_listing.xml файл, він виглядає відносно простим, але відсутність опису в документації робить свою справу. Більшість ui grid сторінок мають схожу структуру такого файлу: argument, dataSource, listingToolbar, columns.

<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
<argument name="data" xsi:type="array">
...
</argument>
<dataSource name="uigrid_grid_listing_data_source">
...
</dataSource>
<listingToolbar name="listing_top">
...
</listingToolbar>
<columns name="uigrid_grid_columns">
...
</columns>
</listing>

Але що вони насправді роблять? Важливий порядок елементів? Які параметри можна і треба передавати? І самий головний, як же все це працює?

Ui Component – це нова особливість Magento 2, це суміш knockoutjs і бекенд коду. Коли ви використовуєте uiComponent тег у вашому лаяуте це говорить Magento що треба обробити файл з таким то ім'ям певним способом. Коротенько, Magento читає компонент файл, створює певні класи, для того, щоб зібрати опції для компонента і в кінцевому підсумку готує jsLayout конфіг, який буде переданий на фронтенд і оброблений knockoutjs (будуть створені observables, viewModels, створений мапінг view теплейтов і так далі). Magento_Ui – це той экстеншен, який надає більшість готових до використання компонентів (viewModels), які ви можете використовувати в своєму коді. Ви можете знайти їх в module-ui/view/base/web/js/*. Головний же конфіг – це module-ui/view/base/ui_component/etc/definition.xml він містить опис і стандартні опції для всіх компонентів, які ви можете використовувати у вашому Ui Component. Будь-які зміни в цьому файлі (або definition.xml файл) будуть застосовані до всіх экстеншенам.

Ui Component конфіг

Розберемо Test/UiGrid/view/adminhtml/ui_component/uigrid_grid_listing.xml. Для того, щоб було простіше простежити структуру я буду нумерувати вкладені елементи і виділяти основні місця.

Почнемо з самого першого елемента, який ми бачимо в прикладі вище.

1. <argument name="data" xsi:type="array">.
<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
<argument name="data" xsi:type="array">
<item name="js_config" xsi:type="array">
<item name="provider" xsi:type="string">uigrid_grid_listing.uigrid_grid_listing_data_source</item>
<item name="deps" xsi:type="string">uigrid_grid_listing.uigrid_grid_listing_data_source</item>
</item>
<item name="spinner" xsi:type="string">uigrid_grid_columns</item>
<item name="buttons" xsi:type="array">
<item name="add" xsi:type="array">
<item name="name" xsi:type="string">add</item>
<item name="label" xsi:type="string" translate="true">Add New Entity</item>
<item name="class" xsi:type="string">primary</item>
<item name="url" xsi:type="string">*/*/new</item>
</item>
<!--
<item name="back" xsi:type="string">Magento\Cms\Block\Adminhtml\Block\Edit\BackButton</item>
<item name="delete" xsi:type="string">Magento\Cms\Block\Adminhtml\Block\Edit\DeleteButton</item>
<item name="reset" xsi:type="string">Magento\Cms\Block\Adminhtml\Block\Edit\ResetButton</item>
<item name="save" xsi:type="string">Magento\Cms\Block\Adminhtml\Block\Edit\SaveButton</item>
<item name="save_and_continue" xsi:type="string">Magento\Cms\Block\Adminhtml\Block\Edit\SaveAndContinueButton</item>
-->
</item>
</argument>
<dataSource name="uigrid_grid_listing_data_source">
...
</dataSource>
<listingToolbar name="listing_top">
...
</listingToolbar>
<columns name="uigrid_grid_columns">
...
</columns>
</listing>

<item name="js_config" xsi:type="array"> містить інформацію про data provider на фронтенде, формат імені провайдера повинен бути {file_name}.{file_name}_data_source.

<item name="spinner" xsi:type="string"> містить посилання на список стовпців у цьому ж файлі, значення повинно бути ідентично імені, яке ви вказали для тега columns. Я рекомендую називати його {extension}_{посилання}_columns. Якщо ви не встановили його або встановили його не вірно, то Magento не зупинить spinner навіть якщо дані вже завантажилися.


<item name="buttons" xsi:type="array"> містить інформацію про верхніх кнопках.


Зверніть увагу, що ви можете не тільки додати кнопку «Add ...», але й інші кнопки з різними класами, як показано нижче.

Кнопка може бути додано не тільки через xml, але і через окремий клас. Зверніть увагу на закомментированный шматок коду. Реалізацію цих класів ви знайдете всередині них самих.

2. <dataSource name="uigrid_grid_listing_data_source">
<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
<argument name="data" xsi:type="array">
...
</argument>
<dataSource name="uigrid_grid_listing_data_source">
<argument name="dataProvider" xsi:type="configurableObject">
<argument name="class" xsi:type="string">Magento\Framework\View\Element\UiComponent\DataProvider\DataProvider</argument>
<argument name="name" xsi:type="string">uigrid_grid_listing_data_source</argument>
<argument name="primaryFieldName" xsi:type="string">entity_id</argument>
<argument name="requestFieldName" xsi:type="string">entity_id</argument>
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="component" xsi:type="string">Magento_Ui/js/grid/provider</item>
<item name="update_url" xsi:type="url" path="mui/index/render"/>
<item name="storageConfig" xsi:type="array">
<item name="indexField" xsi:type="string">entity_id</item>
</item>
</item>
</argument>
</argument>
</dataSource>
<listingToolbar name="listing_top">
...
</listingToolbar>
<columns name="uigrid_grid_columns">
...
</columns>
</listing>

Ця секція містить важливу інформацію про render url, data provider класі, імені вашої колекції, яка надає дані і так далі. Ім'я атрибута повинно дотримуватися наступного формату {file_name}_data_source і повинно бути ідентичне тому, яке ви використовували раніше.

Вам необхідно змінити тільки наступні елементи:

<argument name="name" xsi:type="string"> має містити назву вашої колекції в di.xml,
<argument name="primaryFieldName" xsi:type="string">, <argument name="requestFieldName" xsi:type="string">, <item name="indexField" xsi:type="string"> – entity id ключ вашої таблиці в БД.

Інші атрибути можуть залишатися такими ж як у прикладі.

Якщо ім'я вказано не вірно або колекція не була описана в di.xml ви побачите наступну помилку


3. <listingToolbar name="listing_top">
<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
<argument name="data" xsi:type="array">
...
</argument>
<dataSource name="uigrid_grid_listing_data_source">
...
</dataSource>
<listingToolbar name="listing_top">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="sticky" xsi:type="boolean">true</item>
</item>
</argument>
<bookmark name="bookmarks"/>
<columnsControls name="columns_controls"/>
<filterSearch name="fulltext"/>
<filters name="listing_filters">
...
</filters>
<massaction name="listing_massaction">
...
</massaction>
<paging name="listing_paging"/>
<exportButton name="export_button"/>
</listingToolbar>
<columns name="uigrid_grid_columns">
...
</columns>
</listing>

Цей елемент містить список елементів верхнього меню, таких як Filters, Bookmarks, Column editor, Full text search field, Mass Actions, Pagination і так далі.



Майте на увазі, що ви можете заповнювати цю xml в декількох экстеншенах одночасно! Просто помістіть ui_component файл з тим же ім'ям в той же або base scope. Порядок елемент відіграє велику різницю, тому стежте за тим, в якому порядку модулі завантажуються і елементи додаються в ui_component. Якщо <listingToolbar> буде завантажений після <columns>, ви отримаєте наступний результат:



Ім'я елемента повинно бути зазначено прикладі.

<listingToolbar name="listing_top">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="sticky" xsi:type="boolean">true</item>
</item>
</argument>
...
</listingToolbar>

3.1. <item name="sticky" xsi:type="boolean"> опціональний, ви можете пропустити його. Значення за замовчуванням «false». Цей параметр відповідає за швидкий доступ до топ меню під час прокручування сторінки, воно буде слідувати за скрол, поки ви не прокрутіть сторінку назад до самого верху.

3.2. <bookmark name="bookmarks"> опціональний. Він додає кнопку «Bookmark». Якщо ви позначите цей елемент, Magento дозволить адміністраторам зберігати стан стовпців і їх позиції для використання пізніше. У кожного адміністратора свій власний список.

3.3. <columnsControls name="columns_controls"> опціональний. Він додає кнопку «Columns». Якщо ви позначите цей елемент, Magento дозволить адміністраторам додавати або видаляти деякі стовпці з вашої grid таблиці.

3.4. <filterSearch name="fulltext"> опціональний. Додає full text search поле.



Magento розробники впровадили чудову фічу — пошук по будь-якому полю у БД без написання програмного коду! Все що вам потрібно зробити, це додати full text index по 1 або кількома стовпцями в БД. Якщо у вашої таблиці є хоч 1 full text index то текст буде шукатися за нього. Ви можете додавати індекси у ваших інстал скриптах. Починаючи з MySQL 5.6.4 таблиці InnoDB підтримують Full text Index так само як і MyISAM.

3.5. <filters name="listing_filters"> опційний. Цей елемент може містити додаткові микронастройки для фільтрів та їх відображення. У прикладі ви можете бачити <argument> <filterSelect> елементи.

<listingToolbar name="listing_top">
...
<filters name="listing_filters">
<!-- If you need to apply custom filter render you can use these tag -->
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="templates" xsi:type="array">
<item name="filters" xsi:type="array">
<item name="select" xsi:type="array">
<item name="component" xsi:type="string">Magento_Ui/js/form/element/ui-select</item>
<item name="template" xsi:type="string">ui/grid/filters/elements/ui-select</item>
</item>
</item>
</item>
</item>
</argument>
<!-- custom filter, Expected is one of ( filterInput, filterRange, filterSelect, containerConfiguration ) -->
<filterSelect name="store_id">
<argument name="optionsProvider" xsi:type="configurableObject">
<argument name="class" xsi:type="string">Magento\Cms\Ui\Component\Listing\Column\Cms\Options</argument>
</argument>
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="provider" xsi:type="string">${ $.parentName }</item>
<!-- data that will be sent to server -->
<item name="dataScope" xsi:type="string">store_id</item>
<item name="label" xsi:type="string" translate="true">Store View</item>
<!-- default value -->
<item name="captionValue" xsi:type="string">0</item>
</item>
</argument>
</filterSelect>
</filters>
...
</listingToolbar>

Давайте почнемо з першого.

<argument>
Іноді вам може знадобитися змінити компонента або шаблон для певного типу фільтра (наприклад, змінити поведінку text input всередині списку фільтрів або select елемент). Найбільш частий випадок в Magento 2 коді це заміна стандартного компонента і шаблону select дропдауна з select на ui-select для status фільтра.


Зверніть увагу, що ця зміна торкнеться всі фільтри <item name={type}> типу.

<filterSelect>
Елемент «filterSelect» — це приклад зміни стандартного фільтра для store_id колонки. Загалом практично всі стовпці мають свій власний фільтр (text, textRange, date, select і т. д.), але в деяких випадках вам необхідно змінити поведінку/відображення такого фільтра для якоїсь колонки. Доступні типи: filterInput, filterRange, filterSelect і containerConfiguration (про це типі нам каже повідомлення помилку, якщо ви спробуєте вказати щось інше). Ім'я повинно бути ідентично імені стовпця, фільтр, якого ви хочете змінити, інакше мапінг не буде працювати.

3.6. <massaction name="listing_massaction"> елемент опційний. Він додає massaction дропдаун і спливаюче повідомлення, якщо користувач не вибрав ніякі рядка до вибору дії.




Зазвичай цей елемент виглядає як звичайний дропдаун, але ви можете замінити компонент на древообразное меню.




Якщо ви хочете замінити дефолтний повідомлення «You haven't any selected items!» як показано вище, вам треба передати такі параметри massaction component, просто вставте своє повідомлення в «noItemsMsg».

<massaction name="listing_massaction">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="noItemsMsg" xsi:type="string">Type here any text</item>
</item>
</argument>
...
</massaction>

Для того, щоб додати нову дію в дропдаун, погляньте на приклад нижче. Це приклад дії «delete», але ви можете додати так само інші.

<massaction name="listing_massaction">
...
<action name="delete">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="type" xsi:type="string">delete</item>
<item name="label" xsi:type="string" translate="true">Delete</item>
<item name="url" xsi:type="url" path="uigrid/index/massDelete"/>
<item name="confirm" xsi:type="array">
<item name="title" xsi:type="string" translate="true">Delete items</item>
<item name="message" xsi:type="string" translate="true">Are you sure you want to delete selected items?</item>
</item>
</item>
</argument>
</action>
...
</massaction>

<action name="delete"> — повинен мати унікальне ім'я, так як Magento мерджит елементи по імені.

<item name="type"> — повинен бути унікальним так само, в іншому випадку Magento буде показувати всі такі опції в дропдауне, але всі вони будуть виконувати 1 і теж дія як було описано в 1ом елементі з цим типом так як Magento кешує конфіги за типом. Доброю практикою вважається використання того ж імені, що ви вказали для екшену.

<item name="label"> — ім'я опції.

<item name="url"> — урл дії, який буде використаний для обробки вибраних рядків. Туди буде відправлений масив selected/excluded елементів, застосовані фільтри і застосована full text search фраза. Різниця між передаються параметрами залежить від методу вибору елементів. Якщо ви натиснули «select all» елемент «excluded» буде містити «false». Якщо ви вибрали кілька елементів вручну, масив «selected» буде містити entity id всіх вибраних записів. Останній випадок, якщо ви натиснули «select all», але пізніше анчекнули кілька записів вручну, масив «excluded» буде містити entity id всіх анчекнутых записів. Щоб показати приклад реалізації «massDelete» екшену і як ці параметри обробляються подивіться клас Magento\Cms\Controller\Adminhtml\Block\massDelete.

<item name="confirm"> — опціональний елемент. Якщо вказано, Magento буде показувати модальне вікно підтвердження дії з «Ок» чи «Cancel» кнопками. Title і Message можуть бути змінені як показано вище.

Зараз давайте розглянемо звичайну кнопку, а mass кнопку edit.

<massaction name="listing_massaction">
...
<action name="edit">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="type" xsi:type="string">edit</item>
<item name="label" xsi:type="string" translate="true">Edit</item>
<item name="callback" xsi:type="array">
<item name="provider" xsi:type="string">uigrid_grid_listing.uigrid_grid_listing.uigrid_grid_columns_editor</item>
<item name="target" xsi:type="string">editSelected</item>
</item>
</item>
</argument>
</action>
</massaction>

Основна різниця між ними це <item name="callback"> елемент. Він є опціональним. Його параметри роблять можливим редагування декількох рядків відразу. За фактом, він застосовує колбек до вибраних рядків.

Ось так змінюється грід якщо вибрано кілька рядків:



і якщо вибрано лише 1 стоку:



Для такого редагування будуть доступні тільки ті колонки, які мають «editor» атрибут (більше інформації про нього нижче).

<item name="provider"> — це шлях до компонента. Зверніть увагу на рядок у прикладі. Значення має слідувати наступним форматом {filename}.{filename}.{ columns_element_name}_editor.

<item name="target"> — це ім'я методу всередині knockoutjs компонента, «editSelected» має бути вказано тут.

Детальна конфігурація редактора буде розглянуто трохи пізніше.

Говорячи про опціях massaction дропдауна, як ви бачили раніше, там доступно 2 типу опцій. Звичайні (select) і деревоподібні опції. До нещастя «select» компонент не підтримує підменю, але tree-massactions підтримує. Для застосування цього компонента вам треба сказати Magento використовувати Magento_Ui/js/grid/tree-massactions компонент. «Action» елемент повинен бути вже знайомий вам, тому давайте поглянемо на мінорні зміни в наступному прикладі.

<massaction name="listing_massaction">
...
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="component" xsi:type="string">Magento_Ui/js/grid/tree-massactions</item>
</item>
</argument>
<action name="status">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="type" xsi:type="string">status</item>
<item name="label" xsi:type="string" translate="true">Change status</item>
</item>
</argument>
<argument name="actions" xsi:type="array">
<item name="0" xsi:type="array">
<item name="type" xsi:type="string">enable</item>
<item name="label" xsi:type="string" translate="true">Enable</item>
<item name="url" xsi:type="url" path="uigird/index/massStatus">
<param name="status">1</param>
</item>
</item>
<item name="1" xsi:type="array">
<item name="type" xsi:type="string">disable</item>
<item name="label" xsi:type="string" translate="true">Disable</item>
<item name="url" xsi:type="url" path="uigrid/index/massStatus">
<param name="status">2</param>
</item>
</item>
</argument>
</action>
...
</massaction>

<argument name="actions" xsi:type="array"> опційний. Він містить масив елементів з іменами від 0 до N, якщо імена не будуть слідувати цілочисельний послідовності те knockoutjs (javascript) викине помилку.

<param name="...">...</param> так само є опціональним. Поки вся інформація про вибрані рядках буде передана в тілі post запиту, ці параметри будуть передані як get параметри залежать тільки від обраної опції (див. приклад вище). Ці параметри можуть бути використані і з іншими мас экшенами.

3.7. <paging name="listing_paging"/> опціональний елемент. Він додає пагінацію для вашої грід сторінки. Якщо він не був доданий, Magento буде показувати всі записи на 1 станиці і не буде показувати кількість знайдених записів.

З елементом:



без елемента:



3.8. <exportButton name="export_button"/> опціональний елемент. Цей компонент додає кнопку export з 2ма опціями: export as csv, export as xml. Вам не треба имплементить додаткову логіки, щоб ця фіча працювала. Вона генерує фід файл містить тільки наявні дані, відповідно до застосованих фільтрів. Файл ігнорує сорт ордер і видимість елементів на екрані, Magento завжди генерує файл включає всі колонки з ui_component файлу. Колонки будуть в порядку їх поява в цьому файлі, повністю ігноруючи іншу сортування (включаючи атрибут сортування елементів у файлі). Ви так само можете додати інші формати для експорту, як це зробити описано в документації devdocs.magento.com/guides/v2.1/ui-components/ui-export.html.

4. <columns name="uigrid_grid_columns">
...
<columns name="uigrid_grid_columns">
<argument name="data" xsi:type="array">
...
</argument>
<selectionsColumn name="ids">
...
</selectionsColumn>
<column name="entity_id">
...
</column>
<actionsColumn name="actions" class="Test\UiGrid\Ui\Component\Listing\Column\Action"/>
</columns>

Це найбільш цікава і важлива частина для відображення колонок у гріді. Цей елемент містить список стовпців, які повинні бути доступні адміну.

<columns name="uigrid_grid_columns"> — ім'я елемента має бути наступного формату {extension}_{посилання}_columns і бути ідентичне тому, що ви прописали в <item name="spinner" xsi:type="string">name_of_columns_element</item>. Зазвичай цей тег має тільки атрибут «name», але може мати і «class» як у vendor/magento/module-catalog/view/adminhtml/ui_component/product_listing.xml.

<columns name="product_columns" class="Magento\Catalog\Ui\Component\Listing\Columns">
Вам потрібно використовувати клас у елементі columns тільки якщо ви хочете обробляти якісь дані динамічно начебто сортування, видно якихось колонок або ж додавати нові стовпці динамічно.

Editor
...
<columns name="uigrid_grid_columns">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="editorConfig" xsi:type="array">
<item name="selectProvider" xsi:type="string">uigrid_grid_listing.uigrid_grid_listing.uigrid_grid_columns.ids</item>
<item name="enabled" xsi:type="boolean">true</item>
<item name="indexField" xsi:type="string">entity_id</item>
<item name="clientConfig" xsi:type="array">
<item name="saveUrl" xsi:type="url" path="*/*/inlineEdit"/>
<item name="validateBeforeSave" xsi:type="boolean">false</item>
<!--
<item name="validateBeforeSave" xsi:type="boolean">true</item>
<item name="validateUrl" xsi:type="url" path="*/*/checkData"/>
-->
</item>
</item>
</item>
</argument>
...
</columns>

Якщо ви хочете додати «edit» массэкшен в список массэкшенов або зробити доступним інлайн редактор вам необхідно спершу його налаштувати.

<item name="selectProvider" xsi:type="string"> — шлях до колонки/компоненту в дереві, дотримуйтеся наступного формату:

{filename}.{filename}.{columns_name}.{selectionsColumn_name},
у прикладі це uigrid_grid_listing.uigrid_grid_listing.uigrid_grid_columns.ids.

<item name="enabled" xsi:type="boolean"> — включити/вимкнути редактор.

<item name="indexField" xsi:type="string"> — entity id, буде використовуватися при збереженні даних.

<item name="clientConfig" xsi:type="array"> — конфігурація «Save» екшену.

<item name="saveUrl" xsi:type="url" path="*/*/inlineEdit"/> — урл, який knockoutjs використовує для збереження інлайн змін. Зверніть увагу на «path», я спеціально вказав урл як "*/*/inlineEditor", щоб показати, що такі урли так само підтримуються.

<item name="validateBeforeSave" xsi:type="boolean"> — це дуже цікава опція. Дефолтний значення – «істина», так що якщо ви пропустили цю настройку і не вказали наступний параметр «validateUrl», knockoutjs викине помилку. Якщо ця опція включена, knockoutjs відправляє нові значення на «validateUrl» і якщо респонс в порядку (наприклад http код 200), knockoutjs відправить ці ж дані на saveUrl, в іншому випадку покаже повідомлення з помилкою. Якщо вам не потрібен цей функціонал і ви просто хочете зберігати дані і можливо валідувати їх прямо там то встановіть параметр «false».

<item name="validateUrl" xsi:type="url" path="*/*/checkData"/> — урл для валідації даних.

Налаштування InlineEditor

Якщо ви хочете активувати інлайн редактор по кліку на сходинку (наприклад як на CMS page/block гридах), вам необхідно додати конфіг <argument> вашого <columns> тега відразу після «editorConfig». Єдиний параметр, який вам треба поміняти це «provider», він повинен слідувати наступним форматом {filename}.{filename}.{columns_name}_editor, всі інші параметри мають бути як в прикладі нижче.

...
<columns name="uigrid_grid_columns">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="editorConfig" xsi:type="array">
...
</item>
<item name="childDefaults" xsi:type="array">
<item name="fieldAction" xsi:type="array">
<item name="provider" xsi:type="string">uigrid_grid_listing.uigrid_grid_listing.uigrid_grid_columns_editor</item>
<item name="target" xsi:type="string">startEdit</item>
<item name="params" xsi:type="array">
<item name="0" xsi:type="string">${ $.$data.rowIndex }</item>
<item name="1" xsi:type="boolean">true</item>
</item>
</item>
</item>
</item>
</argument>
...
</columns>

З певних причин інлайн редактор може не підійти вам. У такому випадку ви можете захотіти виконувати інші дії по кліку на сходинку. Для цього помістіть наступний код замість виклику inlineEditor. Вам необхідно змінити тільки 2 параметра там: provider,0. Провайдер повинен слідувати наступним форматом {filename}.{filename}.{columns_name}.actions, ім'я екшену з вашого «action» списку (див. нижче).

...
<columns name="uigrid_grid_columns">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
...
<item name="childDefaults" xsi:type="array">
<item name="fieldAction" xsi:type="array">
<item name="provider" xsi:type="string">uigrid_grid_listing.uigrid_grid_listing.uigrid_grid_columns.actions</item>
<item name="target" xsi:type="string">applyAction</item>
<item name="params" xsi:type="array">
<!-- name of action from class action -->
<item name="0" xsi:type="string">view</item>
<item name="1" xsi:type="string">${ $.$data.rowIndex }</item>
</item>
</item>
</item>
</item>
</argument>
...
</columns>

Columns

<column|actionsColumn|selectionsColumn name="{unique_name}" class="{class_name}">
<argument name="data" xsi:type="array">
<item name="options" xsi:type="object">{source_model_class}</item>
<item name="config" xsi:type="array">
<item name="component" xsi:type="string">Magento_Ui/js/grid/columns/{date|select|thumbnail|column|*}</item>
<item name="bodyTmpl" xsi:type="string">ui/grid/cells/{html|text|*}</item>
<item name="add_field" xsi:type="boolean">{true|false}</item>
<item name="sortable" xsi:type="boolean">{true|false}</item>
<item name="filter" xsi:type="string">{textRange|dateRange|select|text}</item>
<item name="sorting" xsi:type="string">{asc|desc}</item>
<item name="label" xsi:type="string" translate="true">{label}</item>
<item name="visible" xsi:type="boolean">{true|false}</item>
<item name="draggable" xsi:type="boolean">{true|false}</item>
<!-- <item name="editor" xsi:type="string">{text|date|select}</item> -->
<item name="editor" xsi:type="array">
<item name="editorType" xsi:type="string">{text|date|select}</item>
<item name="options" xsi:type="array">
<item name="showsTime" xsi:type="boolean">{true|false}</item>
</item>
<item name="validation" xsi:type="string">{validation_rule}</item>
<!-- 
<item name="validation" xsi:type="array">
<item name="validate-xml-identifier" xsi:type="boolean">true</item>
<item name="required-entry" xsi:type="boolean">true</item>
</item> 
-->
</item>
<item name="timezone" xsi:type="boolean">{true|false}</item>
<item name="dataType" xsi:type="string">{dataType}</item>
<item name="sortOrder" xsi:type="number">{position}</item>
<item name="options" xsi:type="array">
<item name="0" xsi:type="array">
<item name="value" xsi:type="string">{value}</item>
<item name="label" xsi:type="string">{option_label}</item>
</item>
<item name="1" xsi:type="array">
<item name="value" xsi:type="string">{value}</item>
<item name="label" xsi:type="string">{option_label}</item>
</item>
</item>
<item name="has_preview" xsi:type="boolean">{true|false}</item>
</item>
</argument>
</column|actionsColumn|selectionsColumn>

<column|actionsColumn|selectionsColumn> — всі ці елементи розташовані всередині <columns> тега, вони мають схожий синтаксис. <column> використовується для додавання звичайної колонки, <actionsColumn> використовується для додавання стовпця «action» і нарешті <selectionsColumn> використовується для додавання колонки з чекбоксами для вибору рядків. <actionsColumn> може бути пропущений якщо ви хочете використовувати тільки інлайн редактор. Ім'я selectionsColumn атрибута повинно бути ids, він не має атрибуту class і може бути пропущений якщо ви не хочете використовувати експорт, інлайн редактор, мас дій і т. д.

<column name="{unique_name}"> — це обов'язковий атрибут. Це унікальне ім'я стовпця. Magento перезаписує стовпці по імені. Ім'я стовпця може бути не ідентично імені колонки в БД (ключу у вашій колекції), це лише ім'я колонки. Якщо ж ім'я колонки ідентично імені колонки в БД, Magento замапит дані з колекції в це поле автоматично ці дані будуть доступні (видимі) у гріді. В іншому випадку необхідно використовувати атрибут «class», щоб отримати/підготувати необхідне значення.

<column class="{class_name}"> — це опціональний атрибут. Головна особливість «класу» це форматування/підготовка даних з колекції для відображення у колонці/використання компонентом. Клас має доступ до даних колекції для цього рядка і може модифікувати будь-яке значення як і додавати/видаляти деякі ключі. Клас Magento\Ui\Component\Listing\Columns\Date форматує дату з БД, призводить її до необхідного формату і так само застосовує зрушення для тайм зони. Клас Magento\Catalog\Ui\Component\Listing\Columns\Thumbnail надає дані для тамбнейл компонента. Подивіться їх код, щоб краще зрозуміти, як вони працюють.

<argument name="data" xsi:type="array"> — це обов'язковий тег якщо ви хочете надати додаткові дані, клас вашого стовпця будуть доступні всі дані всередині тега) або його компонент (будуть доступні всі дані всередині внутрішнього «config» тега).

<item name="options" xsi:type="object"> — опціональний елемент. Нативно використовується тільки з dataType «select» (див. далі) для відображення опцій з source модельки, але ви можете використовувати цей параметр для обробки даних у вашому класі (вони мають повний доступ до всіх даних всередині «data» тега, але ці дані не будуть доступні в knockoutjs компоненті). Так само є й інші способи зробити теж саме, див. нижче.

<item name="config" xsi:type="array"> — обов'язковий якщо вам потрібно передати які-небудь дані компонент клас і/або knockoutjs компонент. Ви можете мати повний доступ до цих даних всередині вашої knockoutjs ViewModel. За замовчуванням, ViewModel не має доступу до параметрів за межами «config» тега.

<item name="component" xsi:type="string"> — опціональний. Простіше кажучи, компоненти рендерят значення для відображення в колонках. На приклад, один з них відповідає за відображення «Sep 5, 2016 8:03:07 PM» замість 2016-09-05 в колонці дати. Значення за замовчуванням – це Magento_Ui/js/grid/columns/column, він же дефолтний компонент для всіх колонок. ViewModel'і для візуалізації колонок розташовані в Magento_Ui/js/grid/columns/. Найбільш використовувані значення (компоненти) у цьому тегу:

Magento_Ui/js/grid/columns/column – відображає значення як текстове, тобто як є,
Magento_Ui/js/grid/columns/date – відображає дати відповідно до зазначеного формату,
Magento_Ui/js/grid/columns/select – відображає значення як вибрані селект опції з мапингом значень і їх лейблів,
Magento_Ui/js/grid/columns/thumbnail – показує зображення в колонці,
Ви так само можете створити свої власні компоненти, просто «наследуйтесь» від Magento_Ui/js/grid/columns/column.

<item name="bodyTmpl" xsi:type="string"> — опціональний. Ви можете змінити шаблон («view»), який буде використовуватися в стовпці. Дефолтний значення ui/grid/cells/text. Якщо дані не можуть бути трансформовані в текст і вам потрібно більше можливостей для використання html всередині, використовуйте шаблон ui/grid/cells/html (він зазвичай використовується Store Id колонках) або будь-який з ui/grid/cells (або вашого экстеншена).

<item name="add_field" xsi:type="boolean"> — опціональний. Ви могли бачити цей тег в деяких ui_*.xml файлах, він потребує додаткової реалізації в DataProvider/collection класах і обов'язковий для eav/значень окремих таблиць тільки так як такі стовпці можуть бути не виявлені в основній таблиці без цього виклику.

<item name="sortable" xsi:type="boolean"> — опціональний. Дефолтний значення «true». Він відключає здатність застосовувати сортування по кліку на стовпці.

<item name="filter" xsi:type="string"> — опціональний. Цей параметр додає фільтр до колонки. Він підтримує наступні значення: textRange, dateRange, select, text. Зверніть увагу на скріншот нижче. (ID – textRange, Created – dateRange, Store View – кастомный фільтр, Name – text, Status – select).



Якщо вам треба використовувати кастомный фільтр для колонки (наприклад селект з групами, заснований на кастомний модельки, на зразок списку Website/StoreView) ви можете пропустити фільтр параметр у списку параметрів вашої колонки і додати опис фільтра <filters name="listing_filters">.

<item name="sorting" xsi:type="string"> — опционанальный, він застосовує сортування до всього гриду по цьому полю. Доступні наступні опції: asc, desc. Тільки до 1 полю може бути застосована сортування за замовчуванням.

<item name="label" xsi:type="string"> — обов'язкове. Коротенько, це ім'я колонки, воно буде відображатися в хедері вашої колонки. За фактом, це просто текст і використовується ui/grid/columns/text» шаблон, який зазначений у «headerTmpl» параметрі. Ви можете змінити його, якщо вам треба.

<item name="visible" xsi:type="boolean"> — опціональний. Дефолтний значення «true». Цей параметр дозволяє приховати колонку з гріду, але вона буде доступна в списку доступних колонок, її можна буде додати звідти.

<item name="draggable" xsi:type="boolean"> — опціональний. Дефолтний значення «true». Робить стовпець статичним/не переміщуються.

<item name="editor" xsi:type="{string|array}"> — опціональний. Дозволяє використовувати інлайн едитор для колонки. Якщо тег пропущено значення в цьому стовпці можна буде редагувати при виклику інлайн едитора по кліку на рядку або через мас екшен меню. Є 2 способи застосування цього тегу. Він може мати тип «string» чи тип «array». Якщо вам потрібно включити едитор для цього поля використовуйте «string» і вкажіть тип (режим) для цього поля, але якщо ви хочете конфігурувати едитор більш точно використовувати тип «array». Всього є 3 режими: text, date, select. Ви повинні вибрати 1 з них.

Список налаштувань для едитора:

  • <item name="editorType" xsi:type="string"> — тип едитора. Можливі такі ж значення як і в «string» версії: text, date, select.
  • <item name="showsTime" xsi:type="boolean"> — опціональний. Використовується тільки з «date» типом. Дозволяє змінювати не тільки дату, але і час. Дефолтний значення «false».
  • <item name="validation" xsi:type="{string|array}"> — опціональний. Може бути або «string» або «array». Приміряє валідацію до поля редагування. Всі можливі варіанти валідації ви можете подивитися в vendor\magento\magento2-base\lib\web\mage\validation.js. Якщо вам треба застосувати більше ніж 1 валідацію то вам треба використовувати тип «array» і вказати необхідні правила валідації в наступному форматі:

    • <item name="{validation_rule}" xsi:type="boolean">true</item>
<item name="timezone" xsi:type="boolean"> — опціональний. Дефолтний значення «true». Ця опція застосовна тільки до колонок типу «date». Вона використовується в Magento\Ui\Component\Listing\Columns\Date класі. Дозволяє скорегувати тайм зону якщо у БД і в адмін панелі у вас використовують різні тайм зони.

<item name="dataType" xsi:type="string"> — опціональний. У реальному житті, корисний тільки зі стовпцями типу «select». Дефолтний значення «text». Доступні значення будь сутності(теги) з /vendor/magento/module-ui/view/base/ui_component/etc/definition.xml. Що таке dataType? Простіше кажучи, це дефолтний поведінка ваших елементів. Коли Magento починає обробляти конфіг вашого стовпця, вона читає dataType параметр, завантажує його опис з definition.xml запускає об'єкт класу, який вказаний для цього dataType («class» немає ознаки). Цей об'єкт має повний доступ до параметрів, переданим в «data» тег і може модифікувати їх. Після обробки цих даних Magento мерджит конфіг з definition.xml, даними згенеровані зазначеним об'єктом з вашим описом колонки і передає ці дані на фронтенд, де knockoutjs починає обробляти отриманий конфіг. Щодо гріду, єдиний корисний dataType це «select» завдяки класу Magento\Ui\Component\Form\Element\Select, який пов'язаний з ним. Цей клас обробляє тег «options» і форматує дані з вказаної source model у відповідний масив опцій, які можуть бути в подальшому оброблені Magento_Ui/js/grid/columns/select (нативний select компонент).

<item name="sortOrder" xsi:type="number"> — опціональний. Якщо sortOrder пропущено, Magento відображає стовпці в порядку їх опису в ui_component файлі. Якщо ж цей параметр присутній, то Magento відображає елементи згідно параметра sortOrder, але експорт файлі порядок колонок буде ідентичний порядку елементів у ui_component файлі! Майте на увазі, що після першого разу, як адмін відкриє грід сторінку порядок елементів буде збережений в БД і будь-які зміни параметра sortOrder не будуть застосовані. Більш того, нові колонки завжди будуть додані в кінець. Докладніше про це ви знайдете нижче.

<item name="options" xsi:type="array"> — опціональний і є альтернативним способом візуалізації колонки типу «select». Може бути використаний з «select» компонентом. Раніше було сказано, що для відображення лейблів замість ключів з БД вам треба використовувати option тег з сорс моделькою і вказати dataType=«select». Інший спосіб так само існує. «select» компоненту потрібен масив опцій для того, щоб відобразити лейбли замість id. Якщо у випадку з сорс моделькою dataType елемент готує значення, ви можете так сформувати необхідний масив опцій вручну. Зверніть увагу на синтаксис:

<item name="0" xsi:type="array">
<item name="value" xsi:type="string">{value}</item>
<item name="label" xsi:type="string">{option_label}</item>
</item>
<item name="1" xsi:type="array">
<item name="value" xsi:type="string">{value}</item>
<item name="label" xsi:type="string">{option_label}</item>
</item>

Кожен айтем це опція/маппінг. Замість {value} буде відображено {option_label}. Це досить зручний спосіб, але якщо у вас вже є сорс моделька для вашого дропдауна використання dataType підходу більш виправдано.

<item name="has_preview" xsi:type="boolean"> — опціональний. Застосуємо тільки з «thumbnail» компонентом/стовпцями. Дефолтний значення «false». Якщо він включений тоді за кліком на зображенні у списку буде показано модальне вікно з великим зображенням та посиланням на сторінку редагування.

Для того, щоб подивитися всі доступні параметри і які можливості є у кожного з компонентів ви можете подивитися їх вихідний код.

Examples

Minimum data required for creating a column


<column name="data">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="label" xsi:type="string" translate="true">Data</item>
</item>
</argument>
</column>

Цей стовпець просто відображає дані з ім'ям «data» з БД як є. Він не має фільтра або інлайн редактора.

Selections column



Це досить важливий стовпець. Він надає не тільки «select all», «select all on this page», «deselect all», «deselect all on this page», чекбокси, але і маппінг рядків і їх id. Практично завжди описується першим.

<selectionsColumn name="ids">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="indexField" xsi:type="string">entity_id</item>
</item>
</argument>
</selectionsColumn>

<selectionsColumn name="ids"> ім'я повинно бути «ids».
<item name="indexField" xsi:type="string"> ім'я primary key в БД.

Text column


<column name="name">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="editor" xsi:type="string">text</item>
<item name="filter" xsi:type="string">text</item>
<item name="label" xsi:type="string" translate="true">Name</item>
</item>
</argument>
</column>

Цей стовпець показує значення як є з БД, але так само володіє простим текстовим фільтром і підтримує інлайн редактор.

Date column



Є 2 режиму для відображення і інлайн редактора. Date і datetime.



<column name="date" class="Magento\Ui\Component\Listing\Columns\Date">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<!-- <item name="editor" xsi:type="string">date</item> -->
<item name="editor" xsi:type="array">
<item name="editorType" xsi:type="string">date</item>
<item name="options" xsi:type="array">
<item name="showsTime" xsi:type="boolean">true</item>
</item>
</item>
<item name="timezone" xsi:type="boolean">false</item>
<item name="filter" xsi:type="string">dateRange</item>
<item name="component" xsi:type="string">Magento_Ui/js/grid/columns/date</item>
<item name="label" xsi:type="string" translate="true">Created</item>
<item name="dateFormat" xsi:type="string">MMM d</item>
</item>
</argument>
</column>

Клас Magento\Ui\Component\Listing\Columns\Date дозволяє скорегувати тайм зону для даних з БД до обраної локалі.

Компонент Magento_Ui/js/grid/columns/date надає необхідний функціонал для відображення дат.

<item name="editor" xsi:type="array"> встановлює інлайн редактор для поля.

<item name="showsTime" xsi:type="boolean"> — опціональний. Встановлює режим. Дефолтний значення «false». Якщо ви хочете змусити Magento показувати селектор часу то встановіть значення «true». Якщо ви хочете відображати коректну дату інлайн редакторі вам необхідно встановити showTime = true, в іншому випадку дата буде скидатися на сьогоднішній день при запуску інлайн едитора – це баг Magento 2.

<item name="timezone" xsi:type="boolean"> — опціональний параметр. Дефолтний значення «true». Якщо вам треба відключити корекцію часу виберіть цей параметр і передайте «false», в іншому випадку вона буде застосована. Врахуйте, що час в інлайн редакторі буде відображатися з урахуванням тайм зони (якщо не вимкнено) і коли ви натиснете на «save» на сервер відправиться саме цей час.

<item name="filter" xsi:type="string">dateRange</item> — опціональний. Додає фільтр список фільтрів. Майте на увазі, він не залежить від налаштувань редактора, дефолтний фільтр для DataRange відображає лише дати.


<item name="dateFormat" xsi:type="string"> — опціональний. Дозволяє вказати формат для відображення дати у стовпці. Дефолтний значення «MMM d, YYYY h:mm:ss A», що еквівалентно «Sep 5, 2016 9:00:00 AM».

Select column



Найбільш поширений стовпець типу «select» це Status. Зазвичай він має всього 2 значення Enabled і Disabled.

<column name="is_active">
<argument name="data" xsi:type="array">
<item name="options" xsi:type="object">Magento\Cms\Model\Block\Source\IsActive</item>
<item name="config" xsi:type="array">
<item name="dataType" xsi:type="string">select</item>
<item name="component" xsi:type="string">Magento_Ui/js/grid/columns/select</item>
<item name="editor" xsi:type="string">select</item>
<item name="filter" xsi:type="string">select</item>
<item name="label" xsi:type="string" translate="true">Status</item>
</item>
</argument>
</column>

<item name="options" xsi:type="object"> — обов'язкове для підходу з використанням сорс моделі. Надає масив значень (через сорс модель), але knockoutjs компонент не може використовувати ці дані на пряму.

<item name="dataType" xsi:type="string"> — обов'язкове для цього підходу. Використовує клас «options» і отримує список всіх доступних значень. Далі «select» клас форматує отриманий масив опцій для knockoutjs компонента. Після чого компонент рендерить ці дані як «select».

Якщо у вас немає сорс моделі і ви не хочете створювати її ви можете надати список необхідних значень безпосередньо в xml.

<column name="is_active">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="options" xsi:type="array">
<item name="0" xsi:type="array">
<item name="value" xsi:type="string">0</item>
<item name="label" xsi:type="string">Disabled</item>
</item>
<item name="1" xsi:type="array">
<item name="value" xsi:type="string">1</item>
<item name="label" xsi:type="string">Enabled</item>
</item>
</item>
<item name="component" xsi:type="string">Magento_Ui/js/grid/columns/select</item>
<item name="editor" xsi:type="string">select</item>
<item name="filter" xsi:type="string">select</item>
<item name="label" xsi:type="string" translate="true">Status</item>
</item>
</argument>
</column>

<item name="options" xsi:type="array"> — обов'язкове поле для підходу без використання сорс моделі. Воно містить масив ключ/значення.

Store View column



<column name="store_id" class="Magento\Store\Ui\Component\Listing\Column\Store">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="bodyTmpl" xsi:type="string">ui/grid/cells/html</item>
<item name="label" xsi:type="string" translate="true">Store View</item>
</item>
</argument>
</column>

У більшості випадків Store View зберігається як store_id (ідентифікатор стора), але показувати це не найкраща ідея. Для того, щоб замінити це значення на ім'я стора треба використовувати кастомный клас. Щоб показати дані як на скріншоті вище треба використовувати html, так як дефолтний шаблон відображає тільки текстові значення. Треба змінити його в «bodyTmpl». Клас Magento\Store\Ui\Component\Listing\Column\Store замінює ідентифікатор структуроване на Website-Store-StoreView html значення. Майте на увазі, що після цього так само треба застосувати кастомный фільтр, щоб дозволити фільтрувати ці дані в такому ж вигляді.

Thumbnail column



<column name="image" class="Magento\Catalog\Ui\Component\Listing\Columns\Thumbnail">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="component" xsi:type="string">Magento_Ui/js/grid/columns/thumbnail</item>
<item name="has_preview" xsi:type="string">1</item>
<item name="label" xsi:type="string" translate="true">Image</item>
</item>
</argument>
</column>

Thumbnail стовпці трохи специфічні в імплементації. Компонент вимагає наступні дані:

  • {column_name}_src – урл маленького зображення,
  • {column_name}_alt – alt текст,
  • {column_name}_link – посилання на сторінку редагування, яка використовується у спливаючому вікні
  • {column_name}_orig_src – урл оригінального зображення, яке виявляється у вплывающем вікні.
*{column_name} це «image» у прикладі.

Ці дані рідко зберігаються в БД, для надання цих даних на сторінці продуктів використовується Magento\Catalog\Ui\Component\Listing\Columns\Thumbnail. Перегляньте вихідний код, щоб створити вашу власну реалізацію.

<item name="has_preview" xsi:type="boolean"> — опціональний. Включення цієї опції дозволяє показувати спливаюче вікно по кліку на зображенні у стовпці.

Action column



Стовпець «Action» використовує «actionColumn» тег замість «column», але його особливості і синтаксис такі ж. Стовпець може бути створений 2ма способами.

Спосіб перший


Для створення такого «action» стовпця використовуйте наступну коротку:

<actionsColumn name="actions" class="Test\UiGrid\Ui\Component\Listing\Column\Action"/>

або повну запис:

<actionsColumn name="actions" class="Test\UiGrid\Ui\Component\Listing\Column\Action">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="indexField" xsi:type="string">entity_id</item>
</item>
</argument>
</actionsColumn>

На ділі, вони ідентичні. Єдина різниця це «indexField» елемент. За фактом, цей параметр не дуже важливий і не зачіпає функціональність, там немає життєво необхідних місць в його knockoutjs компонент коді. Так що я просто пропустив його в короткій формі, але це може не працювати в майбутніх оновленнях після рефакторінгу коду цього компонента.

Головна частина це клас, він повертає список опцій. Для імплементації класу на кшталт цього подивіться Magento\Cms\Ui\Component\Listing\Column\BlockActions.php.



Magento відображає дропдаун «Select» якщо є хоча б 1 опція.

Спосіб другий
Так само можна додати «action» стовпчик без створення нових класів.

<actionsColumn name="actions" class="Magento\Sales\Ui\Component\Listing\Column\ViewAction">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="indexField" xsi:type="string">entity_id</item>
<item name="viewUrlPath" xsi:type="string">ugrid/enity/view</item>
<item name="urlEntityParamName" xsi:type="string">uigrid_id</item>
</item>
</argument>
</actionsColumn>

Ви можете використовувати «Magento\Sales\Ui\Component\Listing\Column\ViewAction» клас. Він дуже корисний для багатьох випадків. Вам всього-то треба мати конфіг кшталт того, що показаний вище і primary key полем в БД має бути «entity_id».

<item name="indexField" xsi:type="string"> — див. вище,
<item name="viewUrlPath" xsi:type="string"> — урл сторінки редагування,
<item name="urlEntityParamName" xsi:type="string"> — ім'я entity_id поля, яке буде відправлятися на сторінку редагування як GET параметра. Дефолтний значення «entity_id», так що воно може бути пропущено, але якщо ви хочете відправляти щось відмінне від entity_id то вкажіть його як показано в прикладі.

Насправді параметри компонента можуть бути надані повністю через xml, але в такому випадку вам треба буде вказувати повний урл до сторінки редагування запису, що менш зручно.

Необхідно пам'ятати
Як тільки адмін відкриє грід сторінку в перший раз Magento збереже порядок стовпців, застосовану сортування даних, показані елементи і так далі в ui_bookmark таблицю і подальші зміни в ui_component.xml не зможуть змінити цього. Навіть якщо ви додасте новий стовпець в початок файлу або в середину, Magento буде відображати цей стовпець в самому кінці списку, навіть якщо останній стовпець «actions» і він був відзначений як не переміщуваний, ігноруючи sortOrder атрибут. Щоб скинути ці зміни вам знадобитися видалити всі записи, які мають нейм спейс ідентичний вашому гриду (ім'я файлу) з БД (як мінімум мають ідентифікатор «default», який застосовується до новим користувачам, і «current» якщо ви хочете скинути активні зміни користувача так само).

Висновок
Підводячи підсумок, я хотів би сказати, що ui компоненти мають масу можливостей. Завдяки knockoutjs та його впровадження в ui компоненти, розробники можуть створювати динамічний контент без додавання додаткових бібліотек і оновлення сторінок як це було в Magento 1. Єдиний недолік це те, що розробникам необхідно витратити певний час для розуміння ідеї та підходи для того, щоб почати працювати з новою фичей ефективно. Сама Magento 2, як і її документація, продовжує розвиватися кожен день. Перш за все зверніть увагу на . Це хороша ідея почати ваше занурення в ui компоненти з оффициальной документації. Ви можете знайти більше інформації про Ui Component посилання або тут.
Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.