Keeping Magento 2 Admin settings organised

There are a few things that come included in Magento 2 which help in keeping your admin settings easy to use.

Hide unused settings

First - it's always a good idea to remove as many settings as possible. This obviously needs to be weighed up with the need in making your module customisable. One thing which helps in this endeavour is to hide settings which don't have any impact with the current configuration. In other words if a certain setting only makes sense when a certain other setting is set to a particular value we can hide it. Magento offers this out of the box using the <depends> node.

<!-- etc/adminhtml/system.xml-->
<field id="exportwithstatus" translate="label" sortOrder="61" type="multiselect" showInDefault="1"
       showInWebsite="1" showInStore="1">
    <label>Export Orders with Status</label>
        <field id="exportmode">order</field>

You can even do something like

<!-- etc/adminhtml/system.xml-->
<field id="paypalrefundbankaccount" translate="label" sortOrder="425" type="select" showInDefault="1"
       showInWebsite="1" showInStore="1">
    <label>Bank Account for Paypal Refunds</label>
        <field id="xerostatus">AUTHORISED</field>
        <field id="cashrefund">1</field>

which will only show the above setting if the two other settings (xerostatus and cashrefund) have been set to a certain value.

Group similar settings

Next with Magento 2 you can now add one extra layer to group similar settings together compared to Magento 1:

to use it nest an additional level of <group> nodes and Magento will take care of the open/shut toggles:

<!-- etc/adminhtml/system.xml-->
    <section id="sales_pdf">
        <group id="all" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1"
            <label>Common Pdf Settings</label>
            <group id="page" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1"
                   showInStore="1" canRestore="1">
                <label>Page Settings</label>
                <field id="allpagesize" translate="label" type="select" sortOrder="100" showInDefault="1"
                       showInWebsite="0" showInStore="0">
                    <label>Page Size</label>

Migrating settings

One trick to keep in mind is - as your module develops, your settings likely evolve over time as well. This could lead to the need to re-organise your settings and shift them around to a new group to keep them easy to use. Without any further action on your part this could unfortunately mean that your existing users would either need to reconfigure the extension or you would need to write some upgrade data script that migrates your settings to the new path. Fortunately there is a 3rd option which makes this super easy:

<!-- etc/adminhtml/system.xml-->
<field id="displayboth" translate="label" type="select" sortOrder="600" showInDefault="1"
       showInWebsite="1" showInStore="1" canRestore="1">
    <label>Display Base and Order Currency</label>

By adding a config_path node with the old path we have the best of both worlds: An easier to work with admin area while keeping the original settings intact.

Kristof Ringleff

Kristof Ringleff

Founder and Lead Developer at Fooman

Join the Fooman Community

We send our popular Fooman Developer Monthly email with Magento news, articles & developer tips, as well as occasional Fooman extension updates.