app-frame-messages

Utility library to simplify communication between apps and iframes.

Install

$ npm install --save @grapes-agency/app-frame-messages

Getting Started

import { startListening } from '@grapes-agency/app-frame-messages';

startListening({
  onSession: session => {
    console.log('Session received', session);
  }
});

or

<script src="https://unpkg.com/@grapes-agency/app-frame-messages"></script>

Handlers

We support the following handlers:

onSession: contains the user session

{
    profile: {
      name: 'Jon' // Profile name
    },
    lang: 'enUS', // Language
    searchValue: '' // Search value
    ...
}

Set handlers

If you don't want to set handlers on startListening, simply use setHandlers:

import { setHandlers } from '@grapes-agency/app-frame-messages';

setHandlers({
  onSession: session => {
    console.log('Session received', session);
  }
});

Unset handlers

You can unset handlers with unsetHandlers. It expect an array of the handler names.

import { unsetHandlers } from '@grapes-agency/app-frame-messages';

unsetHandlers(['onSession']);

Stop listening

If you want to unsubscribe, use stopListening.

import { stopListening } from '@grapes-agency/app-frame-messages';

stopListening();

Change parent source

Use openDetails to tell the parent to change the view. A common use case is, when this window displays an preview in a small window and requests a detail view a bigger window. The parent can change the size of the window and change the source.

import { openDetails } from '@grapes-agency/app-frame-messages';

openDetails('https://example.com/details');

Set breadcrumbs

Use setBreadcrumbs to tell the parent to change the breadcrumbs (for example when you go deeper in you pages). The methode expects and array of breadcrumb-elements. Every element in array can have maximum 1 children array which will be opened in a popup when you click on the specific element.

import { setBreadcrumbs } from '@grapes-agency/app-frame-messages';

const breadcrumbs = [
  {
    label: 'Home',
    url: '#'
  },
  {
    label: 'Level 2',
    url: '#',
    children: [
      {
        label: 'Children 2-1',
        url: '#'
      },
      {
        label: 'Children 2-2',
        url: '#'
      }
    ]
  },
  {
    label: 'Level 3',
    url: '#'
  }
];

setBreadcrumbs(breadcrumbs);

Check if the application is inside an iframe

You can call inIframe to find out if the application is within an iframe or not. This is useful, if you want to have different behaivours.

import { inIframe } from '@grapes-agency/app-frame-messages';

const isInIframe = inIframe();

Issues

parent/window is not defined

This module needs access to window and parent.window which is not available on server side. To prevent access issues, call startListening only on client side.

React example:

import React from 'react';
import { startListening } from '@grapes-agency/app-frame-messages';

class SomeComponent extends React.Component {
  state = {
    session: null
  };

  componentDidMount() {
    // componentDidMount is not called on server side
    startListening({
      onSession: this.handleSessionChange
    });
  }

  handleSessionChange = session => {
    this.setState({
      session
    });
  };

  render() {
    return <div>{JSON.stringify(this.state.session)}</div>;
  }
}