photo credit: Swiss Army Switchboard Hasler H-88 via photopin (license)

Adding System configuration in Magento 2

When developing a site with Magento 2, you might want to be able to add some custom settings to the system configuration. This can be settings that reflect on your template, or settings that apply to your module. In Magento 1, this could be easily done by creating a system.xml  file. Magento 2 has a similar technique that I’ll explain in this article.
Please note that we use the boilerplate module from the article ‘Creating a module in Magento 2‘ as the entry point for this article.

The system.xml file in Magento 2

As I said before, Magento 2 has a similar way to creating system configuration entries. Like Magento 1, Magento 2 uses a file called system.xml , which is located in the etc/adminhtml -folder of your module. Let’s create such a file right now, with the most basic elements. We’ll explain the content of the file further on:

Break it down

Let’s start with the the section where we add a new tab:

This part declares a new tab in your systems’ configuration, and gives it an ID. The ID is used later on when we are going to declare our sections. So let’s take a look at our first section, with the ID ‘example’:

Here we declare a section in the system configuration. In the <tab> -node we tell this section in which tab it must be. The <resource> -node is used to set our rights with our Access Control List (ACL), more information on this is described further on in this article. Last but not least, we declare a <group> -node, in which we declare the fields that we want to have in our system configuration:

This example adds 2 fields of the input type ‘select’, with 2 different source models:

  • Magento\Config\Model\Config\Source\Yesno : which has 2 options: ‘Yes’ and ‘No’.
  • Gielberkers\Example\Model\Config\Source\Example : which is a basic example of a custom source model. You might need those more than you think.

We also add a simple text input and show a basic dependency example.

What do we have so far?

At this point, when you flush the cache and navigate to your stores’ configuration, you’ll notice that our new configuration node is already picked up:

Screen Shot 2016-03-16 at 21.41.47
However, when you click on the ‘Example’-link, you’ll get presented with a big fat error message. This is because we declared a source model in our system.xml that doesn’t exist (yet): Gielberkers\Example\Model\Config\Source\Example . So let’s create it: Make a file called Example.php  and place it in Model/Config/Source :

For those who know Magento 1 this code might look familiar because it follows the same pattern: the only thing a source model does, is that it returns data that can be presented in a dropdown (at least, that’s what’s it’s used most for).
Now when we reload our configuration we can see our options:

Screen Shot 2016-03-16 at 21.48.12
Pretty neat huh?

Access Control List (ACL)

Now you might have noticed that we’ve talked about the Access Control List (ACL) before. The ACL is the part of Magento that allow us to set permissions for certain items. With the ACL we can create roles for different users so that not every user has the same rights. To make use of the ACL we added a <resource> -node to our system.xml  file:

To put this in effect we add a file called acl.xml  to our etc -folder of our module:

The key in this file is the following line:

Note that it is nested between other resources. This is necessary because the system configuration of Magento is build like in this tree-like structure. This becomes more clearly when you want to allow (or deny) access to this configuration when you are creating or editing a user role:

Screen Shot 2016-03-16 at 21.55.35
That’s it, simple as that. You are now able to add your own settings to the system configuration of Magento 2 and set the proper permissions for those who are allowed to edit them. But wait! There is still one thing left to do:

How can we use these settings?

A very proper question indeed: how can we use these settings? Well, there are various places where your configuration settings might come in handy, so let’s discuss some of them here:

Custom menu items in the admin

When you’re adding custom menu items in the admin, you can depend these on the settings in the configuration. This can be great to show or hide certain menu items when settings are disabled. For example:

Layout updates in your theme

You can decide whether or not to render a block depending on a system configuration setting:

In your code

When you use it in your code, you can make use of the scopeConfig -parameter in a helper to get a configuration setting:

Blocks, Models, templates, etc. can all make use of a method of your helper to get a proper configuration value:

In conclusion

As you see, creating and using a system configuration in Magento 2 is fairly simple once you get the main concept of it. Once you embrace it and you make proper use of the available fields and possibilities, there are a lot of things you can let your client configure. If it’s for your module or your theme: it’s all possible!

This post is part of the series Magento 2 Development from Scratch.

Visitors give this article an average rating of 4.3 out of 5.

How would you rate this article?

4 thoughts on “Adding System configuration in Magento 2”

  1. Manish says:

    Great tutorial

    Please, may you explain how to show hide complete group on yes/no field of a different group.
    for example if we select enable -> no from general group then other group must be hide and vice-vera.


    1. Giel Berkers says:

      I’m not sure if you can hide a complete group depending on a setting. You could always try to add some custom JavaScript to do this of course although that might not be the most elegant solution. I do notice that the group-node of the system.xml-file has an attribute called ‘advanced’. Not sure what it does, but maybe that it hides some advanced functionality that you can use?

      1. Manish says:

        Thanks for your valuable feedbak.

  2. Frederik says:

    Great article, better then others, which forgot some essential parts so I couldn’t get it work. Now it works perfectly! 🙂
    One thing: because the options “something” and “something_else” depend on “enabled”, the screenshot of the reloaded configuration isn’t what I saw, which confused me. By default you’ll only see the enabled option, when switching No to Yes, you’ll see the other two as well.

Leave a Reply