postal.js add-on providing the ability to federate instances of postal across independent window boundaries
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
example
lib
spec
src
.editorconfig
.eslintrc
.gitignore
.jscsrc
README.md
component.json
gulpfile.js
index.html
karma.conf.js
karma.globals.js
package.json
webpack.config.js

README.md

postal.xwindow

Version 0.0.8 (Dual Licensed MIT & GPL)

What is it?

postal.xwindow is an add-on for postal.js that provides cross window communication capabilities using a localStoreage hack. A lot of code and boiler plate config is taken from postal.xframe.

What the difference to postal.xframe

postal.xframe needs a reference to the frame to function. There are scenarios where you don't have this reference:

  • separately opened windows of your application
  • opener reloaded, child still exists
  • window chain where some window in the middle of the chain got closed

How does it work?

postal.xwindow uses localStorage as a workaround to let separate windows communicate. The same would be possible with sharedWorkers but browser support is incomplete for it.

  • Each postal.xwindow instance has it's own target/key in localStorage postal.fedx.xwindow.
  • A target contains two keys message and targetTimeout.
  • Each postal.xwindow instance periodically updates its targetTimeout. A cleanup process tidys up the storage area from dead targets.
  • Each postal.xwindow posts its messages to all other targets message key.
  • Each postal.xwindow instance listens to the localStorage events for its own message key.

Run-time Dependencies

This is a postal add-on, so it's assumed that you have postal and lodash loaded already.

How do I use it?

  • see example
  • NOTE: postal.xwindow uses store2, but store2 can't be loaded by webpack yet. you need to mangage the include yourself.
  <script src="../node_modules/store2/dist/store2.js"></script>
  <script src="../node_modules/store2/src/store.bind.js"></script>
  • NOTE: as postal.xwindow uses localStorage you might need to take care of what you post and have popper cleanup.
// this instance of postal *MUST* have a unique identifier, otherwise
// there is no way to differentiate between this instance of postal
// and a remote instance. You can provide your own server-generated
// GUID, or - if you know a unique value ahead of time - you can set
// it via postal.instanceId(id). Calling postal.instanceId() without any
// arguments acts as a getter - it returns the current instance Id.
postal.instanceId("parent");

// You can optionally configure postal.xwindow with the configure call.
// `allowedOrigins` is an array of origins that you can use to determine
// if you want to federate with postal instances loaded in another window
// from those origins.  If another host attempts to federate with you from
// an origin not listed in that array, the local instance of postal will
// not allow it. The local instance of postal will not send any messages to
// (nor process any from) an origin not listed in this array.
postal.fedx.transports.xwindow.configure({
	allowedOrigins : [ "http://some.host.com", "http://another.com" ],
	enabled: true // this is redundant - just showing that it's here
});

Building, Running Tests

  • npm install to install dependencies
  • gulp test to build and run tests
  • gulp coverage to build, run tests and show an istanbul coverage report
  • gulp to build
  • gulp watch to start a file watch which builds as you save changes to the src/ files
  • npm start will start a local web server that lets you run browser-based tests or see a _very_simple example of multiple windows communicating.

TODO

  • cope/support origins?!
  • support rename of instance
  • write tests
  • implement cleanup on window close