Compatible with all technologies
Live examples
Input Components Suite Users Guide
Last Update
13 August , 2007

Index

Input Components Suite API

How to create my own mask definitions Language, Internationalization and character encoding.

Working with the IC Suite Javascript API

Before reading the following please be sure that you have read the installation et the quick start documentation sections.

It is important to know that the Input Components Suite is based on JavaScript. JavaScript must be enabled on your browser in order to use the product. This user guide will give you all information needed to maximize the uses of Input Components Suite. We suggest ICSuite-2.x-custom-setting.js file to store customized configuration and to import this script on every page along with ICSuite-2.x.js. Attention. Do not modify ICSuite-2.x.js otherwise you risk to lose these modifications following a product version upgrade.



Object definition and control binding

A defintion is a JavaScript object containing ICSuite configuration. This configuration information is later used by ICSuite for input controls instrumentation.

Example
{className      : "IC_Txt_US_ZipCode",
type            : "text/mask",
mask            : "@#@ #@#",
caseFormatters  : "+++++++",
blankCharacter  : "_"}

Definition-to-control binding can be done either by className (class property of input tag) or id. Both options are supported to provide a better flexibility for ICSuite integration with existing web applications/frameworks.

In case of className binding, a form control can use several definitions at the same time. In this case, definition objects are merged in runtime by ICSuite core. We consider the possibility of mixing custom and default definitions an important time saving feature.

Examples
<input type=text class="IC_Deco_Blue  IC_Txt_US_ZipCode">
Result:

<input type=text class="IC_Deco_Purple  IC_Num">
Result:

In the next sections you will learn how to create advanced definitions and how to apply these definitions to your web pages.

IC.MasterDecorator object (See ICSuite-2.x-custom-setting.js for a better understanding.)
Function Description
IC.MasterDecorator IC.MasterDecorator is the main object of IC Suite. It is through it that you manage the behavious of the product.
IC.MasterDecorator.
acceptLicense(license)
You must provide a valid license to use Input Components Suite on a domain name different other than localhost. You can get a 90 days trial license in My Account section.

Example
IC.MasterDecorator.acceptLicense(
    "WiseBlocks@wiseblocks.com"+
    "@localhost/v.1.0.3:2099-01-01#67680d79");
For additional details on the rights and limitations of each license type, please refer to our complete End User License Agreement
IC.MasterDecorator.
setNoLicenseMessage(message)

Define your own message when the library is used without a valid license. By the default the message entered in ICSuite-1.0.8-custom-settings.js is WiseBlocks ICSuite license is not present.

IC.MasterDecorator.
setShowNoLicenseMessage(boolean)
IC Suite is looking for a valid license when it is enhancing the input fields. If the license is not valid a message box is triggered to warn the developper. Use this function regardless of whether you want to see this message. The default value is true.
Example
IC.MasterDecorator.setNoLicenseMessage
("WiseBlocks ICSuite license is not present");
IC.MasterDecorator.setShowNoLicenseMessage(true);
IC.MasterDecorator.
setImagePath(imagePath)
Sets the absolute or relative path to WiseBlocks resources directory. All images used by the product (mainly for the Calculator and the Spinner) are under the directory WiseBlocks_ressources/img in the ZIP file. You must specify to the IC.MasterDecorator where are these images in your HTTP server.

Example
IC.MasterDecorator.
setImagesPath("myApp/WiseBlocks_resources/img");
IC.MasterDecorator.
setGlobals(attributes)

It sets global definition for the current page. You call this function to set global properties to all components in your application. You can call the function several times for the same page without losing prior setting, the properties are stacked.

Example
IC.MasterDecorator.setGlobals({
    conditions : [NegativeRed],
    highlight : HighlightBox.ORANGE
    });
                
IC.MasterDecorator.
setHighlightAll(value)
If value is true, "highlight" attribute of IC.MasterDecorator.setGlobals() will be applied to all <input>, <textare>, <select> tags on the page. This function is especially useful for third party libraries integration, where "class" and "id" attributes are out of control of application developers.
Default value is true.
Example
IC.MasterDecorator.setGlobals
(highlight:HighlightBox.GREEN);
IC.MasterDecorator.setHighlightAll(true);
                
