CIB webRec iframe can be controlled by commands from enclosing page. For this, library called please.js is used.

The library is available on GitHub (https://github.com/wingify/please.js) and is MIT-licensed. It also requires jQuery to be present.

Examples in this section assume that some initialization is run. Here we assume that CIB webRec frame is available by id #webRec

// initialize library in your frame 
please.init(window)
//
grab a handle to call methods on 
var frame = document.getElementById('webRec').contentWindow

 

Methods are called using please.call function:

please(frame).call('webRec.blockUI', true) 

If you’re using only one CIB webRec frame, it might be more convenient to set it as default target, so to omit an argument to please function:

please.defaults({targetWindow: frame}) // just once 

Allowing you to call a method this way:

please.call('webRec.blockUI', true)

This shorthand will be used in examples later.

All message passing to iframe is asynchronous. Please uses jQuery promises for it, so that a result should be processed using .then handler:

please.call('webRec.saveRTF').then(function (rtfString) { 
  console.log('We have saved RTF of length ' + rtfString.length) 
})

When an API method is said to return a value, calling it with please means that you will be given a promise which resolves to that value when the method is done. It is also not safe to call methods one after another without using .then and return

// WRONG! 
please.call('webRec.blockUI', true) 
please.call('webRec.insertRTF', someRTF) // was the UI blocked? It might be not 
please.call('webRec.blockUI', false) // was the RTF inserted? It might be not Page 8 of 15 
 
// RIGHT! 
please.call('webRec.blockUI', true 
).then(function() { 
return please.call('webRec.insertRTF', someRTF) // UI was blocked 
}).then(function() { 
return
})

 

Additional information on jQuery promises is available at its API documentation page: http://api.jquery.com/category/deferred-object/