JavascriptEvents

The IG.vent Event Aggregator

IG.vent is the global Event Aggregator of the IGForm Javascript API. It simplifies the application-wide subscribing and emitting of events, as one doesn't need to wait until a specific object is available (e.g. Form, Tab, Group, Field) in order to subscribe to its events. The subscription is instead done via the global IG.vent object and namespaced events. To know more about this concept, read Martin Fowler's article on Event Aggregators

IG.vent.on()

IG.vent.on() is used to subscribe to events.

Parameters

String event event identifier(s) (either a single event or a space-separated list of events)

Function callback function that is invoked when the event is triggered. The parameters of this function are defined by the event.

Example

subscribe to individual and multiple events

var visibilityChanged = function (item){
   console.log('visibility of form item ' + item.id() + ' has changed');
}
 
 
//just react on visibility changed of fields
IG.vent.on('field:visible:change', visibilityChanged);
//also react on visibility changed of groups and tabs
IG.vent.on('group:visible:change tab:visible:change', visibilityChanged);

IG.vent.off()

IG.vent.off() is used to unsubscribe from events.

Parameters

String event event identifier(s) (either a single event or a space-separated list of events) that should be unsubscribed from.

Function callback (optional) callback function that should be unsubcribed. If no callback function is provided, all callbacks attached to the given event identifier will be unsubscribed.

Example

subscribe and unsubscribe multiple callbacks:

var mycallback = function (form){
   alert("form has been initialized - callback 1");
}
 
var mycallback2 = function (form){
   alert("form has been initialized - callback 2");
}
 
IG.vent.on('form:ready', mycallback);
IG.vent.on('form:ready', mycallback2);
 
//just unsubscribe the first callback
IG.vent.off('form:ready', mycallback);
//unsubscribe all callbacks attached to 'form:ready' - no alert message should be shown when the form is initialized
IG.vent.off('form:ready');

IG.vent.trigger()

triggers an event, i.e. invokes all callbacks listening to this event.

Parameters

String event event identifier (the name of the triggered event, should not contain spaces, namespacing can be achieved by using : as separator )

Arguments callback arguments arguments that will be passed to the event callback when it is invoked

Example

trigger a custom event after a randomly chosen timeout.

var randomTimeout = Math.round(Math.random()*1000);
IG.vent.on('custom:after:pause',function(timeout){
   console.log("this event was triggered after a pause of "  timeout + " milliseconds");
});
 
window.setTimeout(function(){
  IG.vent.trigger('custom:after:pause', randomTimeout);
},randomTimeout);

Form Events

form:ready

---

this event is triggered when the form has been initialized. Use it as a hook for custom scripts that manipulate the current form (e.g. hiding fields, attaching event handlers,...)

Callback Parameters

{FormModel} form instance of the current form.

Example

Alert the number of form items after the form has been initialized:

IG.vent.on('form:ready', function(form){
   alert("Form has been initialized with " + form.getItems().length + " items");
});

form:before:bind

---

this event is triggered before the form bindings are applied, i.e. the programmatic form model is bound to the UI components visible on the screen. Subscribe to this event if you want to modifiy the bindings on the client side.

Callback Parameters

{FormModel} form instance of the current form.

Example

Remove the visible binding of TestField1:

IG.vent.on('form:before:bind', function(form){
   var testFieldBindings = form.getItemsById('TestField1').getBindings();
   testFieldBindings.remove('visible');
});

form:visible:change

this event is triggered when the visibility of the form changes.

Callback Parameters

{Object} eventObject An object holding the context of the event. Structure: { item: {form}, value: {changedVisibilityValue}}

Example

alert a message when the form changes its visibility

IG.vent.on('form:visible:change', function(event){
   alert(event.item.id() + 'has changed its visibility');
});

form:editable:change

this event is triggered when the form is disabled or enabled.

Callback Parameters

{Object} eventObject An object holding the context of the event. Structure: { item: {form}, value: {changedEditableValue}}

Example

alert a message when the form changes its visibility

IG.vent.on('form:editable:change', function(event){
   alert(event.item.id() + 'has changed its editable status');
});

Tab Events

tab:visible:change

this event is triggered when the visibility of the tab changes.

Callback Parameters

{Object} eventObject An object holding the context of the event. Structure: { item: {tab}, value: {changedVisibilityValue}}

Example

alert a message when the form changes its visibility

IG.vent.on('tab:visible:change', function(event){
   alert(event.item.id() + 'has changed its visibility');
});

tab:editable:change

this event is triggered when a form tab is enabled or disabled.

Callback Parameters

{Object} eventObject An object holding the context of the event. Structure: { item: {tab}, value: {changedVisibilityValue}}

Example

alert a message when the form changes its visibility

IG.vent.on('tab:editable:change', function(event){
   alert(event.item.id() + 'has changed its editable status');
});

Group Events

group:visible:change

this event is triggered when the visibility of a form group changes.

Callback Parameters

{Object} eventObject An object holding the context of the event. Structure: { item: {group}, value: {changedVisibilityValue}}

Example

alert a message when the form changes its visibility

IG.vent.on('group:visible:change', function(event){
   alert(event.item.id() + 'has changed its visibility');
});

group:editable:change

this event is triggered when the visibility of a form group changes.

Callback Parameters

{Object} eventObject An object holding the context of the event. Structure: { item: {group}, value: {changedVisibilityValue}}

Example

alert a message when the form changes its visibility

IG.vent.on('group:editable:change', function(event){
   alert(event.item.id() + 'has changed its editable status');
});

Field Events

field:visible:change

this event is triggered when the visibility of a form field changes.

Callback Parameters

{Object} eventObject An object holding the context of the event. Structure: { item: {tab}, value: {changedVisibilityValue}}

Example

alert a message when the field changes its visibility

IG.vent.on('field:visible:change', function(event){
   alert(event.item.id() + 'has changed its visibility');
});

field:editable:change

this event is triggered when the editable status of a form field changes.

Callback Parameters

{Object} eventObject An object holding the context of the event. Structure: { item: {tab}, value: {changedVisibilityValue}}

Example

alert a message when the field changes its editable status

IG.vent.on('field:visible:change', function(event){
   alert(event.item.id() + 'has changed its editable status');
});

Overview List Events

list:ready

triggered on Overview Lists when the list has been initialized

IG.vent.on('list:read', function(list){
   IG.notify('Overview List:' + list.name() + 'has been initialized !');
});

Smart Client Events

smartclient:ready

triggered in Smart Client-based Workflows when both Smart Client and the current workflow page have been initialized and are readdy for manipulation via custom scripts .

IG.vent.on('smartclient:ready', function (e){
   //e.smartClient - smartClient instance
   //e.form - reference to the form (if current page is a form)
   //e.list - reference to the list (if current page is a list)
   IG.notify('Form Name:' + e.form.name() + ', active Smart Client Feature ' + e.smartClient.getActiveFeature());
});

Dependency Events

dependency:resolved

this event is triggered when a dependency is resolved. callback parameter: the server response as JSON-Object.

IG.vent.trigger('dependency:resolved', data){
   //data.fields - fields[] containing the resolved fields
   /*field - {
        "datatype":"String",
        "value":1,
        "listofvalues":null,
        "required": true,
        "maxlength": null,
        "validation": null,
        "validationmessage": null,
        "isremotevalidation": false,
        "widget": "ComboBox",
        "actions": [],
        "name": "ZIPCODE",
        "label": "Zip code:",
        "editable": true,
        "visible": true,
        "scripts": {}
        }
      });
*/