Internal Sales Form Training
Session #1
Basic iCM Forms
Gary Ratcliffe
www.gossinteractive.com
Forms Training Sessions
1
Basic iCM Forms
History & Architecture
Form Design & Implementation
Adding Dynamic Behaviour
2
Example Forms
3
Workflow Processes
History & Architecture
Why are we even doing this
•
Given a highly skilled developer with access to suitable tools a form can be
created using HTML, CSS and JavaScript to precisely meet most requirements
•
But 'highly skilled'
– Expensive
– Limited supply
•
The point of a forms package is to allow for most forms to be created
– Quicker
– Lower skill requirement
– Cheaper
•
However there will be compromises
– Never as flexible as HTML, CSS and JavaScript
– Work with and within the forms package approach – not against
– Some requirements will need to be adjusted
•
Be realistic
Some forms . . .
Some forms . . .
Some forms . . .
Some forms . . .
Some forms . . .
Some forms . . .
Some forms . . .
?
A little history…
•
Before iCM V9:
– Each API (and iCM itself) had its own form rendering code
– Very crude 'design' tool
– Inefficient – a form typically required 2 + (num fields *2) objects
– Virtually impossible to add new field types
•
iCM V9 – initial release
– Form rendering described in JavaScript.
• Each API needed a JavaScript interpreter
– Drag/drop Forms Designer
– A published form only required a single object
– Extensible field types using Forms Family Editor
•
iCM V9 – later releases
– Added Form Data Browser for view and updated form data
– Introduced improved set of field types: DEFAULTV2
V10 Release
•
Visual Script editor for creating JavaScript
•
Introduced API Server
– Forms rendering for all platforms performs in one place
– Still requires fairly complex APIs on each platform
•
Add greater server-side scripting capability
– Scripted form actions the most obvious
•
Workflow engine for form orchestration
•
Future updates
– New field types
– A complete forms service the handles the actual form submission
• Easier site integration
• Better support for file uploads
Forms Architecture
Family Definition
Create/Edit
Published
Form
Object
Publish
Skeletons
Published
Form
Type
Get
Create/Edit
Properties
Form Designer
Skeleton
Processor
API
Family Editor
Override Form
Properties
Context
Variables
Template
Forms Architecture
•
The most basic form in HTML:
<form>
Your name: <input type="text" name="yourname" />
<input type="submit" value="Submit" />
</form>
•
This HTML would be generated using information entered into the Forms
Designer and the contents of the Form Family.
•
The Form Family defines all of the HTML generated when a published form is
rendered.
•
Skeletons provide a template for the generated HTML.
•
Properties contain the values entered in the Form Designer and are combined
with the Skeleton to generate the HTML.
Form Rendering
Everything
that appears on the web page
comes from a
Skeleton
Form Rendering
Everything
in a skeleton is
defined in iCM
so in theory
anything is possible
a dangerous thing to say to a sales-person!!
Skeletons
•
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
– Anything else is output verbatim
•
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 existing within the scope of a single skeleton
•
Context variables can be used within the scope of a whole form
– Actually a single API call
•
A form family contains numerous named skeletons at the form, page and field
type level
Skeletons
Form Family
•
A form family is a collection of skeletons and properties that provide a complete
form rendering
•
It is divided into form, page and field type sections each of which contains its
own skeletons and properties
•
The Forms Designer uses the family to define the contents of the toolbox for
adding field types and setting form and page level properties
•
During form publishing 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
•
We have released two form families: DEFAULT and DEFAULTV2
•
DEFAULTV2 should always be used for new forms
•
Form Family contains its own help text
Underutilised at present because pre-V10 it wasn't removed on publish
Field Types
•
A field type is an, almost, self-contained set of skeletons and properties
•
It is used to render a single 'widget' on the form
•
It can generate a property within the forms object type definition
– This allows it to store a single value
•
Simple text fields, checkboxes, vertical containers. ReCAPTCHA are all field
types
•
iCM v9.0.0.0 shipped with 21 field types in DEFAULT family
•
iCM v10.0.2.0 is shipping with over 55 field types in DEFAULTV2 family
Form Family Editor
•
The form family is maintained using the Form Family Editor
•
This is the only tool for maintaining families, there is no magic tool used by
Development
•
It is not possible to edit this form family directly in iCM
– There is a hidden Application.cfm option
•
It is possible to copy field types to and from the family
Form Family Editor
DEFAULTV2 Exploration
DEMO
DEFAULTV2 in Form Family Editor
Form Publishing
Family Definition
Create/Edit
Published
Form
Object
Publish
Skeletons
Published
Form
Type
Get
Create/Edit
Properties
Form Designer
Skeleton
Processor
API
Family Editor
Override Form
Properties
Context
Variables
Template
Form Rendering
Family Definition
Create/Edit
Published
Form
Object
Publish
Skeletons
Published
Form
Type
Get
Create/Edit
Properties
Form Designer
Skeleton
Processor
API
Family Editor
Override Form
Properties
Context
Variables
Template
Why are we even doing this
•
Given a highly skilled developer with access to suitable tools a form can be
created using HTML, CSS and JavaScript to precisely meet most requirements
•
But 'highly skilled'
– Expensive
– Limited supply
•
The point of a forms package is to allow for most forms to be created
– Quicker
– Lower skill requirement
– Cheaper
•
However there will be compromises
– Never as flexible as HTML, CSS and JavaScript
– Work with and within the forms package approach – not against
– Some requirements will need to be adjusted
•
Be realistic
Form Design & Implementation
Overview
•
There are a number of aspects to the design of a form
•
Requirements
– The purpose of the form
– The data being collected
– The target audience
•
Design
– Ideal layout
– Ease of use
– Accessibility
•
Implementation
– Data storage
– Field names
– Validation implementation
– Dynamic behaviour
Focus of this session
Design Tips
•
Help users understand the form
•
Avoid large number of fields on a page
•
Use pages to split a form into manageable sections
•
Don't ask for the same information multiple times
•
Neat, consistent forms are easier to fill in
•
Apply correct and sensible validation
•
Indicate mandatory fields
•
Provide meaningful error messages
•
Test it
Design Layout Tips
•
The label position is a form level property
– Provides left, right and top alignment
– It is the responsibility of the field type to make use of this setting
– Because it’s a form property it can be changed by the template
Design Tips
•
We have the following books available
– Designing the moment
Robert Hoekman
– Designing the obvious
Robert Hoekman
– Rocket surgery made easy
Steve Krug
Implementation
•
Have a plan
– Information to be collected
– Single or multiple page
– Multiple views of submitted data? (external type definition)
– Sensible name
– Use a group for multiple related forms
•
Have a means of testing
– Form preview actually a bit rubbish
– Create a minimal form
– Publish it
– Create an article using the form
– Then just keep re-publishing the form as you develop it
My Approach
•
Create all pages
– Minimum number of fields
– No additional validation or dynamic behaviour
•
Add all fields
– The right fields on the right page of the right type
– Get field names correct and consistent
•
Add validation
– Simple built-in options
– Custom functions
– Page level checks
•
Add dynamic behaviour
– Showing/hiding fields
A New Form
Name of the form. This is used to create the object
type definition and in many parts of any generated
JavaScript. This can only contain A-Z and 0-9.
Where no external type is involved it must be
unique across the whole system.
Public: For use on sites
Private: For use within iCM for extras
etc
Form description. This appears in
various iCM menus and navigations
trees.
Object type definition to use. This will
'map' the form data to an existing type
definition. If not specified a type will be
generated during the publish phase.
Single Page Form – The form
•
Minimum
– A container field, Vertical Layout or Horizontal Layout
• Most input fields must exist in a container (fieldset)
– Some fields in the container
• A text field
– A Submit Button field
• Needs to actually submit the form!
MINIMALSINGLEPAGE1
Single Page Form – The Form
•
Publish the form
– Generates object type definition: FORM_<formname>
– This cannot be edited directly
– Creates published form object
•
Only published forms can be used
Single Page Form – The Form
Single Page Form – The Fields
•
Add all required fields
•
Correct type of field
•
Sensible field names and labels
MINIMALSINGLEPAGE2
Single Page Form – The Fields
MINIMALSINGLEPAGE2
Single Page Form – Basic Validation
•
Helpful error messages
•
Correct use of built-in validation options
•
As you type or on-submission validation
MINIMALSINGLEPAGE3
Single Page Form – Validation
MINIMALSINGLEPAGE3
Single Page Form – Save & Email Actions
•
Add an action to save the form data
•
Add an action to send an email
MINIMALSINGLEPAGE4
Single Page Form – Save & Email Actions
Field Types - 1
•
Actions
– Capita, Civica, Confirmation Message, Database Save, Email, Script, XML
over HTTP
•
Control
– Reset, Submit, Wizard
•
Input
– Checkbox, Checkbox Group, Date, File Upload, Multi-select List, Number,
Password, Radio Group, Recaptcha, Selection List, Text, Text Area
•
Layout
– Conditional, Horizontal, Vertical
•
Misc
– Address Lookup, Calculated Field, Client Location, Google Analytics
Event, Guidance Text, Hidden Field, Horizontal Rule, Location Picker,
Validation Errors, Validator
10.0.1.0
Field Types - 2
•
Web Developer
– Helper Variable, Hidden Input, HTML, Script Button
•
Workflow
– Complete Task
– Start Workflow
– Workflow Message
– Workflow Upload
•
iCM Subsite Extra
– Custom Subsite Settings
– Subsite Setting Mapping
•
Coming soon…
– APIServerAJAX, HTML Template, Upload Job, iCM Asset Select
10.0.1.0
Text Field Type Validation
•
Validation is performed client side if JavaScript is enabled
– No form submission until validation passes
•
Validation is also always performed server-side
– If a form always appears to be always submitting check for browser
JavaScript error
•
Field validation is typically performed in the following order:
– Required
– Length
– Pattern
– Regular Expression
– JavaScript function
•
The next test is only performed if the preceding one passes
•
Validation performed using ValidationSkel
– Some field types provide server-side specific SvrValidationSkel
Text Field Type Validation
function (helper, value) {
var isValid;
isValid = false;
value = value.toLowerCase();
if (value == 'hello' || value == 'goodbye') {
isValid = true;
}
return isValid;
}
TEXTFIELDVALIDATION
Text Field Type Validation
TEXTFIELDVALIDATION
Field Types similar to the Text type
•
The following field types are very similar to the text type
–
–
–
–
Checkbox
Number
Password
Text Area
•
They all provide similar properties and validation options
•
Some provide additional capabilities
– Number provides minimum and maximum validation
– Checkbox provide a 'must check' option
Listbox Field Types
•
There are two standard list box types:
– Selection List
• Provides a drop-down list of options
• Required and function validation provided
– Multi-select List
• A full list box
• Minimum, maximum and function validation provided
•
Both styles of list box are populated from Group Option Data
– Simple fixed entries
– Database query
– Browser side manipulation using Helper Variables
•
Each entry in a list consists of a Value, Display and, optional, Group
•
Stored values are a comma separated list of values
Listbox Field Types
LISTFIELDTYPES
Listbox Field Types
LISTFIELDTYPES
Checkbox and Radio Button Field Types
•
Similar to list boxes
– Radio Button Group
• Provide a number of linked radio buttons
• Required and function validation provided
– Check Box Group
• A collection of check boxes
• Minimum, maximum and function validation provided
•
Both styles of list box are populated from Option Data
– Simple fixed entries
– Database query
•
Each entry in a list consists of a Value and Display
•
Stored values are a comma separated list of values
•
Hidden field used to generate a submission when nothing selected
Checkbox and Radio Button Field Types
CHECKRADIOFIELDTYPES
Checkbox and Radio Button Field Types
CHECKRADIOFIELDTYPES
Date Field Type
•
This allows a date to be entered or selected from a calendar
•
The pop-up calendar is implemented using jQueryUI
•
The entered date is stored as a string in the format specified
•
Built in validation options are provided for:
– Dates in the past inclusive or exclusive of current date
– Dates in the future inclusive or exclusive of current date
– Weekdays only
– Weekends only
•
Additional validation provided by
– Custom regular expression
– JavaScript function
• The validation function is based a JavaScript Date object
Date Field Type
DATEFIELDTYPE
Date Field Type
DATEFIELDTYPE
Multi-Page Form – Wizard Buttons
•
The only field type capable of changing page
– Add an instance to each page
– Can have multiple instances for display at top and bottom of long page
– In the Forms Designer it will be display the default set of buttons based on
viewed pages position in the list of pages
MINIMALMULTIPAGE1
Multi-Page Form – Wizard Buttons
MINIMALMULTIPAGE1
Multi-Page Form – Wizard Buttons
•
There are some special properties
•
Back Mode
– None
– No validation
– Validate
No back navigation allowed
Allowed, no validation, no change to session data
Allowed, page must validate, session data updated
•
Back Function
– Programmatic control over selection of page to display
•
Next Function
– Programmatic control over selection of page to display
Summary
•
The basics for creating single and multi-page forms have been covered
•
Know what you are trying to achieve
– Who's going to be using the form?
– What information to you need to collect?
•
Single or multi-page?
– Avoid large single page data entry forms
•
External type definition
– Needs for different views of same stored data
•
Helpful validation
•
The next stage is to look at introducing more dynamic behaviour into a form
Adding Dynamic Behavior
Why?
•
We want to provide a standard, simple approach for form designers to:
– Show/hide fields as form contents are changed
– Enable/disable fields as form contents are changed
– Modify the contents of fields dependent on other fields
– Perform form specific operations when a field is changed
– Generate dynamic content
•
But
– There is a lot of variation between field types
• Some correspond to a single HTML element
• Others contain many elements
• Field 'changed' events correspond to different actions
– New field type requirements are always emerging
– Some operations take place server-side
•
So
– The only thing that knows how to perform these operations on a field of a
particular type is the field type itself
Form Runtime Library Concept
•
Provide an extensible library of functions available client and server-side
•
Allow an instance of a field type to register its existence with the library
•
Allow an instance of a field type to registers its capabilities
– Hide/show
– Enable/disable
– Event support
•
Make use of an industry standard library for client side operations
– jQuery and jQuery UI
– Field types can then generally ignore browser specific issues
•
Allow advanced field capabilities to be accessed using client and server-side
JavaScript
•
Providing debugging aids
Form Runtime Modes
Browser
Server
Form
Family
Fields
Runtime ‘helper’
Property Values
Properties
Handlers
Skeletons
Rendered
Form
Client Side
Handler
Script
Skeleton
Processor
Client Side
Validation
Script
helper
CLIENT
Server Side
Validation
Script
Skeleton
Script
<% … %>
helper
Context['HELPER']
SERVER
SKELETON
Core Form Runtime Library Functions
helper.queryFieldValue('TEXT1')
helper.updateFieldValue('TEXT1','Hello World')
helper.focusField('TEXT1')
helper.showField('TEXT1')
helper.hideField('TEXT1')
helper.enableField('TEXT1')
helper.disableField('TEXT1')
helper.focusActionButton('FINISH')
helper.showActionButton('FINISH')
helper.hideActionButton('FINISH')
helper.triggerActionButton('FINISH')
helper.enableActionButton('FINISH')
helper.disableActionButton('FINISH')
COREHELPERFUNCTIONS
Form Runtime Library Debug Panel
•
The Debug Panel is enabled via a form level property
•
It provides the following:
– Overview including version information
– Context Variables
– Variables
– Field Values
– Events
– Console
•
Overview and Console will be examined in more detail now
Debug Panel - Overview
Runtime Version
The follows a similar scheme
to API versions.
jQuery information
In this case the site is already
loading jQuery and jQuery UI
Details of the current form.
COREHELPERFUNCTIONSDEBUG
Debug Panel - Console
Command history
Double clicking will copy the
command ready to execute
again.
JavaScript can be executed by typing
into the command box and clicking
Execute. The helper variable is
available to access the runtime
library.
COREHELPERFUNCTIONSDEBUG
Form, Page and Field Type Support
•
Form and Page Init functions
•
Default function
Validation function
Field event handler function
– These functions are provided by many field types
•
Script function
– Provided by the Script button field type
Conditional function
– Provided by the Conditional Layout field type
Calculated field function
– Provided by the Calculated field type - DEPRECATED
Next and Previous page function
– Provided by the Wizard buttons field type
•
•
•
Form, Page and Field Type Support
•
Functions can be edited using the Visual Script editor or raw JavaScript editor
•
Visual Script editor provides prototypes for each type of function:
Form and Page Init Function
INITFUNCTIONS
Default Function
DEFAULTFUNCTIONS
Validation Function
VALFUNCTIONS
Field Event Handler Function
EVENTFUNCTIONS
Field Event Handler Function
NEWPAGEINIT generated
when page loads. Note
validation failure since the
field requires the entry of a
valid post code.
CHANGE generated when
field changes. Validation now
passes because a valid post
code was entered.
EVENTFUNCTIONS
Debug panel Events tab
shows details of events as
they are generated.
Field Event Handler Function
• The Form runtime library will detect and block circular events
– Based on a nested call to the same handler with the same event
– For example:
• Field ONE is changed, its hander updates field TWO
• Field TWO's handler then updates field ONE
• Real world circular events tend to be much less obvious!
Circular event detected and
blocked.
EVENTFUNCTIONSCIRCULAR
Script Button Function
SCRIPTFUNCTIONS
Wizard Next and Previous Functions
NEXTPREVFUNCTIONS
Wizard Next and Previous Functions
NEXTPREVFUNCTIONS
Wizard Next and Previous Functions
PAGE3 displayed because
HAVEALIAS is unchecked
NEXTPREVFUNCTIONS
Wizard Next and Previous Functions
PAGE2 displayed because
HAVEALIAS is checked
NEXTPREVFUNCTIONS
List-box Helper Variables
VARIABLELIST
List-box Helper Variables
VARIABLELIST
Thank You
Q&A
www.gossinteractive.com