IC.MasterDecorator.
process(definition)

This is the key function that generates the masks. You are able to pass an array of definitions for your custom class definition.

Example
var definitions = [
	{
		className : "input",
		highlight : HighlightBox.ORANGE
	},{
		id : "estimatedTax",
		type : "numeric/formula",
		formula : function (){
			return IC.sum("inc1","inc2")*30/100
		}
	}];

IC.MasterDecorator.process(definitions);
        



IC.Dictionary object
Function Description
IC.Dictionary This object is used to manage the messages shown by ICSuite. See Language, Internationalization and character encoding for more informations.
IC.Dictionary.
addTranslation(key,message)
Defines a message for a given key.

Example
IC.Dictionary.addTranslation("hourValueExpected",
"The first digit must contain 0,1 or 2 or stay empty");
IC.Dictionary.addTranslation("FR_hourValueExpected", "La première position des heures doit être 0,1,2 ou rester vide");

IC.Dictionary.
getLanguage
()
Returns the current language. By default ICSuite uses the browser language.

Example
language = IC.Dictionary.getLanguage();
IC.Dictionary.
setLanguage(language)
Sets the language. By default ICSuite uses the browser language. Don't forget to add the translations if the messages are not already there.

Example
IC.Dictionary.setLanguage("FR");

IC.Dictionary.addTranslation("FR_hourValueExpected", "La première position des heures doit être 0,1,2 ou rester vide");


How to create my own mask definitions

Common attributes
Attribute Description
className String used to reference the mask.
id String used to reference the mask. Mainly use with framework that are generating IDs.
Either className or id is mandatory, but not both of them.
type Used to define the ICSuite component
;
text/mask : ICTextMask component
dateTime/mask : ICDateTimeMask component
dateTime/calendar : ICDatetimeMask component with a calendar
dateTime/calendar/spinner : ICDatetimeMask component with both calendar and spinner
numeric/mask : ICNumericMask component
numeric/calc : ICNumericMask component with a calculator
numeric/spinner : ICNumericMask component with a spinner
numeric/calc/spinner : ICNumericMask component with both spinner and calc
numeric/formula : ICFormulaCell component
mask Mask definition. Check pre-defined masks for more examples. More information on custom masks creation is available here.

Character set for text masks (type=text/mask):
# Numeric digits (0-9)
@ Alphabetic characters (a-z, A-Z)
! Any punctuation character
* Any character
custom maskDefintion character User specified character set. See maskDefinitions property for more details.
Other Fixed in the mask
N.B. Click here to customize and test your custom text mask.

