What does <requires> tag mean in a backend config field XML declaration?

dmitry_fedyuk · February 6, 2016, 11:45pm

The <requires> tag allows a module developer to require a store administrator to fill the specified fields before some other field will be enabled.

An example: Why is «Enable this Solution» backend control disabled for the Braintree payment module?

Usage examples

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Braintree/etc/adminhtml/system.xml#L25-L27


<requires>
    <group id="braintree_required"/>
</requires>

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/BraintreeTwo/etc/adminhtml/system.xml#L25-L27


<requires>
    <group id="braintreetwo_required"/>
</requires>

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Paypal/etc/adminhtml/system/express_checkout.xml#L130-L132


<requires>
    <group id="express_checkout_required_express_checkout"/>
</requires>

XML schema definition

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/etc/system_file.xsd#L265-L269


<xs:annotation>
    <xs:documentation>
        Field Requirements
    </xs:documentation>
</xs:annotation>

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/etc/system_file.xsd#L271-L278


<xs:complexType>
    <xs:sequence>
        <xs:choice minOccurs="0" maxOccurs="unbounded">
            <xs:element type="requiresField" name="field" />
            <xs:element type="requiresGroup" name="group" />
        </xs:choice>
    </xs:sequence>
</xs:complexType>

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/etc/system_file.xsd#L280-L288


<xs:unique name="uniqueRequiresFieldId">
    <xs:annotation>
        <xs:documentation>
            Attribute id is unique under field requires block
        </xs:documentation>
    </xs:annotation>
    <xs:selector xpath=".//field"/>
    <xs:field xpath="@id"/>
</xs:unique>

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/etc/system_file.xsd#L290-L298


<xs:unique name="uniqueRequiresGroupId">
    <xs:annotation>
        <xs:documentation>
            Attribute id is unique under group requires block
        </xs:documentation>
    </xs:annotation>
    <xs:selector xpath=".//group"/>
    <xs:field xpath="@id"/>
</xs:unique>

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/etc/system_file.xsd#L301-L312


<xs:complexType name="requiresField" mixed="true">
    <xs:annotation>
        <xs:documentation>
            Required field resource. Recursive complex type
        </xs:documentation>
    </xs:annotation>
    <xs:simpleContent>
        <xs:extension base="xs:string">
            <xs:attribute name="id" type="typeElementPath" use="required" />
        </xs:extension>
    </xs:simpleContent>
</xs:complexType>

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/etc/system_file.xsd#L314-L321


<xs:complexType name="requiresGroup">
    <xs:annotation>
        <xs:documentation>
            Required group resource. Recursive complex type
        </xs:documentation>
    </xs:annotation>
    <xs:attribute name="id" type="typeElementPath" use="required" />
</xs:complexType>

How is it processed

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/Model/Config/Structure/Element/Field.php#L150-L170


/**
 * Get required elements paths for the field
 *
 * @param string $fieldPrefix
 * @param string $elementType
 * @return string[]
 */
protected function _getRequiredElements($fieldPrefix = '', $elementType = 'group')
{
    $elements = [];
    if (isset($this->_data['requires'][$elementType])) {
        if (isset($this->_data['requires'][$elementType]['id'])) {
            $elements[] = $this->_getPath($this->_data['requires'][$elementType]['id'], $fieldPrefix);
        } else {
            foreach ($this->_data['requires'][$elementType] as $element) {
                $elements[] = $this->_getPath($element['id'], $fieldPrefix);
            }
        }
    }
    return $elements;
}

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/Model/Config/Structure/Element/Field.php#L172-L181


/**
 * Get required groups paths for the field
 *
 * @param string $fieldPrefix
 * @return string[]
 */
public function getRequiredGroups($fieldPrefix = '')
{
    return $this->_getRequiredElements($fieldPrefix, 'group');
}

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/Model/Config/Structure/Element/Field.php#L183-L192


/**
 * Get required fields paths for the field
 *
 * @param string $fieldPrefix
 * @return string[]
 */
public function getRequiredFields($fieldPrefix = '')
{
    return $this->_getRequiredElements($fieldPrefix, 'field');
}

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/Block/System/Config/Form.php#L659-L679


/**
 * Get css class for "requires" functionality
 *
 * @param \Magento\Config\Model\Config\Structure\Element\Field $field
 * @param string $fieldPrefix
 * @return string
 */
