Four51 Spec Form API User Guide
VERSION 3.0
JUNE 2008
Table Of Contents
Overview ...................................................................................................................................... 3
Getting Started .............................................................................................................................. 3

Enabling the Service .......................................................................................................... 3

Accessing the Advanced Scripting Interface .......................................................................... 3
Spec Form API Methods .................................................................................................................. 4
1. get (id) ...................................................................................................................... 4
2. getOptionIndex(value) ................................................................................................. 4
3. getSelectedOptionIndex() ............................................................................................ 4
4. selectedText() ............................................................................................................ 4
5. selectedValue() ........................................................................................................... 5
6. addOption(text[, value][, selected]) .............................................................................. 5
7. insertOption(index, text[, value][, selected]) .................................................................. 5
8. addOptions(value[, …]) ................................................................................................ 5
9. selectOption(value) ..................................................................................................... 6
10. hideOption(value) ....................................................................................................... 6
11. hideOptionAt(index) .................................................................................................... 6
12. hideOptions(value[, …]) ............................................................................................... 6
13. hideOptionRange(fromValue[, toValue]) ......................................................................... 7
14. hideOptionRangeAt(fromIndex[, toIndex]) ..................................................................... 7
15. hideAllOptions() .......................................................................................................... 7
16. showOption(value) ...................................................................................................... 7
17. showOptionAt(index) ................................................................................................... 8
18. showOptions(value[, …]) .............................................................................................. 8
19. showOptionRange(fromValue[, toValue])........................................................................ 8
20. showOptionRangeAt(fromIndex[, toIndex]) .................................................................... 8
21. showAllOptions() ......................................................................................................... 9
22. removeOption(value) ................................................................................................... 9
23. removeOptionAt(index) ................................................................................................ 9
24. removeOptions(value[, …])........................................................................................... 9
25. removeOptionRange(fromValue[, toValue]) .................................................................. 10
26. removeOptionRangeAt(fromIndex[, toIndex]) ............................................................... 10
27. removeAllOptions() ................................................................................................... 10
28. show() ..................................................................................................................... 10
29. hide() ...................................................................................................................... 10
30. trigger(eventName) ................................................................................................... 11
31. toggle() ................................................................................................................... 11
32. setText(value) .......................................................................................................... 11
33. clearText() ............................................................................................................... 11
34. imgSrc(value) ........................................................................................................... 11
35. autoTab(controlName) ............................................................................................... 12
36. setPopup(elementName) ............................................................................................ 12
Four51 Spec Form Widgets............................................................................................................ 13
1. Wizard ..................................................................................................................... 13
2. Image Selector ......................................................................................................... 14
3. Calendar .................................................................................................................. 16
4. DefinedDropDown ..................................................................................................... 17
5. Time ........................................................................................................................ 17
6. CheckBox ................................................................................................................. 18
Four51 Spec Form Validators ......................................................................................................... 20
1. regex(regex, [options]).............................................................................................. 20
2. custom(func, [options]) ............................................................................................. 21
3. required([options]) .................................................................................................... 21
4. requiredIfIndex(compared, comparer, [options]) .......................................................... 21
5. requiredIfValue(compared, comparer, [options]) ........................................................... 22
6. number([options])..................................................................................................... 22
7. email([options]) ........................................................................................................ 22
8. phone([options]) ....................................................................................................... 23
9. zipfour([options]) ...................................................................................................... 23
10. url([options])............................................................................................................ 23
11. minimum([options]) .................................................................................................. 24
12. maximum([options]) ................................................................................................. 24
13. date([options]) ......................................................................................................... 24
14. range([options]) ....................................................................................................... 25
Additional Reference Material ........................................................................................................ 25
Customer Service & Support.......................................................................................................... 25
Four51 Spec Form API User Guide
2
Overview
Four51 has identified many common spec form functionality requests that require extensive
JavaScript programming and wrapped them into an easy to use Application Programming
Interface. The goal of this API is to provide hooks into methods that are attached to elements
on spec forms including spec controls. It is intended for use by skilled developers familiar with
JavaScript programming principles. However, it can be utilized by non-developers needing to
leverage additional features without the need to write JavaScript code. The API is divided into
two distinctive parts: Methods and Widgets. Methods are purely programmatic function calls
that are referenced in the JavaScript code. Widgets are add-ins that can be utilized without a
programming effort, but do also have events that allow you to hook into their functionality
This guide is intended to show you how to get started with the service and describes the
methods and Widgets currently available in the API. Methods and Widgets are frequently
added to the library.
Getting Started
Enabling the Service

