---
title: Adding custom website settings
related:
- https://docs.kentico.com/13/configuring-xperience/managing-sites/configuring-settings-for-sites.md
- https://docs.kentico.com/13/configuring-xperience/reference-web-config-application-keys.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
Xperience allows you to create your own [settings](https://docs.kentico.com/13/configuring-xperience/managing-sites/configuring-settings-for-sites.md) and use them to configure custom parts of the application. You can work with the values of custom settings in two ways:
- [Through the API in custom code](#loading-the-values-of-settings-in-code)
- [Inside macro expressions](#getting-setting-values-in-macro-expressions)
## Creating a custom module
Each setting in the system must belong under a module. You cannot create custom settings for the default modules included in Xperience. To add custom settings, first create a custom module:
1. Open the **Modules** application.
2. Click **New module**.
3. Type a display name for the module (for example _Custom settings_).
4. Click **Save**.
You do not need to create any classes, permissions or user interface for the module – you can use an empty module as a container for custom settings.
Alternatively, you can use the default **Custom** module (only recommended for ad-hoc, non-transferable settings).
## Defining custom settings
> **Info:** The system organizes settings according to the following hierarchy:
>
> - **Categories** – represent separate pages in the settings interface. You can create categories under other categories in a tree structure.
>
> - **Groups** – divide categories into sub-sections. Groups make it easier to navigate in categories that contain a large number of setting keys.
> - **Keys** – individual settings.
To create settings, open the **Modules** application, edit () one of your custom modules and select the **Settings** tab:
1. Click **New category** ().
2. Type a **Display** and **Code name** for the category.
- (Optional) You can set the category's icon image through the **Icon path** property. Enter the path to the image, either as a full relative path from the administration project root (e.g. _\~/App\_Themes/Default/Images/CMSModules/list.png_) or a short path beginning under the App\_Themes _Images_ folder (e.g. _CMSModules/list.png_).
3. Click **Save**.
4. On the **Settings** sub-tab of the category and click **New settings group**.
5. Type a **Display** and **Code name** for the group.
6. Click **Save**.
7. Return to the **Settings** tab of the category and click **New settings key** inside the group.
8. Fill in the properties of the settings key:
| General | |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Display name | Sets the caption displayed next to the key in the settings interface. |
| Code name | Serves as a unique identifier for the setting (for example [in the API](#loading-the-values-of-settings-in-code)). |
| Description | Sets a tooltip that the system displays in the settings interface when hovering over the key's caption or help icon. You can describe the purpose of the setting, allowed values, etc. |
| Explanation text | Adds text that the system displays directly below the setting in the settings interface (**Settings** application). |
| Key is only global | If checked, all sites in the system share the same value for the key. You can only see global keys when editing _(global)_ settings. |
| Key is hidden | If checked, the system does not display the key in the **Settings** application. You can use hidden settings to store the values of configuration options that you set through the API. |
| Value | |
| Type | Selects the data type of the setting key's value:
Boolean (Yes/No)
Integer number
Floating-point number
Text
Long text
The settings interface validates the entered value against the selected type. |
| Default value | The default value of the key. Administrators can reset settings to their default value by clicking **Reset these settings to default** in the settings editing interface. |
| Validation regex | Allows you to define custom validation rules for the setting's value through a [regular expression](http://en.wikipedia.org/wiki/Regular_expression). |
| Editing control | Specifies the interface element used for editing the key's value in the settings form.
**Default** – the setting key uses a basic textbox or checkbox (for _Boolean_ values) interface.
**Form control** – allows you to choose one of the [form controls](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls.md) registered in the system. You can configure the [parameters](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls/defining-form-control-parameters.md) of the selected form control in the _Editing control settings_ section.
**File system path** – directly specifies the path to a user control file in the administration project, for example: _\~/CMSFormControls/SimpleCountrySelector.ascx_ |
9. Click **Save**.
Administrators (and users with the _Configure settings_ [permission](https://docs.kentico.com/13/managing-users/configuring-permissions.md) for the _CMS_ module for non-global settings) can now [configure](https://docs.kentico.com/13/configuring-xperience/managing-sites/configuring-settings-for-sites.md) the value of the custom setting in the **Settings** application.
### Managing custom settings
To manage your custom settings, edit the parent module in the **Modules** application, and select the **Settings** tab. The settings hierarchy here defines the structure of the **Settings** application's interface.
> **Note:** **Restrictions**
>
> - You cannot modify the settings under the default modules in Xperience.
> - You can only work with the settings of the module that you are editing (settings of other modules are grayed out).
You can perform the following actions:
- Edit the properties of setting categories (names and icon path) on the **General** tab.
- Click **Edit** () to modify the properties of setting keys or groups.
- To move an item within the settings hierarchy, edit the item and select the target location through the **Parent category** or **Group** property.
- Click **Up** () or **Down** () to change the order of categories, groups or setting keys.
- Click **Delete category** () or **Delete** () to remove setting items.
## Loading the values of settings in code
To make settings affect the behavior of websites (or the entire application), you need to work with the setting values in your custom code. For example in your live site application, [event handlers](https://docs.kentico.com/13/custom-development/handling-global-events.md), modules or any other components. You can load values of both the default and custom settings.
To load the values of settings, use `ISettingsService` (we recommend using [dependency injection](https://docs.kentico.com/13/developing-websites/initializing-xperience-services-with-dependency-injection.md) to instantiate system service classes). The service exposes an indexer that you can use to access the values of individual setting keys. Settings are identified by the following formats:- **SettingKeyCodeName** – for global settings
- **SiteCodeName.SettingKeyCodeName** – for site-specific settings (to get the code name of the current site, use `ISiteService.CurrentSite.SiteName`)
```csharp title="Example"
using CMS.Core;
...
// Contains an instance of the settings service (e.g., obtained using dependency injection)
private readonly ISettingsService settingsService;
// Gets the value of the 'CMSHomePagePath' setting for the 'SiteCodeName' site
string value = settingsService["SiteCodeName.CMSHomePagePath"];
```
The service always returns `string` values. If you need to cast the setting value to a different type, use `IConversionService`.
```csharp title="Example"
using CMS.Core;
...
// Contains an instance of the conversion service (e.g., obtained using dependency injection)
private readonly IConversionService conversionService;
// Gets the maximum allowed number of events stored by the event log
int eventLogSize = conversionService.GetInteger(settingsService["SiteCodeName.CMSLogSize"], -1);
// Checks if Continuous Integration is enabled
bool continuousIntegrationEnabled = conversionService.GetBoolean(settingsService["CMSEnableCI"], false);
```
## Getting setting values in macro expressions
> **Note:** **Note**: Only users with the Global administrator [privilege level](https://docs.kentico.com/13/managing-users/user-management.md) can create macros that load the values of settings. The _Configure settings_ [permission](https://docs.kentico.com/13/managing-users/configuring-permissions.md) for the _CMS_ module is not sufficient for this purpose.
[Macro expressions](https://docs.kentico.com/13/macro-expressions.md) allow you to:
- Dynamically insert the values of settings into most fields in the Xperience administration interface
- Work with settings in macro conditions or other expressions with advanced logic
You can load values of both the default and custom settings.
Use the following expression to get setting values inside macros: _**Settings.**_
For example:
```text
{% Settings.CMSStoreFilesInFileSystem %}
```
The macro returns the setting's value for the currently running site (or the global value for global-only settings). If you need to access the global value of a setting, you can use the following macro expression: _GlobalObjects.SettingsKeys..KeyValue_