Character set for dateTime masks (type=dateTime/*):
D 2 digits for days (1-31)
DD 2 digits for days (1-31)
M 2 digits for months (1-12)
MM 2 digits for months (1-12)
Y 4 digits for years
YYYY 4 digits for years
YY 2 digits for years - In the current century.
hh 2 digits for hours (0-23)
mm 2 digits for minutes (0-59)
ss 2 digits for seconds (0-59)
A\\M AM or PM for 12 hours system
a\\m am or pm for 12 hours system
Other Fixed in the mask

Character set for numeric masks (type=numeric/*):
# empty space or a numeric digit (0-9)
0 forced numeric digit (0-9); 0 if empty
. Decimal separator character. See ICNumericMask specific properties.
, Thousands separator character. See ICNumericMask specific properties.
Other Not alowed


Dependent Mask:
dependsOn

You could dynamically change the mask of an input field depending on the value of another input field. In this example, a dropdown list is used to define the current mask.

<input type=text id=ammount>
<select name="currency">
<option>USD</option>
<option>EUR</option>
<option>YEN</option>
<option value="XAU">XAU (Gold Ounces)</option>
</select>

    IC.MasterDecorator.process({
        id:"ammount",
        type:"numeric/calc",
        mask :{
                dependsOn : "currency",
                USD : "###,###,###,###,##0.00",
                EUR : "###,###,###,###,##0.00",
                YEN : "###,###,###,###,##0",
                XAU : "###,###,###,###,##0.00000"
        }
    });
Result:


   

maskDefinitions Only needed for custom masks. Used to redefine masks character set.

Time mask Example
H : /[\s0-2]/ Redefinition of H. Allow to type space and number between 0 and 2 included.
M : /[0-5]/ Redifinition of M. Only allow to type number between 0 and 5.

See "creating custom text mask" for detailled explanation.
maskErrors Only needed for custom masks. Used to declare errors messages for custom mask.

Time mask Example
H : "hourValueExpected",
M : "minuteValueExpected"
Constant that will be used as identifier to get and show the message when the user has not typed an accepted value.

For custom mask redifinition you have to use the API to set your messages.
IC.Dictionary.addTranslation("hourValueExpected", "The first digit must contain 0, 1 or 2 or stay empty");
IC.Dictionary.addTranslation("minuteValueExpected", "The first munite digit must be between 0 and 5");

See "creating custom text mask" for detailed explanation.
conditions Predefined conditions are available
[NegativeRed] Will automatically set the input fields text color to red on negative value.

You can also define your own conditions. Here are the codification for the custom time.

Time example.
condition: function(value) {
  return parseInt(value.substring(0, 2)) > 23
},
style : { color:"red" }
Check if the value H is greater than 23. If that is the case the text become red and the message is shown.

See "Creating custom text mask" for detailled explanation.
cursorOnFocus Determine the cursor behavious

selectAll : All data in the input field is selected.
begin : The cursor is always positioned at the beginning of the field.
end : The cursor is always positioned at the end of the field.
firstEmpty (for text masks only) : If empty the cursor goes at the beginning otherwhise where the click has been done.
beforeDecimal (for numeric masks only) :

If empty or completed the cursor goes to the beginning otherwise it is positioned at the end of the uncompleted entry.

autoSize
true (default) : Will automatically set the size of the input field based on its mask. It overwrites "size" attribute of the input tag. CSS width parameter is not overwritten.
false : Deactivate the autoSize function.
align
center : Align the text in the center of the input field.
left : Align the text to the left of the input field.
right : Align the text ot the right of the input field.
borderStyle

specifies default css border style to be applied for an element instrumented with IC Suite.

  • Can be applied at global level, per class or per id.
  • Can contain any compatible value for CSS "border" parameter.
  • Set an empty string to use existing border style defined in your web page.
Examples
borderStyle : "1px dotted #8899AA"
borderStyle : "" /* To use the default one in the web page. */

IC.MasterDecorator.setGlobals({
borderStyle : "3px double black"
});
highlight
Used to define the color that will surround the input field. The default is GREEN.

[ "#8899AA",
"#AABBFF",
"#DDEEFF" ]
Example of custom color. To give a nice effect, you should use three shades of the same color. The first one being the darkest and the third one the palest.
HighlightBox.NONE
HighlightBox.BLACK
HighlightBox.BLUE
HighlightBox.BROWN
HighlightBox.GRAY
HighlightBox.GREEN
HighlightBox.PINK
HighlightBox.PURPLE
HighlightBox.RED
HighlightBox.WHITE
HighlightBox.YELLOW
HighlightBox.ORANGE
Predefined constants ready to use. NONE if you want to avoid any highlight box. The default is GREEN.

See ICDecorator for more examples.
postBackUnmasked Used to define how the data will be sent back to the server.
true : Send back only data to the server. For example, (123)456-7890 will become 1234567890 on the server side.

Client side
(123)456-7890
(___)___-____
(123)___-____

Server side
1234567890
[EMPTY]

123
false (default): Send back masked data.

Client side
(123)456-7890
(___)___-____
(123)___-____

Server side
(123)456-7890
(___)___-____
(123)___-____
ifEmpty : Send back masked data only if there is data in the field.

Client side
(123)456-7890
(___)___-____
(123)___-____

Server side
(123)456-7890
[EMPTY]
(123)___-____
withblankchars:

Removes all non editable mask characters and keeps blankCharacter in place. For instance 01:15:00 becomes 011500.


*IMPORTANT. ICSuite generates a hidden field when postBackUnmasked is set to true or ifEmpty. It may cause problems for those who are coding with DHTML and JavaScript.
Read this section for more information. Integration with DHTML, JavaScript and AJAX/Web 2.0 applications

How data coming from the server is managed by ICTextMask.
It detects if the data from the server is either masked or not and automatically analyses what to do. For example with this mask (**)**-** you will have always the same information on the client even if the data on the server side is different.

Server -> Client with ICTextMask
123456 -> (12)34-56
(12)34-56 -> (12)34-56
12)3456 -> (12)34-56

