--- title: Configuring editing component state in builder configuration dialogs --- > 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). When [defining editable properties](https://docs.kentico.com/13/developing-websites/form-builder-development/assigning-editing-components-to-properties.md) for page or form builder components ([widgets](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-widgets/defining-widget-properties.md), [page templates](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-templates/defining-page-template-properties.md), [personalization conditions](https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/content-personalization/developing-personalization-condition-types.md), [form field validation rules](https://docs.kentico.com/13/developing-websites/form-builder-development/defining-field-validation-rules.md), etc.), you can use the API to configure the state of the assigned editing component. A typical use case is creating dynamic data sources for selector components such as [DropDownComponent](https://docs.kentico.com/13/developing-websites/form-builder-development/reference-system-form-components.md) or [RadioButtonsComponent](https://docs.kentico.com/13/developing-websites/form-builder-development/reference-system-form-components.md) (demonstrated in the examples on this page). This configuration is complementary to setting the component's properties, visibility conditions, and validation rules via the corresponding attribute notation, and is intendedfor cases where statically configuring component values via attributes is not sufficient. Component state is configured via **FormComponentConfigurator** classes that can run custom code at specific points in an editing component's lifecycle. Configurators allow you to modify all aspects of the component: properties, assigned visibility conditions, validation rules, and default value. Configurator classes must: 1. Inherit from the \*\*FormComponentConfigurator \*\*base class. 2. Target a specific form component type via the generic **TFormComponent** parameter of the **FormComponentConfigurator** base class. For implementing types of out-of-the-box components, see [Reference - System form components](https://docs.kentico.com/13/developing-websites/form-builder-development/reference-system-form-components.md). 3. Implement the **Configure(FormComponent, IFormFieldValueProvider)** method. The _FormComponent_ parameter contains the instance of the configured component, giving you access to all its properties. _IFormFieldValueProvider_ allows you to access the values of properties in the given dialog that **precede** the component being configured (according to the _Order_ property that can be set when [assigning editing components](https://docs.kentico.com/13/developing-websites/form-builder-development/assigning-editing-components-to-properties.md)). - The **Configure** method can be omitted in case you are implementing a configurator that is only used to dynamically set values of fields. See [Setting values of fields dynamically](#configuringeditingcomponentstateinbuilderconfigurationdialogs-setvalues). Assign configurators via the **EditingComponentConfiguration** attribute. The attribute has two constructors: - _EditingComponentConfiguration(configuratorType)_ – used to assign a configurator that does not have any dependencies on the values of other components in the dialog. This configurator is invoked during the initial load of the configuration dialog. See [Setting the initial component state](#configuringeditingcomponentstateinbuilderconfigurationdialogs-initial). - _EditingComponentConfiguration(configuratorType, fieldDependency)_ – used to assign a configurator with a dependency on the values of other components in the dialog. This configurator is invoked during the initial load of the configuration dialog and every time the value of the field designated as the dependency changes. See [Establishing dependencies between fields](#configuringeditingcomponentstateinbuilderconfigurationdialogs-dependency). > **Info:** **Note:** You can assign at most one component configurator per editing component. ## Setting the initial component state Configurators assigned via **EditingComponentConfiguration(configuratorType)** are invoked only on the initial load of the configuration dialog. To assign a configurator to a property: 1. Edit the class containing the component's properties (e.g., a [widget properties model class](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-widgets/defining-widget-properties.md)). 2. Identify the property that you want to configure. 3. Decorate the property with the **EditingComponentConfiguration** attribute (_Kentico.Forms.Web.Mvc_ namespace). 4. Set the following parameters: - **configuratorType** – the class that implements the component configurator you want to use. Use the _typeof_ operator. The example below shows a sample implementation of a component configurator and its usage. ### Example The following example creates a _CountryConfigurator_ for [DropDownComponent](https://docs.kentico.com/13/developing-websites/form-builder-development/reference-system-form-components.md) that serves as a data source for its options: ```csharp title="Example - country configurator" using System; using System.Linq; using CMS.Globalization; using Kentico.Forms.Web.Mvc;   // When assigned to a property with 'DropDownComponent' editing component, populates the component's options with all countries stored in the database public class CountryConfigurator : FormComponentConfigurator { private readonly ICountryInfoProvider countryProvider; // Obtains required dependencies using constructor injection public CountryConfigurator(ICountryInfoProvider countryProvider) { this.countryProvider = countryProvider; } public override void Configure(DropDownComponent formComponent, IFormFieldValueProvider formFieldValueProvider) { // Retrieves all countries from the database and transforms them to the drop-down data format var countries = countryProvider.Get() .GetEnumerableTypedResult() .Select(c => c.CountryID + ";" + c.CountryDisplayName); // Sets the initial data of the component to the retrieved countries formComponent.Properties.DataSource = String.Join("\r\n", countries); } } ``` The following code assigns the configurator to a _DropDownComponent_ in a widget configuration dialog. ```csharp title="Example - country configurator usage" using Kentico.Forms.Web.Mvc; using Kentico.PageBuilder.Web.Mvc; public class MyWidgetProperties : IWidgetProperties { [EditingComponent(DropDownComponent.IDENTIFIER, Label = "Country", Order = 3, Tooltip = "Select your country")] [EditingComponentConfiguration(typeof(CountryConfigurator))] public string Country { get; set; } ... } ``` When the widget properties dialog is opened, the configurator ensures all countries are loaded and selectable from the **Country** property. In this example, **CountryConfigurator.Configure** is only triggered on the initial load of the dialog (the configurator does not have a field dependency assigned). ## Establishing dependencies between fields within configuration dialogs Form component configurators can be used to establish dependencies between fields within a dialog. A typical use case is a selector component that changes its available selection options based on the value of another field. For fields with dependencies, the configurator is called during the initial load of the configuration dialog, and every time the value of the field marked as a dependency changes. > **Note:** **Property order requirement** > > Value dependencies between properties are restricted by the order in which the properties are displayed in the configuration dialog. A dependency can only be established with properties of a lower order (controlled by the **Order** property that can be set when [assigning editing components](https://docs.kentico.com/13/developing-websites/form-builder-development/assigning-editing-components-to-properties.md)). To assign a configurator with field value dependencies to a property: 1. Edit the class containing the component's properties (e.g., a [widget properties model class](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-widgets/defining-widget-properties.md)). 2. Identify the property that you want to configure. 3. Decorate the property with the **EditingComponentConfiguration** attribute (_Kentico.Forms.Web.Mvc_ namespace). 4. Set the following parameters: 1. **configuratorType** – the class that implements the component configurator you want to use. Use the _typeof_ operator. 2. **dependencyFieldName** – the name of the property whose change in value causes the configurator to reconfigure the component (call the **Configure** method again). Use the _nameof_ operator. The example below shows a sample implementation of a component configurator and its usage. ### Example The following example builds on the [country selector example](#configuringeditingcomponentstateinbuilderconfigurationdialogs-countryexample). It shows how to create a state selector that displays a collection of states for the selected country. The configurator takes the country selector as a dependency. Every time a user selects a different country, it fetches the corresponding states from the database. If the selected country is not subdivided into states, the configurator hides the field instead. ```csharp title="Example - state configurator" using System; using System.Linq; using CMS.Globalization; using Kentico.Forms.Web.Mvc; // Configurator for components of the 'DropDownComponent' type that populates the dropdown with // a selection of all states based on the country selected in another field public class StateConfigurator : FormComponentConfigurator { private readonly IStateInfoProvider stateInfoProvider; // Obtains required dependencies using constructor injection public StateConfigurator(IStateInfoProvider stateInfoProvider) { this.stateInfoProvider = stateInfoProvider; } public override void Configure(DropDownComponent formComponent, IFormFieldValueProvider formFieldValueProvider) { // Gets the identifier of the country selected in the field marked as a dependency var countryId = GetCountryId(formFieldValueProvider); // If no country is selected (typically on initial page load), hides the state selector if (!countryId.HasValue) { HideField(formComponent); return; } // Gets all states for a given country var states = stateInfoProvider.Get().WhereEquals("CountryID", countryId).GetEnumerableTypedResult().Select(s => s.StateID + ";" + s.StateDisplayName); if (!states.Any()) { // Hides the state selector component if subdivision into states doesn't exist for the selected country HideField(formComponent); } else { // Populates the state selector with states that belong to the selected country formComponent.Properties.DataSource = String.Join("\r\n", states); } } private int? GetCountryId(IFormFieldValueProvider formFieldValueProvider) { // The DependencyFieldName property of the base class contains the name // of the property set by the EditingComponentConfiguration attribute       if (formFieldValueProvider.TryGet(DependencyFieldName, out var country)) { if (!String.IsNullOrEmpty(country)) { // The format of individual options in the dropdown is: ; // Ensured in the Country selector example return Int32.Parse(country.Split(";")[0]); } } return null; } private void HideField(DropDownComponent formComponent) { formComponent.Properties.VisibilityConditionConfiguration = new VisibilityConditionConfiguration { VisibilityCondition = new NeverVisibleVisibilityCondition() }; } } ``` The following code assigns the configurator to a DropDownComponent with a dependency on the value of another property: ```csharp title="Example - country and state selector usage" using Kentico.Forms.Web.Mvc; using Kentico.PageBuilder.Web.Mvc; public class MyWidgetProperties : IWidgetProperties { [EditingComponent(DropDownComponent.IDENTIFIER, Label = "Country", Order = 3, Tooltip = "Select a country")] [EditingComponentConfiguration(typeof(CountryConfigurator))] public string Country { get; set; } [EditingComponent(DropDownComponent.IDENTIFIER, Label = "State", Order = 4)] // Assigns 'StateConfigurator' to the field and sets 'Country' as a dependency [EditingComponentConfiguration(typeof(StateConfigurator), nameof(Country))] public string State { get; set; } } ``` When the widget properties dialog is opened, the configurator ensures that the state field only shows when selecting a state for the country chosen via the **Country** property makes sense and populates the dropdown with relevant choices. In this example, **CountryConfigurator.Configure** is called on the initial load of the dialog and every time a country is selected using the **Country** dropdown. ### Setting values of fields dynamically > **Note:** **Note**: The _ConfigureValue_ method described below is only available after applying [hotfix 13.0.113](https://devnet.kentico.com/download/hotfixes) or newer. **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. You can use configurators to dynamically set the value of a field based on another field. Override the **ConfigureValue(IFormFieldValueProvider, string)** method of the **FormComponentConfigurator** base class. The _ConfigureValue_ method is called later in the editing component's lifecycle after the values of properties are set by the system. The method provides the following parameters: - The _IFormFieldValueProvider_ parameter allows you to access the values of properties in the given dialog that **precede** the component being configured (according to the _Order_ property that can be set when [assigning editing components](https://docs.kentico.com/13/developing-websites/form-builder-development/assigning-editing-components-to-properties.md) ). - The _string_ parameter contains the name of the changed field that triggered the configurator. If the field is updated for a reason other than a changed dependency field (e.g., initial rendering of the field), the value of this parameter is _null_. Return the updated value of the property or, if you do not want to perform any changes, return the _ConfigureValue_ method of the base class. The following code block is an example that shows how to update the value of a dependent property based on updates to the value of another property: ```csharp title="Example - country code configurator" using System; using System.Linq; using CMS.Globalization; using Kentico.Forms.Web.Mvc; public class CountryCodeConfigurator : FormComponentConfigurator { private readonly ICountryInfoProvider countryProvider; // Obtains required dependencies using constructor injection public CountryCodeConfigurator(ICountryInfoProvider countryProvider) { this.countryProvider = countryProvider; } public override object ConfigureValue(IFormFieldValueProvider formFieldValueProvider, string changedFieldName) { // The DependencyFieldName property of the base class contains the name // of the property set by the EditingComponentConfiguration attribute if (changedFieldName == DependencyFieldName && formFieldValueProvider.TryGet(DependencyFieldName, out var originalValue)) { // Returns the code of the country selected in the Country field            var countryCode = countryProvider.Get(Int32.Parse(originalValue)).CountryThreeLetterCode; return countryCode; } // Keeps the existing property value return base.ConfigureValue(formFieldValueProvider, changedFieldName); } } ``` The following code assigns the configurator to a TextInputComponent with a dependency on the value of another property: ```csharp title="Example - country, state and address selector usage" using Kentico.Forms.Web.Mvc; using Kentico.PageBuilder.Web.Mvc; public class MyWidgetProperties : IWidgetProperties { [EditingComponent(DropDownComponent.IDENTIFIER, Label = "Country", Order = 3, Tooltip = "Select a country")] [EditingComponentConfiguration(typeof(CountryConfigurator))] public string Country { get; set; } [EditingComponent(DropDownComponent.IDENTIFIER, Label = "State", Order = 4)] [EditingComponentConfiguration(typeof(StateConfigurator), nameof(Country))] public string State { get; set; }        [EditingComponent(TextInputComponent.IDENTIFIER, Label = "Country code", Order = 4, Tooltip = "Enter country code")] // Assigns 'CountryCodeConfigurator' to the field and sets 'Country' as a dependency [EditingComponentConfiguration(typeof(CountryCodeConfigurator), nameof(Country))] public string CountryCode { get; set; } } ``` When the widget properties dialog is opened, and the **Country** property is updated, the configurator automatically sets the value of the **CountryCode** property to the three-letter code of the country selected in the **Country** property. **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. You can use configurators to dynamically set the value of a field based on another field. Override the **ConfigureValue(IFormFieldValueProvider)** method of the **FormComponentConfigurator** base class. The _ConfigureValue_ method is called later in the editing component's lifecycle after the values of properties are set by the system. The method provides the _IFormFieldValueProvider_ parameter that allows you to access the values of properties in the given dialog that **precede** the component being configured (according to the _Order_ property that can be set when [assigning editing components](https://docs.kentico.com/13/developing-websites/form-builder-development/assigning-editing-components-to-properties.md) ). Return the updated value of the property or, if you do not want to perform any changes, return the _ConfigureValue_ method of the base class. The following code block is an example that shows how to update the value of a dependent property based on updates to the value of another property: ```csharp title="Example - country code configurator" using System; using System.Linq; using CMS.Globalization; using Kentico.Forms.Web.Mvc; public class CountryCodeConfigurator : FormComponentConfigurator { private readonly ICountryInfoProvider countryProvider; // Obtains required dependencies using constructor injection public CountryCodeConfigurator(ICountryInfoProvider countryProvider) { this.countryProvider = countryProvider; } public override object ConfigureValue(IFormFieldValueProvider formFieldValueProvider) { // The DependencyFieldName property of the base class contains the name // of the property set by the EditingComponentConfiguration attribute         if (formFieldValueProvider.TryGet(DependencyFieldName, out var originalValue)) { // Returns the code of the country selected in the Country field var countryCode = countryProvider.Get(Int32.Parse(originalValue)).CountryThreeLetterCode; return countryCode; } // Keeps the existing property value return base.ConfigureValue(formFieldValueProvider); } } ``` The following code assigns the configurator to a TextInputComponent with a dependency on the value of another property: ```csharp title="Example - country, state and address selector usage" using Kentico.Forms.Web.Mvc; using Kentico.PageBuilder.Web.Mvc; public class MyWidgetProperties : IWidgetProperties { [EditingComponent(DropDownComponent.IDENTIFIER, Label = "Country", Order = 3, Tooltip = "Select a country")] [EditingComponentConfiguration(typeof(CountryConfigurator))] public string Country { get; set; } [EditingComponent(DropDownComponent.IDENTIFIER, Label = "State", Order = 4)] [EditingComponentConfiguration(typeof(StateConfigurator), nameof(Country))] public string State { get; set; }        [EditingComponent(TextInputComponent.IDENTIFIER, Label = "Country code", Order = 4, Tooltip = "Enter country code")] // Assigns 'CountryCodeConfigurator' to the field and sets 'Country' as a dependency [EditingComponentConfiguration(typeof(CountryCodeConfigurator), nameof(Country))] public string CountryCode { get; set; } } ``` When the widget properties dialog is opened, and the **Country** property is updated, the configurator automatically sets the value of the **CountryCode** property to the three-letter code of the country selected in the **Country** property.