Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Commit 7478d5e

Browse files
JesseMaxwellJesseMaxwell
committed
Create a short tutorial on how to add a category attribute
1 parent aaaf31b commit 7478d5e

File tree

1 file changed

+102
-0
lines changed

1 file changed

+102
-0
lines changed

‎guides/v2.1/ui_comp_guide/howto/add_category_attribute.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
layout: default
3+
group: UI_Components_guide
4+
subgroup: howto
5+
title: How to add a Category Attribute
6+
menu_title: Creating and displaying a category attribute with UI Components
7+
menu_order: 3
8+
contributor_name: SwiftOtter Studios
9+
contributor_link: https://swiftotter.com/
10+
version: 2.1
11+
github_link: ui_comp_guide/howto/add_category_attribute.md
12+
---
13+
14+
# How to add a Category Attribute
15+
16+
Category attributes were automatically displayed in the admin panel of Magento 1. In Magento 2, it is necessary to explicitly render it with a UI Component. This is quite easy to do and provides a great degree of control over the form input. In the code examples below, replace `attribute_id` and `Your Category Attribute Name` with your own values.
17+
18+
### Step #1: Create the Attribute
19+
20+
The following is a full example of an install script that creates a category attribute. If you already have a category attribute, it is not necessary.
21+
22+
```php
23+
// File: Namespace/Module/Setup/InstallData.php
24+
25+
use Magento\Framework\Setup\{
26+
ModuleContextInterface,
27+
ModuleDataSetupInterface,
28+
InstallDataInterface
29+
};
30+
31+
use Magento\Eav\Setup\EavSetup;
32+
use Magento\Eav\Setup\EavSetupFactory;
33+
34+
class InstallData implements InstallDataInterface
35+
{
36+
private $eavSetupFactory;
37+
38+
public function __construct(EavSetupFactory $eavSetupFactory) {
39+
$this->eavSetupFactory = $eavSetupFactory;
40+
}
41+
42+
public function install(ModuleDataSetupInterface $setup, ModuleContextInterface $context)
43+
{
44+
$eavSetup = $this->eavSetupFactory->create(['setup' => $setup]);
45+
$eavSetup->addAttribute(\Magento\Catalog\Model\Category::ENTITY, 'attribute_id', [
46+
'type' => 'int',
47+
'label' => 'Your Category Attribute Name',
48+
'input' => 'boolean',
49+
'source' => 'Magento\Eav\Model\Entity\Attribute\Source\Boolean',
50+
'visible' => true,
51+
'default' => '0',
52+
'required' => false,
53+
'global' => \Magento\Eav\Model\Entity\Attribute\ScopedAttributeInterface::SCOPE_STORE,
54+
'group' => 'Display Settings',
55+
]);
56+
}
57+
}
58+
```
59+
60+
### Step #2: Display the Attribute
61+
62+
The category UI Component is rendered with configuration from the `category_form.xml` file. All files with that name are merged together. As a result, you can add a field by creating a `category_form.xml` file in the `view/adminhtml/ui_component` directory in your module.
63+
64+
Here is a full example of adding a field under the "Display Settings" group. It is important to note that `attribute_id` should match the ID of the attribute that you created in the install script.
65+
66+
```xml
67+
<!-- Namespace/Module/view/adminhtml/ui_component/category_form.xml -->
68+
<?xml version="1.0"?>
69+
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
70+
<fieldset name="display_settings">
71+
<field name="attribute_id">
72+
<argument name="data" xsi:type="array">
73+
<item name="config" xsi:type="array">
74+
<item name="dataType" xsi:type="string">boolean</item>
75+
<item name="formElement" xsi:type="string">checkbox</item>
76+
<item name="label" xsi:type="string" translate="true">Your Category Attribute Name</item>
77+
<item name="prefer" xsi:type="string">toggle</item>
78+
<item name="valueMap" xsi:type="array">
79+
<item name="true" xsi:type="string">1</item>
80+
<item name="false" xsi:type="string">0</item>
81+
</item>
82+
<item name="default" xsi:type="number">0</item>
83+
</item>
84+
</argument>
85+
</field>
86+
</fieldset>
87+
</form>
88+
```
89+
90+
### Step #3: Upgrade and Run
91+
92+
[Upgrade the database schema](http://devdocs.magento.com/guides/v2.0/install-gde/install/cli/install-cli-subcommands-db-upgr.html) to install the attribute [and clear your cache](http://devdocs.magento.com/guides/v2.0/howdoi/php/php_clear-dirs.html#howdoi-clear-how).
93+
94+
#### How it works
95+
96+
UI Component configuration is merged. When you add a new file, Magento will merge that with the base UI Component configuration file. In the example above, that is `category_form.xml`. The nodes inside of that reflect the structure of the base file. There are only two nodes necessary in this case before the custom field is added: `<form>` and `<fieldset>`. Inside of that, the `<field>` node is used to add a field with a name that matches the id of the attribute you want to render.
97+
98+
The `<field>` node is declared originally in `vendor/magento/module-ui/view/base/ui_component/etc/definition.xml`. If you open that file and look for `<field>`, you will notice that there is only a PHP class referenced—nothing particularly helpful. This is where the `config` elements in the example above come in important. Notice the value of `<item name="formElement">` (`checkbox`)? Now, if you look in `definition.xml`, you will find a `<checkbox>` node that has some configuration values. In the PHP class that the `<field>` element references, it looks up the `formElement` to use and loads that. As a result, `<checkbox>` is the node. In this case, that has the information that we are looking for.
99+
100+
One of those elements is particularly useful when determining what XML you need to provide for your field: `<item name="component">`. That is a Javascript file that handles the functionality of the field. In our case, it is located in `vendor/magento/module-ui/view/base/web/js/form/element/single-checkbox.js`. If you open that file, there is a `defaults` object which contains values that can be modified through the XML above. For example, notice: `defaults.prefer: 'checkbox'`. In the XML above, we declared `<item name="prefer">toggle</item>`. As a result, the XML value overrides the default value, and the Javascript renders a toggle instead of a plain checkbox.
101+
102+
This opens up the opportunity for you to customize nearly anything about the UI Component. It also should provide you with a basis of how to determine what configuration is available for you to set through XML.

0 commit comments

Comments
 (0)