System settings in OroCRM. Introduction

Recently we have described how to create your own OroCRM extension and, even more, how to add a new menu item (see Add a new menu item). Now it is time to move forward. Almost each extension, no matter how big it is, needs to have some settings. Of course, we can put it into an *.yml’. No problem, but OroCRM core developers provide us with a handy ability to create your own settings fields/section on the System->Configuration page.

To proceed with the settings you need to have your own extension created. If you have not created it yet, you can follow instructions in the article mentioned above. First of all, you need to add an additional YML file to your bundle. Go to src/Atwix/Bundle/TestBundle/Resources/config/ and create the system_configuration.yml there with the following content:

#src/Atwix/Bundle/TestBundle/config/system_configuration.yml
oro_system_configuration:
    groups:
        test_bundle_settings:
            icon:   icon-bullhorn
            title:  'Test Bundle'
        test_bundle_general_settings:
            title:  'General'
    fields:
        atwix_test.login:
            type: text
            priority: 10
            options:
                label: 'Login'
        atwix_test.password:
            type: password
            priority: 5 
            options:
                label: 'Password'


    tree:
        system_configuration:
            platform:
                children:
                    general_setup:
                        children:
                            test_bundle_settings:
                                children:
                                    test_bundle_general_settings:
                                        children:
                                            - atwix_test.login
                                            - atwix_test.password

This yml configuration identifies tabs/groups/fields and describes the hierarchy of your settings as well. As you can see, we are adding a tab test_bundle_settings and group test_bundle_general_settings. After this we are editing two fields atwix_test.login (text field) and atwix_test.password (password field). Then, in the tree section we are configuring our settings three. You can set an icon for your tab by using the icon parameter. As you may know, OroCRM uses Font Awesome – the iconic font and CSS framework. You can choose any icon from the predefined icons set for your tab (see Font Awesome Icons Set).

Also, the field has required property type which describes the type of a form field for your settings (i.e. text, textarea, checkbox etc.). They might also have the following additional parameters:

• • tooltip – shows additional information about field
  • acl_resource – determines acl resource to check permissions to change config field value(optional)
  • priority – sorts order for displaying (optional)

The options property of a field allows to pass additional parameters for the form element. This property is tightly connected to a form element type.

On the next step, your settings need to be initialised for loading/saving. In your bundle find the following file src/Atwix/Bundle/TestBundle/DependencyInjection/Configuration.php. There find a method called getConfigTreeBuilder() and add the following lines into it:

SettingsBuilder::append(
            $rootNode,
            array(
                login => array('value' => null),
                password => array('value' => null, 'type' => 'password'),
            )
        );

Then you need to let Oro know that we have included our configuration. To make it happens open your src/Atwix/Bundle/TestBundle/DependencyInjection/AtwixTestExtension.php with the only one method inside called load(). Add the following line there:

$container->prependExtensionConfig($this->getAlias(), array_intersect_key($config, array_flip(['settings'])));

That’s all, now you should be able to see the newly added setting on the System->Configuration page:

In the next articles we are going to describe how to handle different types of settings. If you have any questions or proposals – just let us know in the comments below. Thanks for reading us.