Ever wondered why we have form families, or how iCM turns the fields you add to your form into content displayed on your site?
Why Do We Have a Forms Package?
Let's face it, you could spend your time manually coding bespoke forms that use all of your favourite JavaScript libraries and custom CSS - but who's got time for that?
The iCM Forms Designer (and all of the associated bits and pieces) is right there in iCM. Everyone has it. Just enable the correct user privileges and you can start publishing forms that will "just work" and be fully integrated with the rest of your iCM site.
Forms comes in all shapes and sizes. Single page, multi page, branching, looping, chained together by workflow models, sharing type definitions, giving different views of the same data, published on your site, published in iCM, used as part of the iCM interface, containing custom JavaScript, using the API Server, making AJAX requests, communicating with End Points, saving data - all possible using a drag and drop interface and a little JavaScript knowledge.
Forms Architecture
Every form you create is built using a Form Family. The current family, developed and maintained by us at GOSS is called DEFAULTV2 (V1 was just called DEFAULT and we couldn't think of a better name).
The Form Family defines all of the HTML generated when a published form is rendered on your site.
The Form Family Definition includes Skeletons, which provide the template for the generated HTML, and Properties, which contain the values entered in the Forms Designer.
When a form is published the relevant parts of the family are combined with the form definition to create a single, self contained, set of instructions that the skeleton processor will use to render the form.
Form Skeletons
Every part of a form that appears on your web page comes from a Skeleton. A Form Family contains numerous named skeletons at the form, page and field type levels.
A skeleton is a file that, when processed, creates an output stream. It can contain snippets of JavaScript that can add to the output steam.
The JavaScript snippets are delimited by <%= and %> or <% and %>.
The first adds the return value of the enclosed JavaScript to the output stream. The second simply executes the enclosed JavaScript.
JavaScript variables exist within the scope of a single skeleton.
Context variables can be used within the scope of a whole form.
Skeleton Examples
A skeleton containing:
<p>Hello World</p>
Outputs:
<p>Hello World</p>
Using the tags above, our skeleton can execute JavaScript expressions:
<p>Hello <%myName%></p>
And should the variable myName contain "Tim", the skeleton would generate:
<p>Hello Tim</p>
Skeletons can also include blocks of JavaScript code. This lets you use loops and make decisions.
For example:
<% if (myTitle === "") { %>
<p>Hello <%=myName%></p>
<% } else { %>
<p>Hello <%=myTitle%> <%=myName %></p>
<% } %>
Should myTitle be empty, we'd get:
<p>Hello Tim</p>
If myTitle contained "Mr" and myName "Gulliver":
<p>Hello Mr Gulliver</p>
Form Properties
A property is a named value that is passed into the skeleton processor. You can access them within a skeleton using the Props variable.
Properties can have a type (string, number, boolean etc) but can also contain JSON data.
Properties exist for the whole form, each page and each field.
Field Types
Each field type generates a single element on your form. Every one is an (almost) self-contained set of skeletons and properties. A field type can generate a property within the form object type definition which allows it to store a value.
Field type properties correspond to the properties and values available in the forms designer.
The Form Families
A form family is a collection of skeletons and properties. It is divided into form, page and field sections. You can find your form families in the Definitions section of iCM Management.
You can't directly edit the DEFAULTV2 family, but it is possible to copy it and copy new fields into it.
We're always working on the form families, releasing new fields and features, so if you want to have all of the latest functionality, it's best to use the family we provide and support.
The following sections describe some of the common things you'll see in a form family.
Common Form Skeletons
| Name | Description |
| ControlSkel | This is used to control the flow through multi-page forms. Modification of these skeletons is not recommended |
| EditorSkel | This skeleton is used instead of the HTMLSkel when the form, page or field is being displayed in the forms designer |
| ExecuteActionsSkel | This skeleton is used to execute any actions following the successful server-side validation of a form submission |
| FormRuntime | This skeleton contains the form runtime in its uncompressed format. This is used when a form is published with the debug panel enabled |
| FormRuntimeDebugger | This skeleton contains the implementation of the debug panel displayed when a form is published with the panel enabled |
| FormRuntimeMin | This skeleton contains the form runtime in its compressed format. This is used when a form is published with the debug panel disabled |
| HTMLSkel | This is skeleton is the default for displaying the form, page or field. It generates HTML and, possibly, some JavaScript |
| ObjTypeDefSkel | This skeleton is used to generate all of part of an object type definition. Modification of these skeletons for forms and pages is not recommended. Field types will need such a skeleton if they intend to store data |
| PublishOptimise | This skeleton is used during the publishing phase to modify the form family information embedded in the published form to minimise its size. It is allowed to have detailed knowledge of the family |
| ROHTMLSkel | This skeleton is used instead of the HTMLSkel when the form, page or field is being displayed in read only mode with no HTML controls. This is typically used when generating emails from form content |
| SvrValidationSkel | If provided this skeleton is used instead of the ValidationSkel to perform server-side validation of a form, page or field. It is normally only required for fields where there are different server-side requirements |
| ValidationSkel | This skeleton is used to generate any JavaScript required to validate the form, page or field. The generated JavaScript will be executed in the web browser and on the server to perform server-side validation |
Common Form Scope Properties
| Name | Type | Description |
| Props["MODE"] | string | Indicates the purpose for which the skeleton is being processed. The available modes are "normal", "edit" and "readonlynoctrl". "edit" mode is used when displaying the form in the Form Designer. "readonlynoctrl" is used when displaying the form suitable for emails. |
| Props["ISMULTIPAGE"] | boolean | If true indicates that this is a multi page form. If false it is a single page form. |
| Props["FORM"]["NAME"] | string | Contains the name of the form |
| Props["FORMPROPERTIES"] | object | An object that contains all of the form properties defined in the form family. For example if there is a form property call "TITLE" its value can be accessed as Prop["FORMPROPERTIES"]["TITLE"]. |
| Props["REQPAGENAME"] | string | The name of the page that is being displayed |
Common Page Skeletons
| Name | Description |
| ControlSkel | This is used to control the flow through multi-page forms. Modification of these skeletons is not recommended |
| EditorSkel | This skeleton is used instead of the HTMLSkel when the form, page or field is being displayed in the forms designer |
| ExecuteActionsSkel | This skeleton is used to execute any actions following the successful server-side validation of a form submission |
| HTMLSkel | This is skeleton is the default for displaying the form, page or field. It generates HTML and, possibly, some JavaScript |
| ObjTypeDefSkel | This skeleton is used to generate all of part of an object type definition. Modification of these skeletons for forms and pages is not recommended. Field types will need such a skeleton if they intend to store data |
| ROHTMLSkel | This skeleton is used instead of the HTMLSkel when the form, page or field is being displayed in read only mode with no HTML controls. This is typically used when generating emails from form content |
| ValidationSkel | This skeleton is used to generate any JavaScript required to validate the form, page or field. The generated JavaScript will be executed in the web browser and on the server to perform server-side validation |
Common Page Scope Properties
| Name | Type | Description |
| Props["MODE"] | string | Indicates the purpose for which the skeleton is being processed. The available modes are "normal", "edit" and "readonlynoctrl". "edit" mode is used when displaying the form in the Form Designer. "readonlynoctrl" is used when displaying the form suitable for emails |
| Props["ISMULTIPAGE"] | boolean | If true indicates that this is a multi page form. If false it is a single page form |
| Props["FORM"]["NAME"] | string | Contains the name of the form |
| Props["PAGE"]["NAME"] | string | Contains the name of the page |
| Props["FORMPROPERTIES"] | object | An object that contains all of the form properties defined in the form family. For example if there is a form property call "TITLE" its value can be accessed as Prop["FORMPROPERTIES"]["TITLE"] |
| Props["PAGEPROPERTIES"] | object | An object that contains all of the page properties defined in the form family. For example if there is a page property call "SUBTITLE" its value can be accessed as Prop["PAGEPROPERTIES"]["SUBTITLE"] |
| Props["REQPAGENAME"] | string | The name of the page that is being displayed |
Common Field Type Skeletons
| Name | Description |
| EditorSkel | This skeleton is used instead of the HTMLSkel when the form, page or field is being displayed in the forms designer |
| HTMLSkel | This is skeleton is the default for displaying the form, page or field. It generates HTML and, possibly, some JavaScript |
| ObjTypeDefSkel | This skeleton is used to generate all of part of an object type definition. Modification of these skeletons for forms and pages is not recommended. Field types will need such a skeleton if they intend to store data |
| ROHTMLSkel | This skeleton is used instead of the HTMLSkel when the form, page or field is being displayed in read only mode with no HTML controls. This is typically used when generating emails from form content |
| ValidationSkel | This skeleton is used to generate any JavaScript required to validate the form, page or field. The generated JavaScript will be executed in the web browser and on the server to perform server-side validation |
Common Field Scope Properties
| Name | Type | Description |
| Props["MODE"] | string | Indicates the purpose for which the skeleton is being processed. The available modes are "normal", "edit" and "readonlynoctrl". "edit" mode is used when displaying the form in the Form Designer. "readonlynoctrl" is used when displaying the form suitable for emails |
| Props["ISMULTIPAGE"] | boolean | If true indicates that this is a multi page form. If false it is a single page form |
| Props["FORM"]["NAME"] | string | Contains the name of the form |
| Props["PAGE"]["NAME"] | string | Contains the name of the page |
| Props["FIELD"] ["NAME"] | string | Contains the name of the field |
| Props["FORMPROPERTIES"] | object | An object that contains all of the form properties defined in the form family. For example if there is a form property call "TITLE" its value can be accessed as Prop["FORMPROPERTIES"]["TITLE"] |
| Props["PAGEPROPERTIES"] | object | An object that contains all of the page properties defined in the form family. For example if there is a page property call "SUBTITLE" its value can be accessed as Prop["PAGEPROPERTIES"]["SUBTITLE"] |
| Props["FIELDPROPERTIES"] | object | An object that contains all of the field properties. For example if there is a field property call "LABEL" its value can be accessed as Prop["FIELDPROPERTIES "][" LABEL"] |
| Props["REQPAGENAME"] | string | The name of the page that is being displayed |
| Props["FIELDID"] | string | A unique identifier for this field taking into account the form and page (if multiple page). This should be the basis for any HTML elements ID's and name relating to the field. It should also be part of any global JavaScript functions or variables generated by the skeleton |
| Props["CURRENTVALUE"] | object | Object containing the current value of the field. This object will contain a property for each submitted HTML input control with a name starting with the unique identifier for this field. For field types that submit a single value this means that the current submitted value can be accessed as Props["CURRENTVALUE"][Props["FIELDID"]] |
| Props["CURRENTERROR"] | object | If present this contains details of any validation performed on the field. The object contains three properties: "VALID" a boolean indicating if the field is valid, "DESC" containing a description of the field, this is often a copy of the fields label, and "ERRMSG" any error message that needs to be displayed |
Share this page
