Form Engine Miro Remias Solution architect Kentico software mirekr@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? Field editor Form Form definition Data Field editor - \CMSModules\AdminControls\Controls\Class\FieldEditor.ascx Architecture – overview Database tables: CMS_Class ClassFormDefinition – form definition (Example 1) ClassTableName – table where data is stored ClassIsCustomTable, ClassShowAsSystemTable – custom table/system table flag ClassFormLayout – form layout … CMS_AlternativeForm FormDefinition FormLayout CMS_Form CMS_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 Form error label Field category Field label Field error label Form control BizForm CMSForm DataForm CustomTableForm Submit button (image) 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, TreeNode AllowMacroEditing (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-aa1915ea8413e407" 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="877dc000111b-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.default AlternativeFormFullName (string) – cms.user.editform FormMode (FormModeEnum - Insert, Update, InsertNewCultureVersion) SiteName (string) CultureCode (string) Methods: LoadForm(void) Save (TreeNode) SaveDataToDB(void) Architecture – CMSForm (2) CMSForm life cycle - first load: Page OnInit OnLoad OnPreRender CMSForm BasicForm EditingFormControl TextBoxControl CreateChildControls LoadForm [Controls.Add(BasicForm)] OnLoad (EnsureChildControls) CreateChildControls LoadData [Controls.Add(EFC)] Addition of one EFC EnsureControls (EnsureChildControls) CreateChildControls {SetValue} [Controls.Add(FC)] OnInit OnLoad Page_Load OnPreRender OnPreRender OnPreRender OnPreRender Architecture – CMSForm (3) CMSForm life cycle - postback: Page OnInit CMSForm BasicForm EditingFormControl TextBoxControl CreateChildControls LoadForm [Controls.Add(BasicForm)] CreateChildControls LoadData [Controls.Add(EFC)] Addition of one EFC EnsureControls (EnsureChildControls) CreateChildControls {SetValue} [Controls.Add(FC)] OnInit OnLoad OnLoad OnLoad Page_Load btnSave_Click ValidateData {GetValue} IsValid Save SaveData {GetValue} SaveDataToDB OnPreRender OnPreRender OnPreRender OnPreRender 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 autoresponder) 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.default ItemID (int) AlternativeFormFullName (string) – bizfrom.contactus.layout1 SiteName (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 ItemID AlternativeFormFullName (string) – cms.user.editform FormMode (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.aspx KB - http://devnet.kentico.com/Knowledge-Base.aspx Documentation - http://devnet.kentico.com/Documentation.aspx Technical support - http://www.kentico.com/Support.aspx (support@kentico.com) Thank you! Miro Remias mirekr@kentico.com Solution architect Kentico software