This functionality is useful when the same data is used by several front-ends.


ICTextMask specific attributes
Attribute Description
mask Character set for text masks.
# Numeric digits (0-9)
@ Alphabetic characters (a-z, A-Z)
! Any punctuation character
* Any character
custom maskDefintion character User specified character set. See maskDefinitions property for more details.
Other Fixed in the mask
N.B. Click here to customize and test your custom text mask.
blankCharacter

Used to define the caracters that will tell the user that there is something to type. You can define one to many caracters. For instance you can set "mm/dd/yyyy" for a dateTime input field.
The default is "_".

caseFormatters Used to force upper of lower cases.
+: force upper case at this position
-: force lower case at this position
space: case not forced at this position

Example "+---" will give "Aaaa"


ICDatetimeMask specific attributes
Attribute Description
Mask Character set for dateTime masks.
d 2 digits for days (1-31)
dd 2 digits for days (1-31)
M 2 digits for months (1-12)
MM 2 digits for months (1-12)
Y 4 digits for years
YYYY 4 digits for years
YY 2 digits for years - In the current century.
hh 2 digits for hours (0-23)
mm 2 digits for minutes (0-59)
ss 2 digits for seconds (0-59)
A\\M AM or PM for 12 hours system
a\\m am or pm for 12 hours system
Other Fixed in the mask
postBackDateFormat Used to define how the data will come or sent back to the server. ICSuite will automatically transfrom data. This property is mainly used to apply masks on data from databases.

In this example the data visible on the form can be 06/30/2010 while the data sent to the form is 2010-06-30 12:56:45
className : "CUSTOM_postBackExample",
type:"dateTime/mask",
mask:"MM/dd/yyyy",
postBackDateFormat:"y-M-d h:m:s" 


ICCalendar specific attributes
Attribute Description
calendarTemplate
It is the default. You don't have to define the calendarTemplate attribute to use it . Standard Calendar
CSS based template. You can modify the CSS to respond your needs.
See How I can change the look of my calendar?

This is the default template.
"WiseBlocksCalendar" Wiseblocks Calendar
This is the template that we have created for WiseBlocks web site.
compactDropDown
true : Hide the upper part part of the calendar. See the images bellow and compare the header.
Example with header with icons.
Calendar with an header
Example with no header.
Calendar with no header

false (default) : Show the upper part of the calendar.
calendarOptions calendarOptions properties
Property name Type Default Description
maxdate String
/Date
null Sets the Calendar's maximum selectable date, either in the form of a Javascript Date object, or a string date (e.g. "4/12/2007").
mindate String
/Date
null Sets the Calendar's minimum selectable date, either in the form of a Javascript Date object, or a string date (e.g. "4/12/2007").
SHOW_WEEKDAYS Boolean true Determines whether to display the weekday headers
LOCALE_MONTHS String "long" The format of the month title to be displayed. Possible values are "short", "medium", and "long".
LOCALE_WEEKDAYS String "short" The format of the weekday title to be displayed. Possible values are "1char", "short", "medium", and "long".
START_WEEKDAY Integer 0 0-6, representing the day that a week begins on
SHOW_WEEK_HEADER Boolean false Determines whether to display row headers
SHOW_WEEK_FOOTER Boolean false Determines whether to display row footers
HIDE_BLANK_WEEKS Boolean false Determines whether to hide extra weeks that are completely outside the current month
MONTHS_SHORT Array English 3-letter month names