protected function _getRequiresCssClass(\Magento\Config\Model\Config\Structure\Element\Field $field, $fieldPrefix)
{
    $requiresClass = '';
    $requiredPaths = array_merge($field->getRequiredFields($fieldPrefix), $field->getRequiredGroups($fieldPrefix));
    if (!empty($requiredPaths)) {
        $requiresClass = ' requires';
        foreach ($requiredPaths as $requiredPath) {
            $requiresClass .= ' requires-' . $this->_generateElementId($requiredPath);
        }
        return $requiresClass;
    }
    return $requiresClass;
}
}

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/Block/System/Config/Form.php#L348-L348


$requiresClass = $this->_getRequiresCssClass($field, $fieldPrefix);

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/Block/System/Config/Form.php#L361-L361


'class' => $field->getFrontendClass() . $sharedClass . $requiresClass,

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/view/adminhtml/templates/system/config/edit.phtml#L203-L215


window.configForm = jQuery('#config-edit-form').mage('form').mage('validation', {
    submitHandler: function(form)
    {
        $$('.requires').each(function(element) {
            var scopeElement = adminSystemConfig.getScopeElement(element);
            if (!scopeElement || !scopeElement.checked) {
                Element.extend(element).disabled = false;
            }
        });
        jQuery(form).trigger('afterValidate');
        form.submit();
    }
});

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/view/adminhtml/templates/system/config/edit.phtml#L299-L305


// fill eventObj with required elements
adminSystemConfig.mapClasses(element, false, function(className) {
    var requiredElement = Element.extend(document.getElementById(className.substr(9)));
    if (requiredElement) {
        eventObj.requires.push(requiredElement);
    }
}, 'requires');

github.com

magento/magento2/blob/6ce74b2/app/code/Magento/Config/view/adminhtml/templates/system/config/edit.phtml#L256-L325


$$('.requires').each(function(element) {
    var eventObj = {
        'element': Element.extend(element),
        'requires': [],
        'callback': function(required) {},
        checkRequirements: function() {
            var scopeElement = adminSystemConfig.getScopeElement(eventObj.element);
            if (!scopeElement || !scopeElement.checked) {
                eventObj.element.enable();
                eventObj.requires.each(function(required) {
                    adminSystemConfig.checkRequired.call(Element.extend(required), eventObj.element, eventObj.callback);
                }.bind(this));
            }
        },
        keydownCheckRequirements: function() {
            window.setTimeout(eventObj.checkRequirements, 1);
        },
        bindCheckingObserver: function(element) {
            if (element.tagName.toLowerCase() == 'fieldset') {
                Element.extend(element).select('input,select').each(function(subElement) {
                    eventObj.bindCheckingObserver(subElement);
                })
            } else {
                var scopeElement = adminSystemConfig.getScopeElement(element);
                if (scopeElement) {
                    Event.observe(scopeElement, 'click', eventObj.checkRequirements);
                }
                Event.observe(element, 'change', eventObj.checkRequirements);
                Event.observe(element, 'keydown', eventObj.keydownCheckRequirements);
            }
        },
        indicateEnabled: function() {
            var labelElement = adminSystemConfig.getUpTr(eventObj.element).select('td.label label')[0];
            if (typeof labelElement != 'undefined') {
                if (eventObj.element.value == 1) {
                    labelElement.addClassName('enabled');
                } else {
                    labelElement.removeClassName('enabled');
                }
            }
        }
    };


    // fill eventObj with required elements
    adminSystemConfig.mapClasses(element, false, function(className) {
        var requiredElement = Element.extend(document.getElementById(className.substr(9)));
        if (requiredElement) {
            eventObj.requires.push(requiredElement);
        }
    }, 'requires');
    Element.extend(element).requiresObj = eventObj;


    // replacing "Use Default" action with checking requirements
    var scopeElement = adminSystemConfig.getScopeElement(element);
    if (scopeElement) {
        Event.stopObserving(scopeElement, 'click');
        Event.observe(scopeElement, 'click', function(event) {
            toggleValueElements(scopeElement, Element.previous(scopeElement.parentNode));
            eventObj.checkRequirements();
        });
    }


    // binding events
    eventObj.requires.each(function(required) {
        eventObj.bindCheckingObserver(required);
    });
    Event.observe(eventObj.element, 'change', eventObj.indicateEnabled);
    eventObj.checkRequirements();
    eventObj.indicateEnabled();
});

dmitry_fedyuk · February 27, 2016, 10:52pm