Form controls provide the interface for the various editing forms that allow users to input data into Kentico CMS, both in the administration interface and on the live site. Each control represents a single field by displaying a certain form element, like a text box or area for user input, a group of radio buttons, an object selector etc.

 

 

The controls can be placed into all editing forms that are based on the Kentico CMS form engine, which includes the following:
 

•Document type editing forms (Form tab)

•Web part and Widget properties

•Editing forms of System table objects

•Editing forms of Custom tables

•Forms

•Alternative forms for the objects mentioned above

•Report parameters

 

From a website development point of view, form controls are implemented by standard user controls (.ascx files) that inherit from the CMS.FormControls.FormEngineUserControl class.

 

Even though the built-in set of controls covers most standard types of form functionality, it is also possible to customize existing controls or create completely new ones to match any specific requirements. Please refer to the Developing form controls topic for additional information and an example of how to create a custom form control, register it in the system and insert it into a form.

 

Managing form controls

 

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 used in the interface, e.g. when selecting a control in a field editor.

•Code name - sets the name of the control that is used as its unique identifier in code.

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

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

 

 

The properties under the Use control for section are used to set 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:

 

•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 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 fields of forms, which can be edited in CMS Desk -> Tools -> Forms. 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 amount 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.