Fields dependency in Magento admin forms

In this article we would like to cover a topic about a neat feature of admin forms, that will make management of your module’s data by store staff more convenient.

This feature is called fields dependency which allows to build logic with minor coding effort. For example, this is very useful in case you have a status field for the entry. Let’s say we have Allowed and Denied statuses. Allowed – should ask for additional data and Denied status should allow entering denial reason. Here is a code to build required fields and the dependency logic:

protected function _prepareForm()
{
        $form = new Varien_Data_Form();
        $this->setForm($form);

        $fieldSet = $form->addFieldset('entity_form', array(
            'legend'=>Mage::helper('module')->__('Entity Information')
        ));

        $status = $fieldSet->addField('status', 'select', array(
            'label'     => Mage::helper('module')->__('Status'),
            'name'      => 'status',
            'values'    => array(
                'Approved' => 'Approved',
                'Denied'   => 'Denied'
            )
        ));

        $denyReason = $fieldSet->addField('denial_reason', 'textarea', array(
            'label'     => Mage::helper('module')->__('Denial Reason'),
            'name'      => 'denial_reason'
        ));

        $approveInfo = $fieldSet->addField('approve_info', 'text', array(
            'label'     => Mage::helper('module')->__('Approve Information'),
            'name'      => 'approve_info'
        ));

        if (Mage::getSingleton('adminhtml/session')->getFormData()) {
            $_data = Mage::getSingleton('adminhtml/session')->getFormData();
            Mage::getSingleton('adminhtml/session')->setFormData(null);
        } elseif (Mage::registry('form_data')) {
            $_data = Mage::registry('form_data')->getData();
        }

        $form->setValues($_data);

        $this->setForm($form);
        $this->setChild('form_after', $this->getLayout()->createBlock('adminhtml/widget_form_element_dependence')
            ->addFieldMap($status->getHtmlId(), $status->getName())
            ->addFieldMap($denyReason->getHtmlId(), $denyReason->getName())
            ->addFieldMap($approveInfo->getHtmlId(), $approveInfo->getName())
            ->addFieldDependence(
                $approveInfo->getName(),
                $status->getName(),
                'Approved'
            )
            ->addFieldDependence(
                $denyReason->getName(),
                $status->getName(),
                'Denied'
            )
        );

        return parent::_prepareForm();
}

The block class, which does all this magic, is Mage_Adminhtml_Block_Widget_Form_Element_Dependence, you can check its usage by other core modules for more examples.

Needless to say, this can be achieved even more easily in module’s configuration system.xml file using depends node. You can read about this technique at the bottom of an excellent EComDev article “Custom configuration fields in Magento“, but don’t miss other essential stuff :)

We hope this article unveiled another cool Magento feature for you. Let us know what you like the most about coding for Magento backend in the comments below.