Every <field> in form.xml combines two things: formElement (which input widget) and dataType (which data type is expected). This chapter walks through the most important combinations.

Text and textarea

<field name="title" formElement="input">
    <settings>
        <dataType>text</dataType>
        <label translate="true">Title</label>
    </settings>
</field>

<field name="message" formElement="textarea">
    <settings>
        <dataType>text</dataType>
        <label translate="true">Message</label>
    </settings>
</field>

WYSIWYG editor

For formatted text (HTML), Magento_Ui/js/form/element/wysiwyg wires in the TinyMCE editor:

<field name="message" formElement="wysiwyg">
    <settings>
        <wysiwygConfigData xsi:type="array">
            <item name="add_variables" xsi:type="boolean">false</item>
            <item name="add_widgets" xsi:type="boolean">false</item>
        </wysiwygConfigData>
        <dataType>text</dataType>
        <label translate="true">Message</label>
        <component>Magento_Ui/js/form/element/wysiwyg</component>
    </settings>
</field>

Select and boolean

Select fields use the same OptionSourceInterface class as the grid filters from chapter 6 - a single source of truth for both places:

<field name="is_active" formElement="checkbox">
    <settings>
        <valueMap>
            <map name="false" xsi:type="number">0</map>
            <map name="true" xsi:type="number">1</map>
        </valueMap>
        <dataType>boolean</dataType>
        <label translate="true">Enabled</label>
        <dataScope>is_active</dataScope>
    </settings>
    <formElements>
        <checkbox>
            <settings>
                <valueMap>
                    <map name="false" xsi:type="number">0</map>
                    <map name="true" xsi:type="number">1</map>
                </valueMap>
            </settings>
        </checkbox>
    </formElements>
</field>

valueMap translates between what the checkbox visually represents (true/false) and what actually ends up in the database (1/0) - without this mapping, an unchecked box would be stored as the string "false" instead of the integer 0.

Image upload

An upload field needs, besides the XML declaration, its own upload controller that receives and stores the file (chapter 16 builds this concretely for testimonials). The declaration itself:

<field name="image" formElement="imageUploader">
    <settings>
        <dataType>string</dataType>
        <label translate="true">Image</label>
    </settings>
    <formElements>
        <imageUploader>
            <settings>
                <uploaderConfig>
                    <param name="url" xsi:type="url" path="mironsoft_announcement/announcement/upload"/>
                </uploaderConfig>
                <previewTmpl>Magento_Catalog/image-preview</previewTmpl>
                <allowedExtensions>jpg jpeg png gif</allowedExtensions>
                <maxFileSize>2097152</maxFileSize>
            </settings>
        </imageUploader>
    </formElements>
</field>

uploaderConfig>url points at a controller that uses \Magento\Framework\File\Uploader, validates the file (type, size), and stores it in the media directory. Without that controller, the field shows nothing but a non-functional drag-and-drop area.

Overview: formElement/dataType combinations

• input / text - single-line text field.
• textarea / text - multi-line text field.
• wysiwyg / text - formatted HTML editor (TinyMCE).
• select / select - dropdown backed by OptionSourceInterface.
• checkbox / boolean - on/off checkbox with valueMap.
• imageUploader / string - image upload with drag and drop.