Form Engine

1. Form Engine Miro Remias Solution architect Kentico software mirekr@kentico.com

2. Agenda • Introduction • How does it work? • Architecture (API, database) • Customization options • Code examples

3. 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)

4. How does it work? Field editor Form Form definition Data Field editor - \CMSModules\AdminControls\Controls\Class\FieldEditor.ascx

5. 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 …

6. 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 BizForm CMSForm DataForm CustomTableForm Form control Submit button (image) BasicForm

7. 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)

8. Architecture - Form layout • Supported macro types in form layout: • $$label:<FieldName>$$ • $$input:<FieldName>$$ • $$validation:<FieldName>$$ • $$visibility: <FieldName>$$ • $$submitbutton$$

9. 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_Classtable): • <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>

10. 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: • TextBoxtxtBox = (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) • EditingFormControltxtBox = (EditingFormControl) Form.FieldEditingControls["productprice"];

11. 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)

12. Architecture – CMSForm (2) • CMSForm life cycle - first load:

13. Architecture – CMSForm (3) • CMSForm life cycle - postback:

14. 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.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)

15. 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)

16. 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

17. 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)

18. Thank you! Miro Remias mirekr@kentico.com Solution architect Kentico software