o
To access Advanced Scripting, your administration user must be enabled with
appropriate permissions. To enable your user, contact Four51.
Accessing the Advanced Scripting Interface

o
The Advanced Scripting interface is available with variable products only. To access
the interface, do the following.
1. Log on to your Four51 administration interface.
2. Navigate to a variable product.
3. Select the Spec Form link in the left-hand navigation.
4. You should now see a tab named Advanced Scripting. Click this tab to access
the interface. Place your JavaScript code here and click Save. Note that the
interface provides auto complete features to ease your code development.
Four51 Spec Form API User Guide
3
Spec Form API Methods
Four51 Spec Form API is a collection of JavaScript functions made available to administrator
users who have been granted permission to use Advanced Scripting in their product's spec
forms. These methods are designed to ease the complexity of JavaScript by identifying
common programming tasks specific to spec forms and creating alternative, easy to
understand functions. Included in each methods definition are the parameter signatures.
Parameters surrounded with [] are considered optional. If not marked optional you should
consider required.
1. get (id)
This function returns a reference to the control specified.
Parameters:
id
The ID, or in the case of a spec control the Name, of a control.
Example:
var ctrl = get('Input');
get('Input').show();
specForm.get('Input').show();
2. getOptionIndex(value)
This function returns the index of the SELECT list option whose value or text matches
the given parameter, with priority givent to value. Returns -1 if no matching option is
found. “Hidden” options are taken into account.
Parameters:
value
The option value or text to find
Example:
spec['SelectList'].getOptionIndex('Testing');
3. getSelectedOptionIndex()
This function returns the index of the SELECT list option that is currently selected.
“Hidden” options are taken into account (unlike built-in selectedIndex property).
Example:
spec['SelectList'].getSelectedOptionIndex();
4. selectedText()
This function returns the display text of the currently selected SELECT list option.
Example:
spec['SelectList'].selectedText();
Four51 Spec Form API User Guide
4
5. selectedValue()
This function returns the value of the currently selected SELECT list option.
Example:
spec['SelectList'].selectedValue();
6. addOption(text[, value][, selected])
This function appends a new option to the end of a SELECT list.
Parameters:
text
The display text associated with the option.
value
Optional. The value associated with the option. If omitted, value will be the same
as text.
selected
Optional. A boolean representing whether the new item becomes the currently
selected item in the SELECT list.
Example:
spec['SelectList'].addOption('New Item', '123456', true);
7. insertOption(index, text[, value][, selected])
This function inserts a new option in a SELECT list at the specific index location.
Parameters:
index
The location to insert the new option. The items count begins at 0.
text
The display text associated with the option.
value
Optional. The value associated with the option. If omitted, value will be the same
as text.
selected
Optional. A boolean representing whether the new item becomes the currently
selected item in the SELECT list.
Example:
spec['SelectList'].insertOption(2, 'New Item', '123456', false);
8. addOptions(value[, …])
This function appends multiple new options to the end of a SELECT list.
Parameters:
value
One or more of the following, in any combination:

An individual value representing the text and value of an option.

An array, where each item represents the text and value of an option.
Four51 Spec Form API User Guide
5

A hash of key/value pairs, where each key represents and option text and
value represents option value.
Examples:
spec['SelectList'].addOptions(1,2,3); // individual parameters
spec['SelectList'].addOptions([1,2,3]); // array
spec['SelectList'].addOptions({'one': 1, 'two': 2, 'three': 3}); // hash
spec['SelectList'].addOptions(1, [2, 3], {'four': 4}); // combination
9. selectOption(value)
This function finds the SELECT list option whose value or text matches the given
parameter and, if found, sets it as the selected option.
Parameters:
value
The option value or text to select.
Example:
spec['SelectList'].selectOption('Testing');
10. hideOption(value)
This function finds the SELECT list option whose value or text matches the given
parameter and, if found, hides the option.
Parameters:
value
The option value or text to hide.
Example:
spec['SelectList'].hideOption('Testing');
11. hideOptionAt(index)
This function hides the SELECT list option at the given zero-based index.
Parameters:
index
The index of the option to hide.
Example:
spec['SelectList'].hideOptionAt(3);
12. hideOptions(value[, …])
This function finds the SELECT list options whose values or text match the given
parameters and, if found, hides the options.
Parameters:
value
Four51 Spec Form API User Guide
6
One or more of the following:

An individual value representing the text or value of an option.

An array, where each item represents the value or text of an option.
Examples:
spec['SelectList'].hideOptions('Testing1', 'Testing2');
spec['SelectList'].hideOptions(['Testing1', 'Testing2']);
13. hideOptionRange(fromValue[, toValue])
This function finds the SELECT list options whose values or text match the given
parameters and, if found, hides the range of options that appear in the list between
fromValue and toValue, inclusive.
Parameters:
fromValue
The value or text of the first option in the SELECT list to hide.
toValue
Optional. The value or text of the last option in the SELECT list to hide. If omitted
or not found, all options from fromValue to the end of the list are hidden.
Example:
spec['SelectList'].hideOptionRange('Testing2', 'Testing6');
14. hideOptionRangeAt(fromIndex[, toIndex])
This function hides the SELECT list options within the given index range, inclusive.
Parameters:
fromIndex
The zero-based index of the first option in the SELECT list to hide.
toValue
Optional. The zero-based index of the last option in the SELECT list to hide. If
omitted, all options from fromIndex to the end of the list are hidden.
Example:
spec['SelectList'].hideOptionRangeAt(1, 5);
15. hideAllOptions()
This function hides all options in the SELECT list.
Example:
spec['SelectList'].hideAllOptions();
16. showOption(value)
This function finds the SELECT list option whose value or text matches the given
parameter and, if found and hidden, shows the option.
Parameters:
value
Four51 Spec Form API User Guide
7
The option value or text to show.
Example:
spec['SelectList'].showOption('Testing');
17. showOptionAt(index)
This function shows the SELECT list option at the given zero-based index, if hidden.
Parameters:
index
The index of the option to show.
Example:
spec['SelectList'].showOptionAt(3);
18. showOptions(value[, …])
This function finds the SELECT list options whose values or text match the given
parameters and, if found, shows the hidden options.
Parameters:
value
One or more of the following:

An individual value representing the text or value of an option.

An array, where each item represents the value or text of an option.
Examples:
spec['SelectList'].showOptions('Testing1', 'Testing2');
spec['SelectList'].showOptions(['Testing1', 'Testing2']);
19. showOptionRange(fromValue[, toValue])
This function finds the SELECT list options whose values or text match the given
parameters and, if found, shows the range of hidden options that appear in the list
between fromValue and toValue, inclusive.
Parameters:
fromValue
The value or text of the first option in the SELECT list to show.
toValue
Optional. The value or text of the last option in the SELECT list to show. If omitted
or not found, all options from fromValue to the end of the list are shown.
Example:
spec['SelectList'].showOptionRange('Testing2', 'Testing6');
20. showOptionRangeAt(fromIndex[, toIndex])
This function shows the hidden SELECT list options within the given index range,
inclusive.
Four51 Spec Form API User Guide
8
Parameters:
fromIndex
The zero-based index of the first option in the SELECT list to show.
toValue
Optional. The zero-based index of the last option in the SELECT list to show. If
omitted, all options from fromIndex to the end of the list are shown.
Example:
spec['SelectList'].showOptionRangeAt(1, 5);
21. showAllOptions()
This function shows all hidden options in the SELECT list.
Example:
spec['SelectList'].showAllOptions();
22. removeOption(value)
This function finds the SELECT list option whose value or text matches the given
parameter and, if found, removes the option.
Parameters:
value
The option value or text to remove.
Example:
spec['SelectList'].removeOption('Testing');
23. removeOptionAt(index)
This function removes the SELECT list option at the given zero-based index.
Parameters:
index
The index of the option to remove.
Example:
spec['SelectList'].removeOptionAt(3);
24. removeOptions(value[, …])
This function finds the SELECT list options whose values or text match the given
parameters and, if found, removes the options.
Parameters:
value
One or more of the following:

An individual value representing the text or value of an option.

An array, where each item represents the value or text of an option.
Four51 Spec Form API User Guide
9
Examples:
spec['SelectList'].removeOptions('Testing1', 'Testing2');
spec['SelectList'].removeOptions(['Testing1', 'Testing2']);
25. removeOptionRange(fromValue[, toValue])
This function finds the SELECT list options whose values or text match the given
parameters and, if found, removes the range of options that appear in the list between
fromValue and toValue, inclusive.
Parameters:
fromValue
The value or text of the first option in the SELECT list to remove.
toValue
Optional. The value or text of the last option in the SELECT list to remove. If
omitted or not found, all options from fromValue to the end of the list are removed.
Example:
spec['SelectList'].removeOptionRange('Testing2', 'Testing6');
26. removeOptionRangeAt(fromIndex[, toIndex])
This function removes the SELECT list options within the given index range, inclusive.
Parameters:
fromIndex
The zero-based index of the first option in the SELECT list to remove.
toValue
Optional. The zero-based index of the last option in the SELECT list to remove. If
omitted, all options from fromIndex to the end of the list are removed.
Example:
spec['SelectList'].removeOptionRangeAt(1, 5);
27. removeAllOptions()
This function removes all options in the SELECT list.
Example:
spec['SelectList'].removeAllOptions();
28. show()
This function sets the control to visible.
Example:
spec['Input'].show();
29. hide()
This function set the control to hidden.
Four51 Spec Form API User Guide
10
Example:
spec['Input'].hide();
30. trigger(eventName)
This function triggers the event specified for the control.
Parameters:
eventName
The name of the event to trigger (must be valid event).
Example:
spec['Input'].trigger('onmouseover');
31. toggle()
This function toggles the control's visibility. If it is visible it is hidden. If hidden it is
shown.
Example:
spec['Input'].toggle();
32. setText(value)
This function sets the text value for the control.
Parameters:
value
The string/text to assign to the control's value.
Example:
spec['Input'].setText('New Value');
33. clearText()
This function removes the text value for the control.
Example:
spec['Input'].clearText();
34. imgSrc(value)
This function sets the source value of an image control type. The receiving element
must be an img type.
Parameters:
value
The url location of the image.
Four51 Spec Form API User Guide
11
Example:
<img src="" id="imgPlaceHolder" />
get('imgPlaceHolder').imgSrc('/Images/logo.jpg');
35. autoTab(controlName)
This function changes focus from the current textbox to the specified control when the
input length matches the MaxLength property of the textbox.
Parameters:
controlName
The name of the control that will receive focus.
Example:
spec['City'].autoTab('State');
36. setPopup(elementName)
This function attaches the functions needed to show and hide another element usually
designated as a help message. All appropriate properties are also attached to control
how, when and where the control is displayed.
Parameters:
elementName
The name of the element that will be displayed on mouseover.
Example:
HTML:
<div id="HelpItem" class="HelpPopup">Here is the help</div>
<p>[[Input]]</p>
Advanced Script:
spec['Input'].setPopup('HelpItem');
Four51 Spec Form API User Guide
12
Four51 Spec Form Widgets
Four51 Spec Form Widgets are functional control sets that perform specific actions and do not
require JavaScript programming.
1. Wizard
This widget creates a wizard like approach for user input. When the wizard is defined
the div container tags within the wizard become the steps. The wizard is designed to
eliminate clutter and present a more friendly form for input to the end user. Events
are exposed that allow you to write code against the widget.
Instructions:
For a simple implementation create a <div> HTML tag must be created and a class
defined as "Wizard". For advanced implementations, do not include the class
definition "Wizard", and add an "ID" attribute to the top level element. Within this
<div> tag all other <div> tags become the individual panels of the wizard. There
is no limit on the number of panels (steps) in the wizard. Additionally, navigation
buttons are inserted into the wizard and a border is set around the entire widget.
HTML Example:
<div class="Wizard">
<div>[[FirstName]]&nbsp;[[LastName]]</div>
<div>[[Address]]</div>
<div>[[City]], [[State]] [[Zip]]</div>
<div>[[Phone]]</div>
</div>
Advanced Scripting:
HTML:
<div id="Wizard">
<div>[[FirstName]]&nbsp;[[LastName]]</div>
<div>[[Address]]</div>
<div>[[City]], [[State]] [[Zip]]</div>
<div>[[Phone]]</div>
</div>
Script:
get('Wizard').wizard({
border: "1px solid rgb(0,0,0)",
margin: "5px",
padding: "5px",
width: "100%",
height: "500px",
buttonAlign: "right",
buttonTextBack: "previous",
buttonTextForward: "next"
});
Options:




border: CSS style for defining a border around the entire wizard.
margin: CSS style for defining margin around the entire wizard.
padding: CSS style for defining margin around the entire wizard.
width: CSS style for defining width of the entire wizard.
Four51 Spec Form API User Guide
13





height: CSS style for defining height of the entire wizard.
buttonAlign: CSS style for alignment of navigation buttons in wizard.
buttonTextBack: Text assigned to back navigation button.
buttonTextForward: Text assigned to forward navigation button.
debug: True or false. When true the control holding the value is displayed.
Events:





onBeforeMoveBack(): Triggered by an action causing the wizard to step
back. Return true to allow action to complete.
onBeforeMoveForward(): Triggered by an action causing the wizard to step
forward. Return true to allow action to complete.
onAfterMoveBack(): Triggered after the action to step back. Return true
to allow action to complete.
onAfterMoveForward(): Triggered after the action to step forward. Return
true to allow action to complete.
onError(): Error handling for wizard navigation. By default an alert is
displayed notifying user the navigation is out of range.
Properties:
index(): Gets the current index of the wizard panels (0 based).
Methods:

moveForward(): Forces wizard to step forward.

moveBack(): Forces wizard to step back.

moveTo(index): Forces wizard to move to the panel/step identified by the
index parameter.
Events, Properties and Methods examples:
specForm.wizard.onBeforeMoveBack = function() {
alert('moving back to index: ' + specForm.wizard.index());
return true;
}
specForm.wizard.moveTo(2);
specForm.wizard.onError = function() {
specForm.wizard.moveTo(0);
}
Error Handling:
When a panel is referenced that does not exists an IndexOutofBounds exception
will be thrown and an alert will pop up in the browser. All actions will be
cancelled. The event onError is called when this error is caught.
2. Image Selector
This widget creates a thumbnail and preview image selection interface. When the
image selector is defined the spec control is replaced with a scrolling thumbnail
preview of all images and a larger preview when an image is selected. This is
designed to provide an enhanced user input for image choices you make available in
your Pageflex project. Events are exposed that allow you to write code against the
widget. Custom parameters are available to alter the styling of the control.
Instructions:
Four51 Spec Form API User Guide
14
A <div> HTML tag must be created that will contain the spec control token. Within
the Advanced Scripting tab you must attach the widget to the spec control. In the
attachment you may specify optional parameters that define the rendering of the
control.
HTML Example:
<div>[[Image]]</div>
Advanced Scripting:
HTML:
[[Image]]
Script:
spec['Image'].imageSelector({
width: 500,
height: 185,
thumbnailsize: 50,
bgcolor: "#fff",
bordercolor: "#000",
highlightcolor: "#ff0",
rollovertext: "Click this to insert image",
images: ['/Images/Demo/08-1.gif', '/Images/Demo/08.gif',]
});
Options:









width: Numeric value for the width of the entire widget
height: Numeric value for the height of the entire widget.
thumbnailSize: Numeric value, in pixels, of the width and height of the
thumbnails.
bordercolor: The HTML color value for the border.
highlightColor: The HTML color value for the border when the mouse
hovers the thumbnail.
bgcolor: The HTML color for the background.
rollovertext: The tooltip string when the mouse hovers the thumbnail.
effect: Define animation to perform on thumbnail click. Options include:
slideDown, slideUp, fadeIn, show.
debug: True or false. When true the control holding the value is displayed.
Events:



onThumbnailClick(): Triggered by the mouse click on a thumbnail image.
onThumbnailHover(): Triggered by the mouseover on a thumbnail image.
onChange(): Triggered after the value of the imageSelector has changed.
Properties:


value(): Sets or gets the current value on the control.
image(): Sets or gets the current url of the image selected.
Methods:
reset(): Resets the control value to null and removes the image preview.
Events, Properties and Methods examples:
Four51 Spec Form API User Guide
15
spec['Image'].imageSelector.reset();
spec['Image'].imageSelector.value('/images/home.jpg');
spec['Image'].imageSelector.onThumbnailHover = function() {
alert(spec['Image'].imageSelector.value());
}
3. Calendar
This widget attaches a calendar control to the spec control input. The user is then
able to browse through the calendar and select a date from a visual perspective. The
text representation is controlled by the selection of the calendar helping to enforce
date formatting requirements. Events are exposed that allow you to write code
against the widget. A number of properties are exposed to allow for easy parsing of
date items such as the day of the week.
HTML Example:
<span class="Calendar">[[Date]]</span>
Advanced Scripting:
HTML:
[[Date]]
Script:
spec['Date'].calendar({
width: "80",
format: "DayOfWeek"
});
Options:


width: Numeric value for the width of the input control.
format: The value format of the selection. Choices include: Year, Month,
DayOfMonth, DayOfWeek, FullDate. If not set the value format mask is
MM/DD/YYYY.
Events:
onChange(): Triggered when the values changes and the control loses focus.
Properties:






value(): Returns the value of the control based on the format defined in
options.
fullDate(): Returns the full date value of the selected date. Ex: Thu Nov
27 2008 09:22:42 GMT-0600 (Central Standard Time).
dayOfMonth(): Returns the numeric representation of the selected day of
the month. Ex: 20.
dayOfWeek(): Returns the string representation of the selected day of the
week. Ex: Monday).
month(): Returns the text representation of the selected month. Ex: July.
year(): Returns the numeric representation of the selected year. Ex: 2008.
Events, Properties and Methods examples:
spec['Date'].calendar.fullDate();
spec['Date'].calendar.onChange = function() {
Four51 Spec Form API User Guide
16
alert(spec['Date'].calendar.value());
}
4. DefinedDropDown
This widget creates a drop down list of defined values and text and stores selections in
text spec control.
HTML Example:
<span class="States">[[TextSpec]]</span>
Advanced Scripting:
HTML:
[[TextSpec]]
Script:
spec['TextSpec'].statedropdown({
valueType: "abbr",
displayType: "full"
});
spec['TextSpec'].countrydropdown();
Options:



Events:

valueType: Defines the value stored for the spec. Choices include: "abbr"
and "full". "abbr" stores the abbreviation, and "full" stores the full name
(Ex: full = abbr / Alabama = AL)
displayType: Defines the display text for the dropdown. Principles are the
same as valueType
debug: True or false. When true the control holding the value is displayed.
onChange(): Triggered when the selection changes.
Properties:

selectedValue(): Gets the currently selected value.

selectedText(): Gets the currently selected display value.

selectedIndex(): Gets the currently selected index (0 based).
Events, Properties and Methods examples:
spec['TextSpec'].statedropdown.onChange = function() {
alert(spec['TextSpec'].statedropdown.selectedText());
}
spec['TextSpec'].countrydropdown.onChange = function() {
alert(spec['TextSpec'].countrydropdown.selectedIndex());
}
5. Time
This widget creates a three drop down inputs, one each for hour, minutes and ante
meridium. As each value is set the spec value is updated using the normal format for
time (Ex: 2:15 pm).
HTML Example:
Four51 Spec Form API User Guide
17
<span class="Time">[[TextSpec]]</span>
Advanced Scripting:
HTML:
[[TextSpec]]
Script:
spec['TextSpec'].time({
increment: 15
});
Options:


Events:

increment: Determines the incremental value for the minutes displayed as
choices. The default value is 1. Ex: 15 = 00|15|30|45.
debug: True or false. When true the control holding the value is displayed.
onChange(): Triggered when the selection changes.
Properties:

value(): Gets the currently selected value.

hour(): Gets the currently selected hour value.

minute(): Gets the currently selected minute value.

meridiem (): Gets the currently selected meridiem value.
Events, Properties and Methods examples:
spec['Time'].time.onChange = function() {
alert(spec['Time'].time.hour());
}
6. CheckBox
This widgets creates a check box input type for user form input. Attached to a regular
spec, the checked or unchecked value is associated with the spec. Options to define
checked and unchecked values are available. The default values are true or false.
Text to display to the immediate left of the checkbox may be set in the options.
HTML Example:
<span class="CheckBox">[[Box]]</span>
Advanced Scripting:
HTML:
[[Box]]
Script:
spec['Box'].checkbox({
checkedValue: 'Yes',
uncheckedValue: 'No',
displayText: 'Would you like to go to the park?'
});
Options:
Four51 Spec Form API User Guide
18



checkedValue: Determines the value assigned to spec when checkbox is
checked.
uncheckedValue: Determines the value assigned to spec when checkbox is
not checked.
displayText: Determines the displayed text rendered to the immediate left
of the checkbox.
Events:
onClick(): Triggered when the checkbox is clicked.
Properties:
value(): Gets the current value based on checkbox state.
Events, Properties and Methods examples:
spec['Box'].checkbox.onClick = function() {
alert(spec['Time'].checkbox.value());
}
Four51 Spec Form API User Guide
19
Four51 Spec Form Validators
Four51 Spec Form Validators are extended validation controls for specific input requirements.
Every validators can be defined to fire on one of two events: onblur, onsubmit. Controls for
displaying validation errors is built into each validators. The event can be overridden and
controlled separately if desired. It is recommended that you do not override onSuccess or
onError unless absolutely necessary. All validators have identical options exposed. By default,
when validation fails a red exclamation point image is displays with mouse over error message
and the control's background property is changed to pink. On success these errors are cleared.
When the action is defined as "onBlur" the error is marked next to the control, however the
form is still allowed to submit.
Options:




