System settings in OroCRM. Overview

In the previous article we’ve described how to add a setting to your extension and make it work. We reviewed only two general field types: text and password, however, there are many other field types that you will meet in your development practice. Actually, you are able to find the general fields description in the Symfony manual, but OroCRM has its own types based on the general. Let’s try to review most of this fields.

As you remember from the previous article, you need to put your setting initialisation in few places of your bundle. It’s DependencyInjection/Configuration.php and Resources/config/system_configuration.yml. Since the main details of the setting are stored in the last file (system_configuration.yml) we will overview the pieces of code from this file.

# Text field

    type: text
    priority: 0
        label: 'Account Name'
        tooltip: 'Text Field'

Text field represents the most basic input text field.


# Password field

    type: password
    priority: 1
        label: 'Account Password'
        tooltip: 'Password Field'

Password field renders an input password text box.


# Textarea field

    type: textarea
    priority: 2
        label: 'Custom textarea'
        tooltip: 'Textarea'

Textarea field renders a textarea HTML element.


# Email field
    type: email
    priority: 3
        label: 'Custom email'
        tooltip: 'Email Field'

Email field is a text field that is rendered using the HTML5 <input type=”email” /> tag.


#Integer field

    type: integer
    priority: 4
        label: 'Custom number'
        tooltip: 'Integer Field'

Integer field renders an input “number” field. The input number field looks like a text box, except that – if the user’s browser supports HTML5 – it will have some extra frontend functionality.


#Money field
    type: money
    priority: 5
        label: 'How much?'
        currency: 'USD'
        precision: '2'
        tooltip: 'Money Field'

Money field renders an input text field that is handling submitted “money” data. This field type allows you to specify a currency and what symbol is rendered next to the text field. There are also several other options for customisation how the input and output of the data are handled.


In the configuration file you can see two additional parameters for this field:

currency – defines the currency that the money is being specified in. This determines the currency symbol that should be shown by the text box.

precision – determines how many digits should be handled after the point.

Text fields described above accept few additional parameters:

max_length – if this option is not null, an HTML attribute ‘maxlength’ is added, which is used by some browsers to limit the amount of text in a field.

trim – if true, the whitespace of the submitted string value will be stripped via the trim() function when the data is bound.

read_only – if this option is true, the field will be rendered with the readonly attribute so that the field is not editable.

disabled – if you don’t want a user to modify the value of a field, you can set the disabled option to true. Any submitted value will be ignored.

#Choice field
    type: choice
    priority: 6
        label: 'A select'
        tooltip: 'Choice Field'
            0: 'To be!'
            1: 'Not to be..'

Choice field is a multi-purpose field used to allow the user to “choose” one or more options. It can be rendered as a select tag, radio buttons or checkboxes.


The ‘choices’ parameter contains a list of items that should be used by this field. Also, this field type has few additional important parameters:

multiple – if true, the user will be able to select multiple options.

expanded – if it is set to true, radio buttons or checkboxes will be rendered (depending on the multiple values). If false, a select element will be rendered.

Very often it’s necessary to populate the choices dynamically. We are going to review how to achieve this in our next article.

#Country field
    type: oro_locale_country
    priority: 7
        label: 'Country'
        tooltip: 'Country Field'

Country field it’s a choice field prefilled with countries of the world. The “value” for each country is the two-letter country code.


#Language field

    type: oro_language
    priority: 8
        label: 'Language'
        tooltip: 'Language Field'

Language field it’s a choice field prepopulated with the large list of languages. The “value” for each language is the Unicode language identifier.


#Timezone field

    type: oro_locale_timezone
    tooltip: 'Timezone Field'
    priority: 9
        label: 'Timezone'

Timezone field it’s a choice field prepopulated with the list of all possible timezones. The “value” for each timezone is the full timezone name, such as America/Chicago or Europe/Istanbul.


#Currency field

    type: oro_currency
    tooltip: 'Currency Field'
    priority: 10
        label: 'Currency'

Currency field it’s a choice field prepopulated with the large list of 3-letter ISO 4217 currencies.


#Date field
    type: oro_date
    priority: 11
        label: 'Date'
        tooltip: 'Date Field'

Date field allows user to modify date information via variety of different HTML elements.


#Datetime field

    type: oro_datetime
    priority: 12
        label: 'Datetime'
        tooltip: 'Datetime Field'

Datetime field allows user to modify data that represents a specific date and time. Also, it can be rendered as a text input or choice field.


In Symfony the date field, as well as datetime field, allows you to choose a ‘widget’ which determines how exactly the date input is shown. But since OroCRM has its own handy widget for date and time selection it’s not necessary to change the widget type in most cases.

#Checkbox field

    type: oro_config_checkbox
    priority: 13
        label: 'Check me'
        tooltip: 'Checkbox Field'

Checkbox field it’s a single checkbox input. This should always be used for a field that has a Boolean value: if the box is checked, the field will be set to true, if the box is unchecked, the value will be set to false.


#File field

    type: file
    priority: 14
        label: 'Upload'
        tooltip: 'File Field'

File field represents a file input in your form.


When the form is submitted, the attachment field will be an instance of UploadedFile. It can be used to move the attachment file to a permanent location.

There was a short overview of the commonly used configuration fields. As were mentioned above, in the next articles we plan to describe how to implement your own dynamic choice fields and how to operate with uploaded files. Also, keep in mind that you are always able to create your own field (form type) by using the standard types as a basis. Feel free to ask your questions and leave your recommendations in the comments bellow. Have nice settings ;)