Kentico CMS 7.0 Developer's Guide

Form control parameters

Form control parameters

Previous topic Next topic Mail us feedback on this topic!  

Form control parameters

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

It is possible to define parameters for form controls that can be used to further specify the behavior or appearance of the generated form fields. Parameters can greatly increase the flexibility of a form control, since they provide additional configuration options for individual fields that use the control. This allows you to reuse the same control without having to develop a new one for every small difference in functionality or design.

 

To access the parameters of a form control, edit (Edit) the given control in Site Manager -> Development -> Form controls and switch to the Properties tab. Here, you can manage the fields that represent individual parameters.

 

devguide_clip0117

 

As you may have noticed, the parameters themselves are created through a field editor and the form used to edit their values is based on the standard form engine. The editing interface for every parameter is provided by a selected form control, which means you can create completely custom parameters according to your own requirements.

 

The defined parameters are then displayed when the given form control is selected in the field editor of an object. You can view and configure them under the Editing control settings section of the given field.

 

devguide_clip0128

 

There are two possible modes for this group of settings: Advanced and Simplified. You can switch between them using the corresponding link in the given section of the field editor. Simplified mode only offers the parameters that have the Display in simple mode option enabled (on the Properties tab of the given form control under the Field advanced settings section).

 

The parameter values entered here will be applied to the given field.

 

 

InfoBox_Exclamation

 

Warning!

 

Removing or modifying the parameters of the built-in form controls may cause the system to behave incorrectly in some cases, since the controls are used in various parts of the Kentico CMS interface.

 

We recommend implementing a new form control or inheriting from an existing example if you wish to create a custom field.

 

Parameters of inherited form controls

 

When editing an inherited form control on the Properties tab, the parameters are automatically loaded from the parent control. The configuration of the parameters cannot be modified, it is only possible to change their default values. This allows you to create specialized form controls that may easily be used in the field editor without any configuration of their Editing control settings.

 

To modify the default value of a parameter, uncheck the Inherited box next to it and then make the necessary changes. Otherwise, the default value set for the given property in the parent control will be used.

 

devguide_clip0864

 

An inherited form control may only override the default value for parameters that have the Display attribute in the editing form option enabled in the definition of the parent control.

 

Handling parameters in the code of custom form controls

 

In order to be reflected by the field in the resulting form, each parameter must be processed in the code of the form control. The following methods can be used to access the value of a parameter:

 

GetValue("<ParameterName>")

SetValue("<ParameterName>", Object value)

 

Replace the <ParameterName> expression with the Column name of the parameter that you wish to get or set. These two methods are inherited from the FormEngineUserControl class, so they are available for every form control. For easy storage and usability, it is recommended to define a separate property for every parameter (as a member of the control's class). Once you have the value of the parameter, you can implement code that modifies the control accordingly.

 

For more details, please see the example in the Developing form controls topic, which demonstrates how a parameter can be added to a form control and handled in the code.