@sparwelt/iframe-integration-boilerplate NPM

iframe-integration-boilerplate

This is a boilerplate you can use if you want to dynamically include an iframe to provide some kind of service or widget.

It mostly uses & integrates https://github.com/davidjbradshaw/iframe-resizer while adding some common functionality and easing usage for a number of usecases.

What does this do

allows you to provide a simple js client for your iframe based application that allows
- dynamic sizing
- easy passing of variables ( set variables are translated as get parameters )
- asynchronous initialization on both ends

Integration

Content Serving side - host.js

The side serving the content ( e.g. the one being integrated as iframe ) can simply use the dist/host.min.js file

<script>
  (function(w, d, s, i) {
    var js, cjs = d.getElementsByTagName(s)[0]; if (d.getElementById(i)) return;
    w.iih=w.iih||function(){(iih.q=iih.q||[]).push(arguments)};iih.l=+new Date;
    js = d.createElement(s); js.i = i; js.src = "http://example-serving-side.com/dist/host.min.js"; cjs.parentNode.insertBefore(js, cjs);
  }(window, document, 'script', 'iih'));
</script>

Methods

/**
 * returns the value of a given parmaeter apssed to the integration, if none can be found,
 * the fallback is returned
 * 
 * @var string   parameterName           name of a parameter
 * @var mixed    parameterValueFallback  fallback for the parameter value you wanna get
 * 
 * @return mixed
 */
get(parameterName, parameterValueFallback)

/**
 * returns object of url params
 * 
 * @return URLSearchParams 
 */
getParameters()

Properties

Integrating Side - client.js

The side integrating the iframe should load the dist/client.min.js provided here.

Usage

You can simply use the script as is and provide your custom information on initialization All Names and default values can be changed in the/with a custom app/client.js and by simply adapting the script below.

<your-integration-placement></your-integration-placement>
<script>
  (function(w, d, s, i) {
    var js, cjs = d.getElementsByTagName(s)[0]; if (d.getElementById(i)) return;
    w.iic=w.iic||function(){(iic.q=iic.q||[]).push(arguments)};iic.l=+new Date;
    js = d.createElement(s); js.i = i; js.src = "http://example-serving-side.com/dist/client.min.js"; cjs.parentNode.insertBefore(js, cjs);
  }(window, document, 'script', 'iic'));

  // we send some command to the client
  iic('render', [{
    'one_option': 'some_value',
    'another_option': 'another_value'
  }, {
    targetUrl: 'http://example-serving-side.com/your-iframe-source.html',
    localElementTagName: 'iframe-integration-placement'
  }]);

  // we get the client
  iic(function (client) {
    // we now have the client and can interact with it, no real functionality here as of now
  });
</script>

Methods

/**
* @var object parameters  list of parameters passed via get to the target page
* @var object settings    list of settings about the workings of the iframe, all those default values can be set so this is for overriding & testing
*                         - targetUrl           what base url to load in the iframe
*                         - localElementTagName css selector of the element to transform
*                         - width               with of the element - default 100%
*                         + all settings avaiabile for the internal iframe resizer
*                         @see https://github.com/davidjbradshaw/iframe-resizer#options
*/
render({parameters}, {settings});

Properties

/**
 * the iframe resize client itself for avaible methods see
 * @see https://github.com/davidjbradshaw/iframe-resizer#callback-methods
 */
iFrameResize

Events ( Host & Client )

/**
 * binds a listener (callback) to a given event
 *  
 * @var string   eventName  name of the event to be listened on
 * @var callback callback   callback that is triggered when event happens
 *                          - data    data send to the event
 *                          - name    name of the event ( same as eventName )
 *                          - iframe  iframe the event was send from
 **/
iic('on', [eventName, callback(data, name, iframe)])

/**
 * fires an event
 * 
 * @var string  eventName name of the event being emitted/fired
 * @var mixed   data send for the event
 **/
iic('emit', [eventName, data])

Example

  // on client side, use iih on host side  
  iic('on', ['value.changed', function (data, name, iframe) {
    console.log(data.content)
  }]);
  […]
  // on host side, use iic on client side
  iih('emit', ['value.changed', {content: 'some value'}])

Customize

To change the naming or preset your placement name & url simply modify the app/client.js file ( or create your own) and build the application.

How to build the app

Simply install all npm dependencies ( including dev dependencies ) and run build.

npm install
npm run build

if you want to use a different source client.js file

npm install
./node_modules/.bin/webpack app/your-client.js dist/client.js

npm install only needs to be run once of course.

Things to keep in mind / known limitations

event system currently does not support separation of multiple host iframes inside one client page (events are always send to all hosts)
both pages must use https or http - no mixing
the placement element ( iframe-integration-placement by default ) always needs to exist before the render method is called
the iframe resizing event is first fired after the host document finished loading, so optimize this page for an early Load event