JavascriptEvents
GMSC 2013/2014 Javascript API | Overview • Form • Events • Types • Utility Functions • client-side Validation • Conditions • Interaction with SmartClient • Cookbook • Cheatsheet |
Contents
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": {} } }); */