default:["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
MONTHS_LONG Array English Full month names

default:["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]
WEEKDAYS_1CHAR Array English Single letter weekday names

default:["S", "M", "T", "W", "T", "F", "S"]
WEEKDAYS_SHORT Array English 2-letter weekday names

default: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
WEEKDAYS_MEDIUM Array English 3-letter weekday names

default: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
WEEKDAYS_LONG Array English Full weekday names

default: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]

Example
calendarOptions:{
      START_WEEKDAY : 1,
      SHOW_WEEKDAYS : false,
      SHOW_WEEK_HEADER : false,
      SHOW_WEEK_FOOTER : false,
      HIDE_BLANK_WEEKS : true,
      LOCALE_MONTHS : "short"}
clickToClose Determine how the calendar is closed.
true : The calendar closes automaticaly with a single click.
customCalendarHelpFunction Used to customize the "?" icons. Set it to null to make the icon disapear or give any JavaScript code to be executed.

Example
customCalendarHelpFunction: {function(){
                alert("Help online! ")}} 

You can use this method with the setGlobal function.

Example
IC.MasterDecorator.setGlobals({customCalendarHelpFunction:...}) 



ICNumericMask specific attributes
Attribute Description
mask Character set for numeric masks.
# empty space or a numeric digit (0-9)
0 forced numeric digit (0-9); 0 if empty
. Decimal separator character. See ICNumericMask specific properties.
, Thousands separator character. See ICNumericMask specific properties.
Other Not alowed
decimalSeparator The sign used to separate the decimal. The default is ".".
thousandsSeparator The sign used to separate thousands. The default is ",".


ICCalculator and ICOpenCalculator specific attributes
Attribute Description
calcTemplate

It is the default. You don't have to define the calcTemplate attribute to get this one.
Standard Calulator
CSS based template. You can modify the CSS to respond your needs.
See How I can change the look of my calculator?


This is the default template.

"Wiseblocks"

 

CSSWiseBlocks
This is the template that we have created for WiseBlocks web site.
customCalcHelpFunction Used to customize the "?" icons. Set it to null to make the icon disapear or give any JavaScript code to be executed.

Example
customCalHelpFunction: {function(){
                alert("Help online! ")}} 

You can use this method with the setGlobal function.

Example
IC.MasterDecorator.setGlobals({customCalcHelpFunction:...}) 

compactDropDown false (default) Show the upper right part of the calculator that contains the three icons,
true Hide the upper right part of the calculator that contains the three icons,


ICSpinner specific attributes
Attribute Description
spinStep Used to define the step of the The default is "1".
spinScale Indicates the distance of the spinner handle movement (in pixels) necessary for one step (increment/decrement). The default is "1".
spinMin Used to define the minimum value that the spinner could go. No default.
spinMax Used to define the maximum value that the spinner could go. No default.


ICFormulaCell specific attributes
Attribute Description
formula The ICFormulaCell component is used to to automatically calculate fields in a form.

Here are the predefined functions available
IC.sum(id1,id2, ..., idN) Returns the sum of all input fields.
IC.min(id1,id2, ..., idN) Returns the value of the smaller value of all input fields.
IC.max(id1,id2, ..., idN) Returns the biggest values of all input fields.
IC.avg(id1,id2, ..., idN) Returns the average of all input fields.
IC.intValue(id) Returns an integer.
IC.floatValue(id) Returns a float.
IC.stringValue(id) Returns a string.

You could also define your own functions.

Here are few examples:
formula : function (){ return IC.sum("input1","input2")*30/100 }
formula : function (){ returnIC.intValue("input1")*99.00)+35 }

See ICFormulaCell or ICExample_Spreadsheet.html for real examples.
formulaRefrehPeriod The fields are recalculated on every period defined. The default is "1".


ICDecorator
The decorator could be used with <input>, <select> and <textarea> components.
Attribute Description
highlight
Used to define the color that will surround the input field. The default is GREEN.

