Settings¶

Core Settings¶

Core settings are located in the Administration panel on the Settings page (see the top menu). They are split into sections:

• General
• Appearance
• Company
• Stores
• Checkout
• E-mails
• Thumbnails
• Sitemap
• Vendors
• Upgrade center
• Security settings
• Image verification—this section was hidden starting with version 4.5.1
• Logging
• Reports
• Settings wizard

A setting or a section with settings may or may not appear, depending on edition_type (see Attachment 1: Possible Values of edition_type). A setting can have different values, depending on the storefront or vendor. Usually a core setting must belong to a section. If a setting doesn’t belong to a section, the setting will be hidden.

For example, when there are multiple storefronts, the Alternative currency display format (edition_type="ROOT,STOREFRONT") will look like this:

Add-on Settings¶

Add-on settings are managed under Add-ons → Manage add-ons (see the top menu in the Administration panel). Most add-ons have their own settings. To open the settings of an add-on, use one of the two ways:

• Click the name of the add-on.
• Hover over the add-on. The gear button will appear on the right. Click it and choose Settings. Settings may not be available when a certain edition_type is set for them.

For example, here are the settings of the SEO add-on:

The Registry Class¶

The Registry class allows to access settings from any part of the application. This class also performs caching of settings (see the var/cache/registry folder).

Here is how settings are controlled with the Registry class:

• Getting the value of a core/add-on setting for the current storefront or company:

  Registry::get('settings.SECTION_NAME.SETTING_NAME');
  Registry::get('addons.ADDON_NAME.SETTING_NAME');
  

• Changing the value of a core/add-on setting:

  Registry::set('settings.SECTION_NAME.SETTING_NAME', 'Some value');
  Registry::set('addons.ADDON_NAME.SETTING_NAME', 'Some value');
  

The Settings Class¶

The Settings class is an extended API that exists specifically to work with settings stored in the database. This class has many methods: checking the availability of settings; reading, changing, and removing the values of settings.

For example, here’s how to manage the elements_per_page setting (Elements per page from Settings → Appearance) with the Settings class:

• Checking the availability of the setting:

  Settings::instance()->isExists('elements_per_page', 'Appearance');
  

• Getting the value of the setting:

  Settings::instance()->getValue('elements_per_page', 'Appearance');
  

• Changing the value of the setting:

  Settings::instance()->updateValue('elements_per_page', $new_value, 'Appearance');
  

When working with the settings, keep in mind that they can have storefront- and company-specific values.

In some cases the storefront and the company are detected automatically, but it’s recommended to explicitly specify them:

$settings_manager = Settings::instance(['storefront_id' => 4, 'company_id' => 17]);
$settings_manager->getValue('elements_per_page', 'Appearance');

Moreover, this is the only way to access vendor-specific settings in Multi-Vendor.

Declaring Settings in addon.xml¶

Settings of an add-on are declared in the addon.xml file located in the directory of that add-on. The list of settings is added to the <settings> section of addon.xml.

Here are the attributes of the <settings> section:

• layout—determines the look of the window with the add-on’s settings. By default, settings will appear in a pop-up window; if you specify layout="separate", settings will appear on a separate page.
• edition_type—determines when and where the setting will be available (see Attachment 1: Possible Values of edition_type).

For example, <settings layout="separate" edition_type="ROOT"> means that the settings will appear on a separate page and will be available in the All stores/All vendors mode.

Structure of the <settings> Section¶

<settings layout="separate" edition_type="ROOT,ULT:VENDOR">
        <sections>
        <!--
            The list of tabs (sections) in add-on settings
        -->
            <section id="section1">
            <!--
                A section with settings has the following attributes:
                * id:           An identifier used to address the section.
                * edition_type: Determines when and where the section is available;
                                this parameter is optional and supports
                                multiple variants separated by commas.
            -->
                <items>
                <!--
                    The list of settings in the section
                -->
                    <item id="header">
                    <!--
                        A setting has the following attributes:
                        * id:           An identifier used to address the setting:
                                        Registry::get('addons.[addon_id].[setting_id]')
                        * edition_type: Determines when the setting is available;
                                        this parameter is optional and supports
                                        multiple variants separated by commas.
                    -->
                        <type>header</type>
                        <!--
                            See Attachment 2 for the description of possible values:
                            input, textarea, password, checkbox, selectbox,
                            multiple select, multiple checkboxes,
                            countries list, states list,
                            file, info, header, template
                        -->
                        <default_value>radio_1</default_value>
                        <!--
                            The default value assigned to the setting.
                        -->
                        <variants>
                        <!--
                            The variants are available for the following setting types:
                            * selectbox, multiple select;
                            * multiple checkboxes, combo select
                        -->
                            <item id="radio_1"></item>
                            <!--
                                A variant item has the following attributes:
                                * id: An identifier used to address the variant.
                            -->
                        </variants>
                </items>
            </section>
</settings>

Functions for Working with Settings¶

The variants of values for settings can be changed and added via 2 types of functions: variants.functions and actions.functions:

