Multiple Windows

The multiple windows feature makes it possible to display the same client concurrently in two or more browser windows. This allows users to see several views of the client at once, and to navigate each one separately.

This feature can be used to build a multi-monitor solution, since each browser window can be displayed on a different monitor. However, any additional functionality needed for a true multi-monitor solution, such as mapping a given window to a specific monitor, would have to be implemented directly in the client, and not through the PureWeb APIs.

 

The multiple windows feature is currently only available for HTML5 clients.

It works in all supported browsers for HTML5 clients; however, in Internet Explorer, performance is noticeably lower.

Implementation considerations

Parent-child relationship

In a multiple windows scenario, all client windows use the same channel to communicate with the service application. In other words, the PureWeb server and the service see all windows as belonging to a single client application. This creates a parent-child relationship between the first window (the client instance that is launched first), and each subsequent instance.

This has a few implications:

  • Child instances cannot create other child instances, all new windows must be created from the parent.
  • Terminating the parent window terminates all child windows.

A child window cannot reconnect after disconnecting. If a child window disconnects, close it and open a new one from the parent.

PureWeb features such as application state, collaboration, resource manager and session storage work the same as if the client were running in a single window, with the following few exceptions:

  • Commands: Only the window that originates a command will trigger the command response callback.
  • Views: There should only be one instance of a given view across all browser windows at a given time; having multiple instances of the same view may result in erratic behavior.

Performance

The intent of the multiple windows feature is to display different views of the same client in a small number of concurrent windows.

Because all client windows use the same channel to communicate with the service application, the greater the number of child windows, the greater the hit on performance.

Performance also depends on which browser is running the client; Internet Explorer in particular does not perform as well as the other browsers.

Performance degradation will vary for each application and environment. To determine an appropriate limit on the number of concurrent windows supported by your service, we recommend that you run tests for your own use case.

How-to

Launch a new window

APIs:

MultiWindow.createNewWindow() | HTML5

To launch a new window, you call the createNewWindow method from the MultiWindow class (this method also has a convenience wrapper on the Framework class).

This method accepts two parameters, both are optional:

  • specs: This parameter, if provided, will be passed to the JavaScript window.open method, and accepted values are the same as those expected by that method. For example, to ensure that child windows have a specific dimension, you would include the height and width in the specs parameter. For more information about the parameters accepted by the window.open method, refer to your favorite JavaScript reference, or click here.
  • passFlowControl: This parameter is used to indicate whether flow control should be driven by the new window. When set to true, it can help reduce perceived latency in view updates; this can prove especially useful when running the client in Internet Explorer.

In the snippet below, we set the size of the new window to 200 x 200, and pass flow control to this window:

HTML5

pureweb.getFramework().createNewWindow("height=200,width=200", true);

That's it. Communications between the windows and the service application, and between sibling windows, is all handled under the hood.

For any other functionality, such as resizing or closing windows once they are open, use JavaScript as you normally would.


Send messages between windows

APIs:

MultiWindow.sendMultiWindowMessage() | HTML5

It is possible for one window to send a message to another window, and trigger a response in the destination window through event handling. The same functionality can also be used to broadcast a message to all windows at once.

Send a message

To send messages, you use the sendMultiWindowMessage method. This method accepts two parameters:

  • message: The message to send to the other window, expressed as a string, for example "clear" or "exit".
  • destination: The unique name of the window that will receive the message; this is a GUID that can be obtained by calling getOpenWindows()[...].name. If no destination is specified, the message will be broadcast to all open windows (except the window from which the message originates).

HTML5

myclient.sendWindowMessage = function(){
    var ddlAllWindows = document.getElementById('ddlAllWindows');
    var selectedWindow = ddlAllWindows[ddlAllWindows.selectedIndex].text;
    var message = document.getElementById('txtWindowMessage').value;
    
    pureweb.getClient().getMultiWindow().sendMultiWindowMessage(message,selectedWindow);
}

Listen for the event

Whenever a window sends a message using sendMultiWindowMessage, this raises a MULTI_WINDOW_MESSAGE event. A handler can be chained to this event on the destination window, so that it can respond appropriately to the message.

In the snippet below, the event listener is set up to trigger a handler called "onMultiWindowMessage":

HTML5

pureweb.listen(pureweb.getClient().getMultiWindow(),
                pureweb.client.MultiWindow.EventType.MULTI_WINDOW_MESSAGE,
                myclient.onMultiWindowMessage);

Handle the event

You can define the event handler to respond to a message received from another window. For instance, you could send a message labeled "exit", and write a corresponding event handler that closes the destination window on receiving this message.

In the snippet below, the handler simply displays a message confirmation prompt.

HTML5

myclient.onMultiWindowMessage = function(e) { 
    console.log("Message received from: " + e.sender.source.name); 
    console.log("Message Content: " + e.message);
};

Implement parent-specific functionality

You may want to implement logic in your client so that it behaves differently when functioning as a child window. For example, since child windows cannot launch new instances of the client, you may want to hide the Add Window button when the window is a child.

To help with this, the HTML5 API provides the following methods:

  • pureweb.WebClient.MultiWindow.isParentWindow(): Indicates whether the current window is the parent.
  • pureweb.WebClient.MultiWindow.isChildWindow(): Indicates whether the current window is a child.
  • pureweb.getFramework().canCreateNewWindow(): Returns true if this client can open a new window.

  • pureweb.getFramework().getOpenWindows(): Returns all windows known by this parent window. If not the parent window, the child will call its parent to perform the action.