Form EngineMiro RemiasSolution architectKentico softwaremirekr@kentico.com

Agenda

• Introduction

• How does it work?

• Architecture (API, database)

• Customization options

• Code examples

Introduction

• Allows users to create forms and manage data (insert/update)

• Built-in and custom form controls

• Input validation

• Custom form layout (Alternative forms)

Where can you find examples of form engine?

• On-line forms (BizForm)• Forms for documents (CMSForm)• Forms for web-part properties (BasicForm)• Forms for system tables (DataForm) • Forms for custom tables (CustomTableForm)

How does it work?

Form

Form definition

Data

Field editor

Field editor - \CMSModules\AdminControls\Controls\Class\FieldEditor.ascx

Architecture – overview

Database tables:

CMS_ClassClassFormDefinition – form definition (Example 1)ClassTableName – table where data is stored ClassIsCustomTable, ClassShowAsSystemTable – custom table/system table flagClassFormLayout – form layout…

CMS_AlternativeFormFormDefinitionFormLayout

CMS_FormCMS_FormUserControl

API support (http://devnet.kentico.com/downloads/kenticocms_api.zip):

CMS.FormControls: BasicForm, BizForm, CMSForm, CustomTableForm, DataForm, FormEngineUserControl, EditingFormControl …

CMS.FormEngine: FormInfo, FormFieldInfo, AlternativeFormInfo, AlternativeFormInfoProvider, BizFormInfo, BizFormInfoProvider …

Architecture - BasicForm

• Renders form from it’s definition• Creates form layout with labels, fields, error labels, categories, …• Manages field initialization, validation and gathers entered data

Field label

Field category

Form error label

Field error label

Form control

Submit button (image)

BizFormCMSFormDataFormCustomTableForm

BasicForm

Architecture - BasicForm (2)BasicForm (API) (Example 2)Properties:

Mode (FormModeEnum - Insert, Update, InsertNewCultureVersion)FormInformation (FormInfo)FormLayout (string)FormXML (string)DataRow (DataRow)FieldLabels (Hashtable)FieldControls (Hashtable)FieldEditingControls (Hashtable)FieldErrorLabels (Hashtable)SiteName (string)SubmitButton (Button)SubmitImageButton (ImageButton)UseColonBehindLabel (bool)EditedObject (object)

TreeNode (CMSForm)IDataClass (BizForm and CustomTableForm)

AbstractInfo or DataClassInfo (DataForm)ParentObject (object) - insert mode, TreeNodeAllowMacroEditing (bool)DefaultFormLayout (FormLayoutEnum)RenderCategoryList (bool)MarkRequiredFields (bool)

Methods:LoadData(void: DataRow)

LoadFormLayout(void: formLayout, FormInfo)LoadDefaultLayout(void: FormInfo )

CreateEditingFormControl(Control: FormFieldInfo)SaveData(void: redirectUrlAfterSave)

ValidateData(bool)

Architecture - Form layout

Supported macro types in form layout:

$$label:<FieldName>$$

$$input:<FieldName>$$

$$validation:<FieldName>$$

$$visibility: <FieldName>$$

$$submitbutton$$

Architecture - Form controls

• Allow you to use custom field types in editing forms (http://devnet.kentico.com/docs/devguide/developing_form_controls.htm)

• Register in Site Manager -> Development -> Form controls

FormFieldInfo (API)Name (column)Caption (fieldcaption)Visible (visible)Enabled (enabled)AllowEmpty (allowempty)PrimaryKey (isPK)…DataType (columntype) -FormFieldDataTypeEnum (Text, LongText, Integer, Decimal, DateTime, Boolean, File, GUID ... )FieldType (fieldtype) - FormFieldControlTypeEnum (LabelControl, TextBoxControl, DropDownListControl, RadioButtonsControl, MultipleChoiceControl, ...)

ClassFormDefinition (CMS_Class table):<form>

<field column="ContactUsID" fieldcaption="ContactUsID" visible="false" columntype="integer" fieldtype="label" allowempty="false" isPK="true" system="true" publicfield="false" spellcheck="true" guid="ba75b40f-edf6-434f-aa19-15ea8413e407" visibility="none" ismacro="false" />...<field column="Email" fieldcaption="E-mail" visible="true" columntype="text" fieldtype="usercontrol" allowempty="false" isPK="false" system="false" columnsize="100" publicfield="true" spellcheck="true" guid="877dc000-111b-4379-938c-6386557719aa">

<settings><controlname>emailinput</controlname>

</settings></field>

</form>

Architecture - Form controls (2)FormEngineUserControl (API) (Example 3) Properties:

Form (BasicForm)FieldInfo (FormFieldInfo)FormControlParameter (object)Value (object)Enabled (bool)DataDR (DataRow)

Methods:IsValid (bool)GetOtherValues (object[,] AttributeName/Value)

Working with other fields from form control: TextBox txtBox = (TextBox) Form.FieldControls["productprice"];

EditingFormControl (API)Properties:Enabled (bool)Value (object)DataRow (DataRow)IsMacro (bool)DataRowValue (object)

Methods:IsValid (bool)GetOtherValues (object[,] AttributeName/Value)CreateControl(Control : FormFieldInfo)

EditingFormControl txtBox = (EditingFormControl) Form.FieldEditingControls["productprice"];

Architecture – CMSForm

• Creation and editing of documents• Adds ‘Publish from/to’ and ‘Document name’ fields (optional)• Handles content tree hierarchy for blogs (insert mode)• Uploaded files stored in DB and/or file system as an attachments

CMSForm (API) (Example 4)Properties:

BasicForm (BasicForm)NodeId (int)FormName (string) - cms.news.defaultAlternativeFormFullName (string) – cms.user.editformFormMode (FormModeEnum - Insert, Update, InsertNewCultureVersion)SiteName (string)CultureCode (string)

Methods:LoadForm(void)Save (TreeNode)

SaveDataToDB(void)

Architecture – CMSForm (2)

Page CMSForm BasicForm EditingFormControl TextBoxControlOnInitOnLoadOnPreRender

CreateChildControlsLoadForm[Controls.Add(BasicForm)]

OnLoad (EnsureChildControls)CreateChildControlsLoadData Addition of one EFC

[Controls.Add(EFC)] EnsureControls (EnsureChildControls) CreateChildControls {SetValue} [Controls.Add(FC)] OnInit

OnLoadPage_Load

OnPreRenderOnPreRender

OnPreRenderOnPreRender

CMSForm life cycle - first load:

Architecture – CMSForm (3)

CMSForm life cycle - postback:

Page CMSForm BasicForm EditingFormControl TextBoxControlOnInit

CreateChildControlsLoadForm[Controls.Add(BasicForm)]

CreateChildControlsLoadData Addition of one EFC[Controls.Add(EFC)] EnsureControls (EnsureChildControls) CreateChildControls {SetValue} [Controls.Add(FC)] OnInit

OnLoadOnLoad

OnLoadPage_Load

btnSave_ClickValidateData

{GetValue}IsValid

SaveSaveData

{GetValue}SaveDataToDB

OnPreRenderOnPreRender

OnPreRenderOnPreRender

OnPreRender

Architecture – BizForm

• Used for online form creation (most frequently used module)• Data stored in separate DB table (also CMS_Form)• Uploaded files stored in file system (exclusively)• Data managed through the UI, could be sent via e-mail (notification and auto-responder) or exported to MS Excel file (http://devnet.kentico.com/docs/devguide/bizforms_module_overview.htm)

BizForm(API) (example)Properties:

BasicForm (BasicForm)FormMode (FormModeEnum - Insert, Update)FormName (string) - bizfrom.contactus.defaultItemID (int)AlternativeFormFullName (string) – bizfrom.contactus.layout1SiteName (string)UseColonBehindLabel (bool)EnableNotificationEmail (bool)EnableAutoresponder (bool)

Methods:LoadForm(void)SaveDataToDB(void)

SendNotificationEmail (void)SendConfirmationEmail (void)

Architecture – DataForm and CustomTableForm

• common form controls to edit data from system/custom tables(http://devnet.kentico.com/docs/devguide/custom_tables_module_overview.htm)

• uploaded files stored in file system

DataForm / CustomTableForm (API) (Example 5)Properties:

BasicForm (BasicForm)ClassName (string)ItemID (int) CustomTableId (int)Info (AbstractInfo) - usable instead of ClassName and ItemIDAlternativeFormFullName (string) – cms.user.editformFormMode (FormModeEnum - Insert, Update)SiteName (string)

Methods:ReloadData (void)

LoadForm(void)Save (bool) + OnAferSave handler

SaveDataToDB(void)

Customization options

• Control event handlers ():OnBefore(After)DataLoad, OnBefore(After)Validate, OnBefore(After)Save, OnValidationFailed, OnItemValidation, OnUploadFile, OnDeleteFile, …

• Global data handlers (http://devnet.kentico.com/docs/devguide/data_handler.htm):

OnBefore(After)Update, OnBefore(After)Insert, OnBefore(After)Delete, OnGetContent

• Custom Field (Form) controls

Questions

?FAQ – http://devnet.kentico.com/FAQs.aspxKB - http://devnet.kentico.com/Knowledge-Base.aspxDocumentation - http://devnet.kentico.com/Documentation.aspxTechnical support - http://www.kentico.com/Support.aspx (support@kentico.com)

Thank you!Miro Remias

mirekr@kentico.comSolution architectKentico software