• variants.functions generate the list of possible variants without recording those variants to the database. The variants of values for a setting are generated dynamically every time when someone opens the page with that setting.

  These functions must be in the variants.functions.post.php file in the [addon_name]/schemas/settings directory. The functions must be named as follows: fn_settings_variants_addons_[addon_name]_[setting_name]().

  Let’s assume that the my_changes add-on has a setting with example as its ID. To generate the variants of values for this setting, create the variants.functions.post.php file in my_changes/schemas/settings. This file must contain a function called fn_settings_variants_addons_my_changes_example().

• actions.functions are called when add-ons are installed and uninstalled. For example, these functions generate fields for the add-on’s settings in the database during add-on installation. They also remove those fields when the add-on is uninstalled.

  These functions must be located in the actions.functions.post.php file in the [addon_name]/schemas/settings. The functions must be named as follows: fn_settings_actions_addons_[addon_name]_[setting_name]().

  Let’s assume that the my_changes add-on has a setting with example as its ID. To create a function for this setting, create the actions.functions.post.php file in my_changes/schemas/settings. This file must contain a function called function fn_settings_actions_addons_my_changes_example().

Table settings_sections¶

The settings_sections table contains the list of sections to which the settings may belong. This table has the following fields:

• section_id—the identifier of the section.

• parent_id—the identifier of the parent section.

• edition_type—the information on when and where the section will be available; this field determines if the section will be available in CS-Cart/Multi-Vendor, and which level of access an administrator must have. This field may include one value or multiple values separated by commas (for example, ROOT,ULT:VENDOR).

• name—the name of the section.

• position—the position of the section relative to other sections.

• type—the type of the section:

  • CORE—a section of the core settings. All the sections of this type are listed on the Settings page in the Administration panel (see the settings.php controller).
  • ADDON—a section with the add-on settings. All sections of this type appear either in a pop-up window or on a separate page and include the settings of an add-on (see the addons.php controller).
  • TAB—a subsection of settings (a tab). Core and add-on settings can both have tabs. Each subsection has the ID of its parent section in the parent_id field.
  • SEPARATE_TAB—a subsection of settings (a tab). Core and add-on settings can both have tabs, but this tab is added as a separate container. Each subsection has the ID of its parent section in the parent_id field.

  Note

  Only sections with the CORE or ADDON type can have subsections.

Here is an example of the entry in the database—the Appearance section:

Here is how to learn the ID of the section in the Administration panel:

• Core settings: go to the Settings page and select a section. The name of the section will be displayed in the browser’s address bar as the section_id parameter in the URL.

  For example, the Appearance section will have Appearance as section_id. The URL will look like this: example.com/admin.php?dispatch=settings.manage&section_id=Appearance

• Add-on settings: go to Add-ons → Manage add-ons and click the gear button of an add-on. If you hover over the Uninstall action, a URL should appear at the bottom of the browser window. The URL will include the addon parameter with the name by which the add-on can be referred to in the code.

  For example, Customers also bought add-on will have customers_also_bought as a name. The URL will look like this (note that this example only includes a part of the URL): example.com/admin.php?dispatch=…&addon=customers_also_bought&…

Table settings_objects¶

The settings_objects table contains the list of core settings and add-on settings, and their values. This table has the following primary fields:

• object_id—the identifier of the setting.
• edition_type—the information on when and where the setting will be available; this field determines if the setting will be available in CS-Cart/Multi-Vendor, and which level of access an administrator must have.
• name—the name of the setting.
• section_id—the identifier of the section to which the setting belongs.
• section_tab_id—the identifier of the tab (if the setting is located in a tab).
• type—the type of the setting.
• value—the value of the setting.
• position—the position of the setting relative to other settings.

Here is an example of the entry in the database—company_name (Company name from Settings → Company):

To learn the identifier of the setting, view the code of the page with the setting. For example, let’s learn the identifier of the elements_per_page setting (Elements per page from Settings → Appearance).

To do this, go to Settings → Appearance, click the right mouse button on the setting and choose Inspect element. The identifier of the setting can be found in the square brackets [] in the name attribute.

Table settings_variants¶

The settings_variants table contains the list of variants (possible values) for the settings with the following types: selectbox, multiple select, and multiple checkboxes. Administrators choose one of the predetermined variants as the value of the setting.

For example, there is a setting called Orders in the Settings → Logging section. The information about which variants are chosen is stored in the log_type_orders setting (see the settings_objects table). The list of all possible variants for this setting is stored in settings_variants.

You can get the list of all the possible values of a setting by the object_id field. If the table doesn’t have any variants for the setting, it means that they are formed dynamically via the variants.functions.

Table settings_descriptions¶

The settings_descriptions table contains the names of sections, settings and variants, and the tooltips for different languages. Here are the primary fields of the table:

• object_id—the identifier of the setting.
• object_type—one of the following types:
  • V—the name of a variant of a setting value (see the settings_variants table).
  • O—the name of a setting (see the settings_objects table).
  • S—the name of a section (see the settings_sections table).
• lang_code—the language code.
• value—the name of a setting/section/value in the specified language.
• tooltip—the tooltip of a setting/section/value.

This table contains the information for all the languages that are currently installed. When searching the database for a specific value, you need to consider lang_code as well as object_id and object_type.