remote-page-communication

JS library (npm dependency) that uses WebMessage API for communicating the editor (insta-theme) with the preview (the store itself). It's intended to be used with browserify.

Use

To add the library in another browserify project, just include it in the package.json file this way:

{
	...
	"dependencies": {
		...
		"tienda-nube-remote-page-communication": "https://github.com/TiendaNube/remote-page-communication/archive/v1.0.2.tar.gz",
		...
	}
	...
}

Note that you are also specifying the version.

Then (after npm install) you can include it in your code with the id "tienda-nube-remote-page-communication" this way:

var RemoteCommunication = require('tienda-nube-remote-page-communication');

API

Instantiation methods

The example asumes that you required the library into the RemoteCommunication variable.

Constructor

new RemmoteCommunication(DOMIframe target | window target [, string origin]) -> RemoteCommunication

The library can be instantiated as showed above. You must provide the target parameter and should provide the origin parameter:

• target: the page you want to communicate with. It can be an iframe DOM element (if you want to communicate with an iframe that's inside of your page) or window.top (if your page is contained into an iframe and you want to communicate with the top window).
• origin (optional): the allowed origin of the other window. For security reasons, if the other window's origin doesn't match the specified one, then the communication won't occur. Default is "*".

Examples:

var remoteWindow = new RemoteCommunication(document.getElementById('my-iframe'));

var remoteWindow = new RemoteCommunication(window.top, 'tiendanube.com');

Note: all the following examples asume that the variable remoteWindow refers to an instance of the library's constructor (of RemoteCommunication in the example above).

####.ready

.ready(function(RemoteCommunication remoteWindow) callback) -> RemoteCommunication

Attachs a callback that is called when the library is ready (after stablishing the communication with the remote window). The callback is called with a reference to the remote window instance. It returns itself to allow method chaining.

Example:

remoteWindow.ready(function() {
	console.log('The remote window is ready for sending and receiving messages.');
});

Basic messaging methods

####.send

.send(object message) -> RemoteCommunication

Sends the message to the remote window. You don't have to worry about serializing the message. It's serialized internally using the Structured clone algorithm. This method allows method chaining.

Example:

remoteWindow.send({
	foo: 'bar',
	baz: 5
});

####.onMessage

.onMessage(function(object message) callback) -> RemoteCommunication

Attachs a callback that will be called when the remote window sends a message. The callback is called with the message as first parameter. You don't have to worry about deserializing it, because it's deserialized internally using the Structured clone algorithm. This method allows method chaining.

Example:

remoteWindow.onMessage(function(message) {
	console.log('They sent the message', message);
});

Routing methods

The following methods are intended to provide a richer interface for communicating with the remote window

####.get

.get(string path[, object data], function(object data) callback) -> RemoteCommunication

The metaphor of this method is sending a request to a server (which will actually be the remote window). You send the request (with optional data) and specify a callback that will be called by on respose by the remote window.

This method accepts method chaining.

Example:

remote.get('colors', function(colors) {
	// Do magic with the colors that the remote window replied
});

####.post The post method is an alias of the get method.

Altough both methods accepts an optional data parameter, semantically it's expected that the get method will be used without the data parameter and the post method will be used with the data parameter.

Example:

remote.post('colors', ['black', 'white'], function(response) {
	if(response == 'ok') {
		// The remote window says that everything is ok! :)
	}
});

####.route

.route(string path, function(function(object responseMessageData) res, object data) callback) -> RemoteCommunication

The metaphor is setting a route of a REST server: the window will listen with the callback to requests (get or post methods) calls by the remote window on the specified path. The route method sets a "route" on the path parameter that calls the callback function. The callback function is called with two arguments:

• a res function that you can call to send a message to the remote window. It accepts an object parameter that you can send in response.
• optional data that the remote window can send when calling the post or get methods.

This method accepts method chaining.

Example:

remoteWindow.route('colors', function(res, data) {
	if(data) {
		// They sent data, they want to set the colours
		setColors(data);
		res('ok');
	}
	else {
		// They didn't send data, they are asking for the default colours
		res(['red', 'green', 'blue']);
	}
});