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.
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.
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.
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 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.
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.
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.
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/*):
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.
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");
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.
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)___-____
*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.
ICNumericMask specific attributes
Attribute
Description
decimalSeparator
The sign used to separate the decimal. The default is ".".
thousandsSeparator
The sign used to separate thousands. The default is ",".
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
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.)
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)
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.
<!--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>
<!--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>
Working with the IC Suite in Debug mode ICSuite-2.x.x-custom-settings.js file contains the following setting:
IC.Log.setShowOnError(true); //recommended for development
IC.Log.setShowOnWarn(false); //default value
IC.Log.setShowOnInfo(false); //default value
It means that by default, if ICSuite detects en error in its configuration it will open a pop-up browser window with
the log console with errors, warnings and info messages if there are some.
By default only an error level message opens a window, however, you are free to change this. During development we recommend
enabling error and warning levels. In production all three parameters should be set to false to avoid unexpected collisions.
Nevertheless, you can open the log console at any time by typing in the address bar of your browse the following URL:
javascript:void(ICOpen.Log.show())
Integration with DHTML, JavaScript and AJAX/Web 2.0 applications.
ICSuite is based on runtime DOM instrumentation technique. Once the page is loaded, ICSuite
determines the controls to instrument and enhances them. Form controls are
usually recognized by "class" or "id" attributes, according to pre-defined settings.
During the enhancement, ICSuite attaches specific event handlers to the original objects and
occasionally modifies DOM.
This technique allows achieving maximum flexibility and compatibility with server-side technologies.
It does not really matter what platform, framework or language was used on the server-side, because ICSuite
operated the (x)HTML received by a browser. Once this (x)HTML is parsed, ICSuite becomes active and upgrades the chosen HTML controls.
Post-back problem and dynamic changes on the client side
An interesting compatibility issue appears on form submission. For instance ICNumericMask allows any number format
including locale specific decimal and thousands separator characters. However, server expects a
classical number format: no thousands delimiter and a dot as a decimal separator. ICSuite keeps up
to date an hidden field with its value unmasked as required by the server. This hidden field keeps the original name that has been given by the developper.
Consider an example of a web application using a text field named "income". During instrumentation ICSuite hides
this text field (to store the value in compatible format) and creates a new input field with
user friendly formatting. You understand that any changes done directly to the control "income" via Javascript are applied to the hidden field and not to the visible one.
For example if your application changes the property readonly of the text field "income", it will have no effect, as income is not visible.
ICSuite dynamically attaches a "getFacade()" method to each instrumented field. This method returns the facade,
the visible field.
So, instead of
myForm.income.readonly=true
you should call
myForm.income.getFacade().readonly=true
When does ICSuite generate an hidden field
ICNumericMask
ICSuite generates an hidden field when postBackUnmasked is set to true or ifEmpty. The default is true.
ICTextMask
ICSuite generates an hidden field when postBackUnmasked is set to true or ifEmpty. The default is ifEmpty.
ICDateTimeMask
ICSuite generates an hidden field when postBackUnmasked is set to true or ifEmpty. The default is ifEmpty.
If your application sets a new value to an input field that is hidden by ICSuite you must call one of these two functions.
Always use these functions when coding JavaScript with Input Components Suite
getFacade()
This function is used to get the visible input field that is decorated by ICSuite.
setValue(value)
This function is used to modifiy the value of an input field that is decorated by ICsuite. Always call setValue instead of using .value property. Otherwise you will update the hidden field and you won't see the change on the screen. This function updates both visible and hidden field at the same time.
valueUpdated()
The function should be used when an input field value has been modified by a framework or anything else that is out of control by the programmer. Use this function to tell ICSuite to refresh the visible field cause the hidden one has been updated somehow.
Examples
myForm.myfield.setValue(...); or myForm.myfield.getFacade().value=...;
myForm.myfield.getFacade().valueUpdated();
//Example
function button1_onclick() {
//myForm.myField.value="987654321"; //Will update the hidden field only.
//The call bellow will update both hidden and visible fields. myForm.myField.setValue(987654321); }
If you'd like to keep your web application operational with and without ICSuite, do something like the following:
DOM manipulations with JavaScript
AJAX/WEB2.0 applications also take advantage of DOM manipulation without reloading the page. Such manipulation
may result in dynamically created form controls: input fields, text areas, etc.. Modern client side scripting
standards does not provide a reliable way to be informed of the DOM change. Therefore ICSuite must be explicitly
informed of such change in order to instrument newly added elements by calling the process method without
parameters.