Reference - Form arguments

A Loki_AdminComponents form is a block that is defined within the XML layout by referring to the PHTML template Loki_AdminComponents::form.phtml and accompanied with various required or optional arguments.

<block name="yireo-training.example-admin.form" template="Loki_AdminComponents::form.phtml">
    <arguments>
        <argument name="foo" xsi:type="string">bar</argument>
    </arguments>
</block>

XML layout base arguments

A form block can be supplied with the following XML arguments:

provider (string or object, required)

A class or classname supported by available provider handlers, like collections, repositories or array providers.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="provider" xsi:type="string">Magento\Eav\Model\ResourceModel\Entity\Type\Collection</argument>
    </arguments>
</block>

If you want to pass the class as an object, it needs to implement Magento\Framework\View\Element\Block\ArgumentInterface.

provider_handler (string)

A string pointing to the provider handler. Often this is not needed. But it can be used if the automatic detection fails.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="provider_handler" xsi:type="string">repository</argument>
    </arguments>
</block>

resource_model (string or object)

By default, a repository handler is unable to retrieve column-information from the repository. By providing the classname for the resource_model, you can help the repository handler determine things automatically. This, or you need to supply the columns in a different way.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="provider" xsi:type="string">Magento\Cms\Model\PageRepository</argument>
        <argument name="resource_model" xsi:type="string">Magento\Cms\Model\ResourceModel\Page</argument>
    </arguments>
</block>

factory (string or object)

A class or classname to instantiate a model object when needed. This is (definitely) needed when creating new items. However, the core logic tries its best (via PHP Reflection) to detect the factory class automatically. This argument is only needed when this autodetection fails.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="factory" xsi:type="string">Magento\Cms\Model\PageFactory</argument>
    </arguments>
</block>

fields (array)

By default, the form tries to display all fields from the underlying table, but this might include fields that you don't want to display. By adding the fields property, you can add your own fields or overriding existing fields.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="id" xsi:type="array">
                <item name="label" xsi:type="string">Item ID</item>
            </item>
            <item name="name" xsi:type="string">
                <item name="label" xsi:type="string">Item Name</item>
            </item>
        </argument>
    </arguments>
</block>

index_url (string)

If the grid URL is not */*/grid, then it needs to be changed with this argument.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="index_url" xsi:type="string">*/*/index</argument>
    </arguments>
</block>

item_convertor (object)

An instance of Loki\AdminComponents\Form\ItemConvertorInterface to transform the item data before sending it to the form.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="item_convertor" xsi:type="object">YireoTraining\ExampleAdmin\Form\ExampleItemConvertor</argument>
    </arguments>
</block>

XML layout field arguments

label (string)

By default, the field label is extracted by converting the field name (example_item_name) into readable text (pascal-case with dashes replaced with spaces). The label can be customized with this argument.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="name" xsi:type="string">
                <item name="label" xsi:type="string">Item Name</item>
            </item>
        </argument>
    </arguments>
</block>

code (string)

This sets the name of the HTML form field and some other things. Usually, it should not be changed via XML layout, but simply is the same as the actual database column name.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="name" xsi:type="string">
                <item name="code" xsi:type="string">item_name</item>
            </item>
        </argument>
    </arguments>
</block>

sort_order (number)

Each field is supported by default in the order that they are detected - commonly, the order of the columns in the database structure. You can change this with this argument.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="name" xsi:type="string">
                <item name="sort_order" xsi:type="number">3</item>
            </item>
        </argument>
    </arguments>
</block>

field_type (string)

The default field_type is input, but you can customize this by setting the field_type.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="description" xsi:type="string">
                <item name="field_type" xsi:type="string">textarea</item>
            </item>
        </argument>
    </arguments>
</block>

required (boolean)

Boolean to indicate that the field is required.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="description" xsi:type="string">
                <item name="required" xsi:type="boolean">true</item>
            </item>
        </argument>
    </arguments>
</block>

placeholder (string)

Placeholder text.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="name" xsi:type="string">
                <item name="placeholder" xsi:type="string">Enter a name</item>
            </item>
        </argument>
    </arguments>
</block>

options (object)

When the field type allows for multiple options (like with select or switch), this class supplies the options. The class needs to be an instance of Magento\Framework\Data\OptionSourceInterface.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="store_id" xsi:type="string">
                <item name="field_type" xsi:type="string">select</item>
                <item name="options" xsi:type="string">Magento\Store\Ui\Component\Listing\Column\Store\Options</item>
            </item>
        </argument>
    </arguments>
</block>

multiple (boolean)

When the field type is select, this allows you to create a multiple select.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="store_id" xsi:type="string">
                <item name="field_type" xsi:type="string">select</item>
                <item name="options" xsi:type="string">Magento\Store\Ui\Component\Listing\Column\Store\Options</item>
                <item name="multiple" xsi:type="boolean">true</item>
            </item>
        </argument>
    </arguments>
</block>

size (boolean)

This allows you to set the HTML attribute size with select fields.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="store_id" xsi:type="string">
                <item name="field_type" xsi:type="string">select</item>
                <item name="options" xsi:type="string">Magento\Store\Ui\Component\Listing\Column\Store\Options</item>
                <item name="multiple" xsi:type="boolean">true</item>
                <item name="size" xsi:type="number">8</item>
            </item>
        </argument>
    </arguments>
</block>

empty_option (string)

When the field type is select, this allows you to add an additional empty option.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="store_id" xsi:type="string">
                <item name="field_type" xsi:type="string">select</item>
                <item name="options" xsi:type="string">Magento\Store\Ui\Component\Listing\Column\Store\Options</item>
                <item name="empty_option" xsi:type="string">Select a store</item>
            </item>
        </argument>
    </arguments>
</block>

field_attributes (array)

An associative array of attribute names and values to use as HTML attributes of the HTML field element. This can be anything. For instance, you can set the number of rows in an textarea. Or you can set a specific autocomplete value.

<block name="yireo-training.example-admin.form">
    <arguments>
        <argument name="fields" xsi:type="array">
            <item name="description" xsi:type="string">
                <item name="field_type" xsi:type="string">textarea</item>
                <item name="field_attributes" xsi:type="array">
                    <item name="rows" xsi:type="number">10</item>
                </item>
            </item>
        </argument>
    </arguments>
</block>

label_attributes (array)

An associative array of attribute names and values to use as HTML attributes of the HTML label element.