action: The event that validation should occur. Two available choices:
onSubmit, onBlur. The default value is onSubmit.
message: The error message to display when validation fails. Each individual
validator has a specific message.
onSuccess(): Overridable function called when validation succeed. A
parameter, "ctl", is passed as a reference to the control being validated.
onError(): Overridable function called when validation fails. A parameter, "ctl",
is passed as a reference to the control being validated.
Example:
spec['Control'].number({
action: "onBlur",
message: "You must enter a number.",
onSuccess: function() {
alert('Your entry is a number!')
},
onError: function() {
alert('Your entry is not a number!')
});
1. regex(regex, [options])
Accommodates custom regular expression validators.
Parameters:
options
Includes all optional properties applied to all validators
regex
String value consisting of a valid regular expression
Example:
HTML:
[[Name]]
Advanced Script:
spec['Name'].regex({
action: "onBlur",
message: "Minimum of 6 characters required"
}, "(?=^.{6,100}$).*$");
Four51 Spec Form API User Guide
20
2. custom(func, [options])
Accommodates custom function validators.
Parameters:
options
Includes all optional properties applied to all validators
func
Function for validation. Must return true or false.
Example:
HTML:
[[Name]]
Advanced Script:
spec['Name'].custom({ message: "You must type (The Suns)" },
function() {
var result = spec['Name'].value == 'The Suns';
return result;
}
);
3. required([options])
Requires a value of any type be entered into spec as validation.
Parameters:
options
Includes all optional properties applied to all validators
Example:
HTML:
[[Name]]
Advanced Script:
spec['Name'].required();
4. requiredIfIndex(compared, comparer, [options])
Sets conditional entry requirement entry on spec when index of selection spec matches
the comparer parameter.
Parameters:
compared
Spec control to validate when comparison is true.
comparer
The index to trigger requirement of validators.
options
Includes all optional properties applied to all validators
Four51 Spec Form API User Guide
21
Example:
HTML:
[[Name]] [[Title]]
Advanced Script:
spec['Name'].requiredIfIndex(spec['Title'], 2);
5. requiredIfValue(compared, comparer, [options])
Sets conditional entry requirement entry on spec when value of spec matches the
comparer parameter.
Parameters:
compared
Spec control to validate when comparison is true.
comparer
The value to trigger requirement of validators.
options
Includes all optional properties applied to all validators
Example:
HTML:
[[Name]] [[Title]]
Advanced Script:
spec['Name'].requiredIfValue(spec['Title'], 'Vice President');
6. number([options])
Requires a valid integer/number be entered into spec control.
Parameters:
options
Includes all optional properties applied to all validators
Example:
HTML:
[[Age]]
Advanced Script:
spec['Age'].number();
7. email([options])
Requires a valid email address be entered into spec control. Regular expression used for
validation: ^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$
Parameters:
options
Four51 Spec Form API User Guide
22
Includes all optional properties applied to all validators
Example:
HTML:
[[Email]]
Advanced Script:
spec['Email'].email();
8. phone([options])
Requires a valid US phone number be entered into spec control. Phone numbers may be
delimited with - or . and area codes () are optional. Example of allowed phone number:
(612)-555-5555 or 612.555.5555. Regular expression used for validation: ^\(\d{3}\)
?\d{3}(-|.)?\d{4}|^\d{3}(-|.)?\d{3}(-|.)?\d{4}
Parameters:
options
Includes all optional properties applied to all validators
Example:
HTML:
[[Email]]
Advanced Script:
spec['Email'].email();
9. zipfour([options])
Requires a valid US zip code plus four be entered into spec control. Plus four is optional
and will validate if missing. Example of allowed zip code: 90120, 90120-5555. Regular
expression used for validation: ^\d{5}$|^\d{5}-\d{4}$
Parameters:
options
Includes all optional properties applied to all validators
Example:
HTML:
[[Zip]]
Advanced Script:
spec['Zip'].zipfour();
10. url([options])
Requires a valid URL be entered into spec control. This validation is quite forgiving.
Essentially it attempts to ensure that the URL does not contain invalid characters nor
invalid protocol prefixes. Example of allowed URL: http://www.four51.com,
http://four51.com. Regular expression used for validation:
Four51 Spec Form API User Guide
23
(((http|ftp|https)://)|(\.))+(([a-zA-Z0-9\._-]+\.[a-zA-Z]{2,6})|([0-9]{1,3}\.[09]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))(/[a-zA-Z0-9\&amp;%_\./-~-]*)?
Parameters:
options
Includes all optional properties applied to all validators
Example:
HTML:
[[Website]]
Advanced Script:
spec['Website'].url();
11. minimum([options])
Requires the entered value, when parsed to an integer, must be greater than the
amount specified.
Parameters:
options
Includes all optional properties applied to all validators
Example:
HTML:
[[Total]]
Advanced Script:
spec['Total'].minimum({ min: 100 });
12. maximum([options])
Requires the entered value, when parsed to an integer, must be less than the amount
specified.
Parameters:
options
Includes all optional properties applied to all validators
Example:
HTML:
[[Total]]
Advanced Script:
spec['Total'].maximum({ max: 100 });
13. date([options])
Requires the entered value be a valid date representation according the JavaScript
object reference. This validation uses the JavaScript Date object function "parse". You
Four51 Spec Form API User Guide
24
can read about this method here: http://www.w3schools.com/jsref/jsref_parse.asp
Please note that the parse method is very lenient and may allow poorly formatted dates
to be entered. If you need stricter control you should use the custom validator.
Parameters:
options
Includes all optional properties applied to all validators
Example:
HTML:
[[Date]]
Advanced Script:
spec['Date'].date();
14. range([options])
Requires the entered value, when parsed to an integer, fall within the range specific by
the min and max options.
Parameters:
options
Includes all optional properties applied to all validators
Example:
HTML:
[[Total]]
Advanced Script:
spec['Total'].range({ min: 5, max: 500 });
Additional Reference Material

JavaScript Reference – Complete reference of all JavaScript objects, along with
their methods and properties – http://www.w3schools.com/jsref/default.asp.
Customer Service & Support
Questions should be directed to Four51’s help desk.

Online Resource Center: http://myaccess.four51.com

Telephone: 952.294.0451
Four51 Spec Form API User Guide
25