Kentico CMS 7.0 Developer's Guide

Managing form controls

Managing form controls

Previous topic Next topic Mail us feedback on this topic!  

Managing form controls

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

You can view the catalog of available form controls in Site Manager -> Development -> Form controls and register new ones as necessary. When edited, form controls have the following properties available on the General tab:


Display name - sets the name of the form control displayed in the administration interface, e.g. when selecting a control in the field editor.

Code name - sets the name of the control that is used as its unique identifier, for example in the API.

Type - allows the selection of a category under which the form control will be placed. The type can be used to filter form controls.

File name - contains the relative path to the .ascx file that implements the form control, for example: ~/CMSFormControls/Basic/TextBoxControl.ascx

Description - may be used to enter a text description of the control or comments for other administrators.

High priority - when selecting a form control in the field editor, controls with high priority are offered at the top of the list and highlighted using a colored background. This option should only be enabled for those controls that are most commonly used.




The properties under the Use control for section determine for which attribute types the form control should be available. Possible attribute types for fields include standard data types (Text, Long text, Decimal, Integer, Long integer, Boolean, Date-time), as well as the following special options:


Visibility - this attribute type is used for controls that modify the visibility options of other fields. Please see the Development -> Membership, permissions and security -> Custom field visibility chapter for more details.

Unique identifier (GUID) - attributes of this type are 32‑character strings used as globally unique identifiers for objects.

File - used for fields that provide file management.

Document attachments - this attribute type is used for fields that allow the management of document attachments.


The Show control in section is used to specify in which types of forms the control can be used i.e. where in the user interface it can be selected. The following options are available:


Document types - allows use in document type fields, which can be edited in Site Manager -> Development -> Document types. The actual form is displayed when editing a document on the Form tab in CMS Desk -> Content -> Edit.

Custom tables - allows the control in custom table fields, which can be edited in Site Manager -> Development -> Custom tables. The corresponding data editing form can be found in CMS Desk -> Tools -> Custom tables.

System tables - allows use in system table fields, which can be edited in Site Manager -> Development -> System tables. The editing forms of system objects are located in various sections of the administration interface or on the live site, depending on the specific object.

Reports - if checked, the control may be used to provide the interface for entering report parameters, which can be defined when editing a report in CMS Desk -> Tools -> Reporting. The reporting parameter form is displayed when a report is viewed in the interface or published on the live site.

Controls and web parts - allows the control to be used for the properties of web parts and widgets, as defined in Site Manager -> Development -> Web parts/Widgets. This editing form provides the configuration dialog of individual web parts or widget instances.

Forms - if checked, the control may be used to represent the fields of on-line forms, which can be edited in CMS Desk -> Tools -> Forms. The High priority flag of the form control also needs to be enabled if you wish to have it offered in the form field editor's simple mode. If you allow a form control for forms, you also need to enter the following default values that will be used if the field is edited in simple mode:

Default data type - the data type of the field that will be used by default when a user chooses to create a new field of this type.

Column size - only applies to the Text data type. This sets the maximum size of the database column used to store the field, which also limits the maximum number of characters that may be entered into the field.


The Properties tab is used to define parameters for the specific form control. Further information can be found in the Form control parameters topic.


Form control inheritance


When creating a new form control, it is possible to inherit from an existing control rather than starting from scratch. Inherited controls work the same way as their parent, but it is possible to change their general settings (i.e. set where they can be used) and assign different default values for their parameters. This allows you to create specialized controls based on general ones. Such controls can be particularly useful for users who work with the field editor in simple mode.


For example, imagine that you need to define a reusable drop-down list with a specific set of options. This is a typical scenario that can easily be achieved by creating an inherited form control. You could use the general Drop-down list form control as the parent and then simply set the required options through the default values of the parameters available on the Properties tab.




Inherited form controls use the same source file as their parent, so they do not have a File name property. Instead, you simply select the parent when creating the inherited control.