Compatible with all technologies
Live examples
Input Components Suite Users Guide Advanced
Last Updated
27 April, 2007

Index


Integration with DHTML, JavaScript and AJAX/Web 2.0 applications
Supported event onMethod
How to create your own mask definitions
Developping with IC Suite: Debug mode

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:
(myControl.getFacade?myControl.getFacade():myControl).myProperty = ... 

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.
IC.MasterDecorator.process();

Supported event onMethod.

You will find bellow the list of onMethod supported by Input Components Suite. It is supporting all onMethods available.

onAbort onActivate onAfterPrint onAfterUpdate
onBeforeActivate onBeforeCopy onBeforeCut onBeforeDeactivate
onBeforeEditFocus onBeforePaste onBeforePrint onBeforeUnload
onBeforeUpdate onBlur onBounce onCellChange
onChange onClick onContextMenu onControlSelect
onCopy onCut onDataAvailable onDatasetChange
onDatasetComplete onDblClick onDeactivate onDrag
onDragEnd onDragEnter onDragLeave onDragOver
onDragStart onDrop onError onErrorUpdate
onFilterChange onFinish onFocus onFocusIn
onFocusOut onHelp onKeyDown onKeyPress
onKeyUp onLayoutComplete onLoad onLoseCapture
onMouseDown onMouseEnter onMouseLeave onMouseMove
onMouseOut onMouseOver onMouseUp onMouseWheel
onMove onMoveEnd onMoveStart onPaste
onPropertyChange onReadyStateChange onReset onResize
onResizeEnd onResizeStart onRowEnter onRowExit
onRowsDelete onRowsInserted onScroll onSelect
onSelectionChange onSelectStart onStart onSubmit
onTimeError onUnload    

Note. The onChange event is fired by the browser when data is changed by a user and the element looses its focus. However, onChange is NOT fired when the form element value is changed programmically, by JavaScript for instance. Once instrumented with WiseBlocks, many other ways to change the value appears. Naturally, these changes are performed by JavaScript, not the user. In this case "onChange" is not fired by the browser and that can cause a serious inconsistency for the web application. To solve this problem, WiseBlocks simulates "onChange" event every time a changed input field looses its focus.

How to create your own mask definitions.

//You first define your mask as a standard mask.

{ className : "timeMask",
type : "text/mask",
align : "center",
// Use 0 to fill blank spaces. Hitting del or backspace will reset the current digit to 0 in that case. blankCharacter : "0",
//Define custom mask caracters with regular expressions.
For more information about the JavaScript Regular Expressions.

maskDefinitions : {
H : /[\s0-2]/, // space or 0-2
M : /[0-5]/ // 0-5
},
//Create you masks with the letters or the signs that you want to redefine.
mask : "H#:M#",
//Provide an error message or an explication text for each redefined caracters.
//It your application needs to be internationalized,
//you can indicate "keys" and then provide translations using //IC.Dictionary.addTranslation().  These messages (or their translations) will be shown as a
//tooltip every time users type a wrong character.

maskErrors : {
H : "hourValueExpected",
M : "minuteValueExpected"
},
//(optional) Define some conditions. Any javascript code can be used.
conditions :[{
condition: function (value) {
return parseInt(value.substring(0, 2)) > 23
}, //CSS-like style definition that will be applied if the condition function returns true.
//In this case : make the text red if hour value is greater then 23.
style : { color:"red" } } ,{
condition: function (value) {
return value == "00:00"
},
style : { color:"#DDDDDD" } //Just another sample condition: text is grey for the initial "00:00" value. }] }

//Add text messages for the language that you want to cover. 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");

Working with Input Components 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())

Input Components Suite Debugger
ICS Debugger
 


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