[ "#8899AA",
"#AABBFF",
"#DDEEFF" ]
Example of custom color. To give a nice effect, you should (3 dégradés d'une même couleur. La première étant la plus foncé et la dernière la plus pâle.)
HighlightBox.NONE
HighlightBox.BLACK
HighlightBox.BLUE
HighlightBox.BROWN
HighlightBox.GRAY
HighlightBox.GREEN
HighlightBox.PINK
HighlightBox.PURPLE
HighlightBox.RED
HighlightBox.WHITE
HighlightBox.YELLOW
HighlightBox.ORANGE
Predefined constants ready to use. NONE if you want to avoid any highlight box. The default is GREEN.

It is possible to apply ICDecorator to all your input fields without assigning a specific class name to all your components.
See IC.MasterDecorator.setHighlightAll(true)

Example
IC.MasterDecorator.setGlobals({ highlight : HighlightBox.GREEN });
IC.MasterDecorator.setHighlightAll(true);


Language, Internationalization and character encoding

You can modify or add new languages for all messages used by the product. The default language is english and the messages are embedded in the product by default. You don't have to import a specific file in that case. There is a simple system that allow you to either add a new language or modify the current english messages.

You will find these files beneath this directory: WiseBlocks_resources\js\languages
File name Description
en.js The default messages. Be aware of the consequences of modifying this file. Future version of ICSuite may override your changes. You should create a new file for your own modifications.
all-ISO-8859-1.js All messages used by ICSuite with the charset ISO-8859-1.
all-UTF-8.js All messages used by ICSuite with the charset UTF-8.
fr-ISO-8859-1.js French messages only with the charset ISO-8859-1.
fr-UTF-8.js French messages only with the charset UTF-8.
es-ISO-8859-1.js Spanish messages only with the charset ISO-8859-1.
es-UTF-8.js Spanish messages only with the charset UTF-8.

For other languages, create a new file and just put the country code before the message identifier. The language will be detected automatically and the good translation will be shown to the final users.

Example for a french
//default messages
IC.Dictionary.digitExpectedHere = "Digit expected here";
IC.Dictionary.alphaExpectedHere = "Alphabetic character expected here";
IC.Dictionary.digitOrDotExpectedHere = "Digit or decimal separator is expected here";
IC.Dictionary.punctuationExpectedHere = "Punctuation is expected here";


// translated messages
IC.Dictionary.FR_digitExpectedHere = "Veuillez saisir un chiffre";
IC.Dictionary.FR_alphaExpectedHere = "Veuillez saisir une lettre";
IC.Dictionary.FR_punctuationExpectedHere = "Veuillez saisir une signe de ponctuation";
IC.Dictionary.FR_digitOrDotExpectedHere = "Veuillez saisir un chiffre ou une virgule";
// For custom mask redifinition you have to use the API to set your messages.
IC.Dictionary.addTranslation("hourValueExpected", "The first digit must contain 0,1 or 2 or stay empty");
IC.Dictionary.addTranslation("minuteValueExpected", "The first munite digit must be between 0 and 5");
IC.Dictionary.addTranslation("FR_hourValueExpected", "Premiere chifre d'heurs doit être 0,1,2 ou rester vide");
IC.Dictionary.addTranslation("FR_minuteValueExpected", "Premiere chifre de minutes doit être entre 0 et 5");

*IMPORTANT. Don't forget to import the JavaScript language file in you HTML page. Depending of the charset that you use for your HTML page, import the good JavaScript File. See Dictionary API for complementary information.

Example with ISO charset.
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />

<!--Wiseblocks import - The JS files should be in the body section. -->
<script type="text/javascript"
src="[/path/]WiseBlocks_resources/js/languages/all-ISO-8859-1.js"></script>

Example with UTF-8 charset.
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<!--Wiseblocks import - The JS files should be in the body section. -->
<script type="text/javascript"
src="[/path/]WiseBlocks_resources/js/languages/fr-UTF-8.js"></script>
 


InputComponents are trademarks of WiseBlocks. Copyright 2007. All Rights Reserved.