DEV Community: Fred Christianson

Multi-window JavaScript App

Fred Christianson — Tue, 28 Mar 2023 20:10:06 +0000

If you want to see this in action before continuing there are 2 examples fredchristianson.github.io deployed from my GitHub examples repository. Use the "Simple Child Windows" or "Child Window" links on that page.

I always knew window.open() could do more than I used it for. But I never know how great it is.

Multi-window JavaScript App

I'm working on a project where I want to see multiple things at the same time

Test controller
Results
Visual test
Manual accept/fail of (3)

With a multi-monitor system, I didn't want to squeeze all that into one browser window. Separation can be nice even with one monitor. So I decided to look more carefully at window.open(). I've used apps where a popup window form is obviously working with the main form so I knew it was possible. Turns out it's extremely easy and powerful.

Terminology

These are the terms I will use in this document

Parent - the window that called window.open(). Most documents call this "opener", which is the property name in the opened window. "Primary window" is also used.

Child - the window created by window.open(). I have seen this called a "secondary window".

Name - the 2nd window.open() parameter is called "target". I will use the term "name" for child windows. In my implementation name is used

to create the target (whitespace removed),
as the new window title,
can be used to manage multiple open windows (e.g. in a Map).
used to save/load window position in localStorage (.e.g. child-window-pos-${name})

Quick Summary

Parent and child windows have access to each other's global "window" object

Access includes window.document.body which allows usage of most common DOM properties, manipulation functions, and event listening on any element in the other window's body.

window.postMessage() is an easy way to pass data/requests between windows. The other window needs to listen to "message" events.

Window Creation

window.open() takes up to 3 parameters, and returns a Window object (actually a proxy to a Window object)

const child = window.open(url, target, features)

If popups are blocked in the domain, this will fail. It's not always obvious in the browser UI so it's good to alert("New window failed. Are popups enabled?");

url

The first parameter can be an absolute or relative URL or an empty string. An empty string opens a window with a blank page. If the URL is not an empty string, the browser attempts to load it.

target

This optional parameter can be null or any of the target values allowed in an <a> element: _self, _blank, _parent, and _top. It can also be the name of a window to open (or reuse if a window of that name is already opened). Whitespace is not allowed in the name.

features

The last parameter is also optional or can be a comma-separated string of "name=value" pairs. If no parameters are specified, the new window will probably open as a tab in the same browser window as the parent. MDN has full details of this parameter.

If the feature "popup=true" exists, the browser creates a "minimal popup window". The browser decides what "minimal" is.

One or more of "width", "height", "left", "top" can be specified. The values are in pixels, and the browser selects values for any that are not specified. For example

"width=500,height=600,top=100"

creates a window 500x600 pixels at a location with a top of 100 and a left selected by the browser. The browser will ignore position values if they would place the window off screen. See "Multi-monitors on Chrome" section below for details of using multi-display systems on Chrome.

You can also specify "noopener" if the child should not have access to the parent's DOM and "noreferrer" if the URL request should not include the HTTP referrer header. These are not usually useful in a multi-window application.

Google returns many sites referring to other features like "resizable" and "memubar". They are not in the current MDN docs and I do not see any effect in chrome or firefox.

window.open() return

If window.open() succeeds, it will return a Window object for the window where it was opened. This object is the same class as the global "window" value, but a different instance. If open failed it returns null. The main cause of failure is having popups blocked.

The returned child window has not loaded the URL at this point. It does not have a document (so no body or elements to work with) You need to wait for a "load" event. A simple way to do that is with an async function like this

async function openChild(url,target){
    const child = window.open(url, target);

    return new Promise((resolve, reject) => {
        if (child == null) {
            alert("open failed.  are popups blocked?");
            reject();
        }
        child.addEventListener('load', async (_event) => {
            resolve(child);
        });
}

One problem is that the HTTP request for the URL may fail. There is no good way to tell if the request failed. The "load" event only indicates the HTTP request is complete. But not if it completed with a 200 status, or 404, or 500, or anything else.

If you are loading a page with known content, you can query the child document body after "load" to determine if it has expected text or elements. Or you can include javascript in the child page that uses window.opener.postMessage() to notify the parent that it is loaded and running. (You can also use custom events, or manipulate the parent DOM instead of postMessage if that's more appropriate for your application).

There is an "error" event the parent window can listen to. Unfortunately, that is triggered by errors processing the returned URL, not by HTTP errors. It may be useful, for example, to detect javascript initialization errors in the child windo.

Assuming this is a coordinated multi-window application, it's probably best for the child window to include javascript that notifies the parent window when it is ready (see postMessage below).

If the request can timeout you may want to use setTimeout to give up after some amount of time.

return new Promise((resolve, reject) => {
    let timeout = setTimeout(reject,5000); // 5 seconds
    child.addEventListener('load', async (_event) => {
        clearTimeout(timeout);
        resolve(child);
    });
});

Closing

The parent window can easily close the child window

childWindow.close()

But a multi-window app needs to consider many complications

The user may close the child window unexpectedly while the parent expects to still access its elements.

The user may close the parent window while child windows are left.

The child window may listen for "beforeunload" events and cancel the close

The parent window may listen for "beforeunload" events and cancel the close

None of these are difficult to solve, just things that should be considered when developing a multi-window application.

1) "beforeunload" events are unreliable when it comes to canceling a close. It is not a good idea for either the parent or child to use the event for that purpose.

2) When the application's main window is closed, it is usually a good idea to close all child windows. This closes 2 child windows if they are not null

// close the child windows when the main window is closed.
window.addEventListener('beforeunload', () => {
    controlWindow?.close();
    drawWindow?.close();
});

3) A parent can listen to a child's 'beforeunload' event and create a new child if the child window should not be closed. This isn't as good as canceling the close, but is reliable.

child.addEventListener('beforeunload', recreateChild);

recreateChild() would probably

save the child's position
create a new child
set the new child's position to replace the closing child
restore the new child's state (input value, text, etc)
listen for child events - including 'beforeunload'

4) A parent can use the child window's "closed" property to recreate a closed child when needed rather than during 'beforeunload'

if (child.closed) {
    recreateChild();
}

I think it is useful to save the window's location in "beforeunload"

const location = {
  left: window.screenX
  top: window.screenY
  width: window.innerWidth
  height: window.innerHeight
};

localStorage.setItem('child-window-location',
                     JSON.stringify(location)

Then use that to generate features when opening the window again

const location = localStorage.getItem('child-window-location');
let features = 'popup=true';
if (location != null) {
   features = `left:${location.left},...`
}
window.open(url,name,features);

Chrome needs permission for this to work with multiple monitors.

document

A loaded child window has a document just like any other javascript window.

const childDocument = childWindow.document;
const childBody = childDocument.body;

These can be used used to inspect, change, and listen to the child DOM the same as the main (parent) DOM

const mainBody = window.document.body;

mainBody.style.backgroundColor = '#00f';
childBody.style.backgroundColor = '#00f';

mainBody.querySelector('.message').append('new message');
childBody.querySelector('.message').append('new message');

mainBody.querySelector('input.name').value;
childBody.querySelector('input.name').value;

mainBody.addEventListener('mousemove',mainMouseMoved);
childBody.addEventListener('mousemove',childMouseMoved);

The child has similar access to the parent's DOM

const parentBody = window.opener.document.body;

parentBody.style.backgroundColor = '#00f';

parentBody.querySelector('input.name').value;
parentBody.querySelector('.message').append('new message');

parentBody.addEventListener('mousemove',mainMouseMoved);

While it is possible for JavaScript in multiple windows to use multiple DOMs, it will likely cause problems with debugging and maintaining the code. The most maintainable solutions will be either

The parent window handles all DOM management (modifications and events)

The child window handles of its DOM management and the parent does nothing with childWindow.document. In this case, the 2 parts of the application communicate with postMessage or CustomEvents.

Global Classes

This doesn't come up often, but classes such as HTMLElement and HTMLDivElement are properties of Window. And they are not the same in the parent and child window objects.

const parentDiv = window.document.createElement('div')
const childDiv = childWindow.document.createElement('div')

parentDiv instanceof HTMLElement;             // is true
childDiv instanceof HTMLElement;              // is false
childDiv instanceof childWindow.HTMLElement;  // true

In my testing, even though parentDiv and childDiv are not created by the same HTMLElement constructor, they may be inserted into with DOM. It is probably safest for the future to use the correct window's document.createElement to create new elements. Different window objects also have different DOMParsers so use the correct one of those also.

Global Values

Classes are just one type of property a Window object contains. They are just functions and any other function or data can be added to a parent or child window and accessed by the other

parent JavaScript:
    window.callParent = function(...args) {...};
    window.parentData = { a:1,b:2};

child JavaScript:
    window.opener.callParent(1,2,['a','b']);
    const parentData = window.opener.parentData;
    parentData.a = 5;

Similarly, the child can add properties to its window and the parent can call or access them.

This is probably a bad idea in most cases. JavaScript debugger and console logs are not shared between the windows. So it can be more difficult to track down problems if multiple windows are modifying the same data.

Child and parent JavaScript can communicate with postMessage and CustomEvents in a way that is likely to be much more maintainable.

Inter-window Events

The simplest multi-window application runs all JavaScript in a single window. It has access to the DOM in every window and takes care of everything. There are many cases where there are advantages to developing the windows independently (JavaScript, HTML, CSS) and use inter-window communication. The communication may be modifying DOM, calling each other's functions, accessing window properties, or events.

An architecture where windows communicate with each other through events is likely to be

Most maintainable
Most extensible
Most testable

In terms of maintainability, the JavaScript, HTML, and CSS for each window can be changed without concern for the implementation of other windows. The events make an API and as long as the API is followed problems are unlikely.

For extensibility, a window implementation for one application may be more easily added to other applications. The event API must be followed, but the DOM, data, and functions are independent.

Testing a child window implementation is fairly straightforward with an event interface. And the test harness will not need to change as the child implementation changes.

There are 2 (very similar) ways for windows to communicate with events. The first is custom events.

Custom Events

JavaScript CustomEvents are listened to like any other event. There are a few things to manage

The sender and receiver need to use the same name ("myevent" below)

The second parameter of the CustomEvent constructor must be an object with a "detail" property to send data to the listener

dispatchEvent is used to send the event to the listener (dispatchEvent can be used on elements as well as on the Window object. event.target has the window or element as with any other event)

Parent: 
    window.addEventListener('myevent',(event)=>{
        const data = event.detail;
        // data is the detail object send by the Child
        // {"name":"fred","age":57} in this example
    });

Child:
    const data = {
        "name": "fred",
        "age": 57
    };
    const event = new CustomEvent("myevent",{detail: data});
    window.opener.dispatchEvent(event);

It is fairly simple and works the same if the child listens to its window and the parent dispatches the event. This works great for one-way events (i.e. notifications). It needs more if the child needs a response. In my opinion, the easiest is to use a Promise

Parent:
    window.addEventListener('myevent',(event)=>{
        const data = event.detail;
        if (isValid(data)) {
            const response = {"message":"got it", value:42};
            data.resolve(response);
        } else {
            const error = new Error("something went wrong");
            data.reject(error);
        }
    });

Child:
    let resolveEvent = null;
    let rejectEvent = null;
    let promise = new Promise((resolve,reject)=>{
        resolveEvent = resolve;
        rejectEvent = reject;
    })

    const data = {
        "name": "fred",
        "age": 57,
        resolve: resolveEvent,
        reject: rejectEvent
    };
    try {
        const event = new CustomEvent("myevent",{detail: data});
        window.opener.dispatchEvent(event);
        const response = await promise;
        // got response
    } catch(error) {
        // something failed
    }

There is much more code for a single event with a response than a one-way communication. But most of it is common and easily encapsulated in a module and would not need to be repeated if there are many events passed between windows.

postMessage

In a multi-window application on the same domain, postMessage has no advantage over custom events. postMessage has checks for the "same-origin policy" so it would be preferred if that is a concern. You can read more about it on mdn web docs.

Multi-monitor Windows on Chrome

Firefox, and most browsers support features with left and top on any monitor. Chrome requires user permission or it always moves the new window to the same monitor.

It has a global function to ask the user for permission: getScreenDetails.

I created a function to ask the user for permission and wait for a response if Chrome's function exists:

async _checkMultipleScreenPermission() {
    if (!('getScreenDetails' in window)) {
        return true;
    }
    const promise = new Promise((resolve, reject) => {

        window.getScreenDetails()
            .then(() => {
                //user allowed multiscreen
                resolve(true);
            })
            .catch((ex) => {
                // user did not allow multiscreen.  not a problem.
                resolve(false);
            });
    });
    return await promise;
}

Before using window.open with features that specify a left or top, call this function

await checkMultipleScreenPermission();
window.open(url,target,"left:2000,top:50");

If getScreenDetails doesn't exist, the await will return immediately and the window will be opened. It will also return immediately if the user has already granted or denied permission, so will not prompt the user every time.

Examples and Discussion

There are 2 examples of child windows on GitHub if you want to see any of this work

If you want to just see them in action they are deployed to fredchristianson.github.io

The best place to contact me if you have corrections or questions is Twitter.

Software Coupling (Part 2 – OO)

Fred Christianson — Sun, 26 Feb 2023 02:55:53 +0000

I provided a brief introduction to coupling in part 1. This article is specifically aimed at coupling in object-oriented systems.

There are academic ways of Measuring Cohesion and Coupling of Object-Oriented Systems. And there are formal explanations of types of coupling and cohesion and complexity metrics.

I’m ignoring academia and formality and measures. I’ll explain the types of relationships in object-oriented systems that create complexity. This complexity is often a large component of technical debt. I’ll refer to all types of relationships as coupling even when it’s not formally the correct term.

There is a lot of theory on reducing coupling with tools like encapsulation, inheritance, and abstraction. I am writing about what I’ve experienced in decades of practice which does not always match the promises of theory.

Relationship Example

I had a client with 100s of Java applications and 1000s of packages intended to be reused wherever needed. One of my tasks was to extend “App 1” (in the diagram) to include features from “Package B”.

B was used pretty heavily in many apps without issue, so this should be easy. But it wasn’t.

To keep this short, A acted weird after B was added to App 1. And nobody knew much about C. And there were a dozen other packages that were just as likely to be the problem.

We finally figured out that if there were no explicitly configurated properties for C, it chose defaults that were altered by an optional dependency injection that B provided.

There are many ways this could have been avoided. And it could have been a reasonable implementation when C was created.

Configuration issues are not a problem that is specific to object-oriented systems. This example is not meant to show OO or DI is bad. But that there are hidden relationships as well as explicit dependencies involved in the coupling among parts of the system. And also, because of the number of packages, classes, and interfaces used by the app, it’s unlikely that documentation of C would have helped to find the issue.

chatGPT tells me

To minimize coupling, developers can use techniques such as encapsulation, abstraction, and inheritance, which promote modularity and loose coupling between different parts of the system.

While this is true, a little loose coupling can cause trouble. And a lot of loose coupling makes a system difficult to maintain and extend.

Interfaces

Interfaces can be used to reduce coupling.

In this diagram, ConsumerA only depends on the interface. In theory, any of the implementations can be provided to a ConsumerA object and it will work.

In practice, there are many relationships in a code base with these items. There are many things that may cause problems in the future:

A necessary change to InterfaceA requires changes to all implementations
A new implementation may follow the interface contract, but not the intent. It just happens to be an easy hook into consumers, so it is used.
ImplB is modified and causes performance issues with consumers
ImplC has side effects. It’s usually used for other things but a DI change causes it to be injected into a consumer which breaks because of the side effects.
Interfaces are great and have many uses. Most will not cause problems, but in a project with dozens or hundreds of global interfaces, it’s easy to have a few that cause problems in version 2, or 3, or N.

Interfaces can reduce coupling if used well. But a little thought of scope and functionality during architecture design can reduce the chance of future problems. It’s not a simple matter of “create an interface and coupling is reduced”.

Data

Data is usually encapsulated so users of a class cannot access fields directly. While this provides some protection, it is a relationship that can break in the future.

In this diagram, the Base class implements virtual methods getA() and setA(). SubclassB overrides them.

There are a few relationships that need to be considered:

Type of field A: If this changes, it will require changes anywhere Base get/setA() is used.
Implementation of SubclassB: this subclass may have (or add) constraints that break ConsumerA. If ConsumerA is given a Base object, the writer may not be aware that SubclassB.setA() is different than Base.setA()
SubclassA: this subclass may be changed to override getA() and setA() with constraints or modifications. While there is no coupling at this time in the code, there is a relationship in the architecture that may cause issues.
SubclassC: As with interfaces, future subclasses may be created which match the contract of getA() & setA() but have side effects or performance issues.
When architecting a class hierarchy it’s good to consider why getters and setters are created. Do consumers really need access? Can the scope be limited (package, subclass)? I’ve heard arguments for including getters and setters

It makes the class more flexible when consumers can access the data. Encapsulation protects the data so why not?

While this is true, it also adds coupling now or potentially in the future. The class designer should determine what consumers will need and why. It takes more thought in the architecture/design phase but limits potential complexity to be intentional about data access.

Methods

Methods have a similar coupling as data getters and setters, including future relationships from being virtual.

Any method which is called from within a class, or a subclass, or an external class is a relationship. If it is not called but is within scope, it is a possible future relationship.

As with data, a broader scope makes the class more flexible since coders of external classes can decide when and how a method is used. A good class design considers not only why a method exists, but when, where, and how the method should be used. Leaving those decisions up to consumers leads to complexity and often misuse of classes which becomes difficult if not impossible to untangle.

One way to significantly reduce virtual method complexity is to make all virtual methods protected. A common virtual method pattern is to make the virtual method public and use it in the subclass

    public override int methodA(int b)
    {
      var result = base.methodA(b);
      /* do more */
      return result;
    }

This creates a heavy coupling between consumers calling methodA and any implementation. It also allows a subclass to not call base.methodA() – intentionally or accidentally. Even if the base implementation does nothing now, in the future it may add validation or calculations, or any number of other functionality that it expects subclasses to call.

It is better to have a base public methodA that is not virtual. It will always be in control and subclasses only need to implement what they need

  internal class BaseB
  {
    private int a;

    public int methodB(int b) { 
      if (!isValid(b))
      {
        throw new ArgumentException();
      }
      setupB(b);
      doMethodB(b);  
      cleanupB(b); 
      return a; 
    }

    private bool isValid(int b) { return b >= 0; }

    protected virtual void setupB(int b) { }
    protected virtual void doMethodB(int b) { a = b; }
    protected virtual void cleanupB(int b) { }
  }

This looks like more effort than a public methodB(). But it only needs to be implemented once. All subclasses are guaranteed to call

isValid
setupB
cleanupB

in the correct order. Consumers are guaranteed that argument validation is called and that any necessary setup and cleanup is performed. Additional mandatory functionality can be added to the base class in the future without the possibility of subclasses not calling the base method. There are many other advantages that may come up over multiple versions of an application. It may only occur in a small percentage of classes, but it can be very helpful to add code to the base class and be guaranteed that it will be called for every subclass and in the right order. Some of these areas are

logging
resource management (open/close files, create/free drawing contexts)
monitoring & metrics
performance (timeout, caching, etc)
synchronization

With no public virtual methods, users of the class only have tight coupling to a single known base class. It’s possible for subclasses to cause problems, but it’s much less likely when they implement the minimal polymorphic functionality and the base class guarantees documented common functionality.

Dependency Injection

Dependency Injection is very powerful for many things from testing to configurable runtime implementations. It also can create relationships and chains of relationships that neither the dependent class nor the dependency class has considered.

It provides a simple way to create proxy classes to execute a method remotely or add validation, logging, or any number of other extensions without modifying the dependency class. The proxy class (or alternate implementation) can also add

performance issues
stability issues
security issues (logging a password)
synchronization issues

When DI is used to create architected configurations of components it is powerful. When it is used to put components together in a way the injector decides is appropriate it’s easy to end up with unknown relationships and complexity.

The runtime architectural structure should be intentional. Stability is difficult when the structure is a result of many independent injection requests.

Client-Server

It’s common to share components on a client and server. Whether its

data structure
class design
class implementation

it is very tempting to have both sides of an API use the same thing. This can happen with a web front end using a nodeJS API. Or with microservices calling each other in any language. It certainly speeds up development when the same component can be used on both sides.

It’s easy to end up with one side not being architected – it just copies the other side. It’s unlikely that the architecture on both sides ends up as good as it could be. And it’s very likely that there will be future limitations and difficulties because of the tight coupling between the client and server.

This is a specialization of the DRY principle. It’s important to look not just at the what and how, but why the functionality is needed. If the why is different, there is an unnecessary relationship that can be restrictive in the future.

In general, data on the server exists for different reasons than the client (e.g. database CRUD vs UI). It is unlikely that the same classes will be appropriate as the system iterates through versions. It is likely that changes on one side will be limited by the other or cause problems on the other.

Avoidance

Object-oriented systems have many relationships by design. One way to avoid system complexity is to localize useful relationships.

Module & Package Interfaces

Keywords like sealed, internal, final, protected, and private are often avoided because “they make the class/module/package less flexible”. But that flexibility is what leads to unmanageable complexity.

The 2 class designs below have the same number of objects and modules. The one on the right has additional interface objects (rectangles) and all inter-module relationships are isolated to those interfaces.

The entire implementation inside of a module can be replaced without risk to other modules on the right design. While that is the idea behind interfaces, what simplifies this design is that the interfaces share data-only objects. There are no relationships between classes in one module and methods of classes in another.

Modules are usually used to group related objects or functionality. They are less often used to isolate complexity, but that is where they are most powerful as an application iterates through multiple versions.

While it’s rarely possible or even desirable to hide module function (i.e. public methods) it is useful to think about the minimal interface (data & methods) a module can expose and still meet its objective.

Access can always be loosened later if necessary (e.g. protected–>public) fairly easily. Tightening access can be much more difficult.

Microservices

I’ve seen microservices used, not to reduce complexity, but because changes made in one part of a monolithic service always break other parts. Instead of requiring all parts of the system to be debugged and deployed together, only the changed service needs to work.

The microservice deployments are a bandaid over a complex monolithic system that is no longer maintainable. There will certainly be shared components of any system with microservices. The components need to have as few relationships as possible in order to avoid the same problems a tightly coupled monolithic system has.

Data Mappers

Learn to love data mappers. In version 1 they may do nothing. Or may make a copy of an object.

Once mapper infrastructure is in place, it is trivial for one component (class, module, client) to change its data structure without impacting others. Each component should use data structures that suit it best, and not make do with objects it is passed using data that is appropriate for another module.

A data mapper may create a new object and copy/transform data from another object. Or it may be a wrapper around another object with restricted access or transformations on get/set. Or an interface that provides a limited view of fields. The most important value of a data mapper is that it encourages the developer to think through the data design for each module rather than using a system-wide entity definition.

API (client-server)

Architect the client and server independently. While the architectures may have a lot in common, the 2 systems serve different purposes and there should be differences in the architecture. This includes data, transformations, functionality, and many other things.

It will be tempting to reuse components (e.g. classes) but think carefully about copy/paste instead of shared classes. For rapid prototyping without much architecture, it can be much quicker to share classes initially. But as soon as you have reached some amount of stability & correctness consider copy/paste to create 2 versions of the same class that can move forward independently in the direction that is best for each side of the API.

Summary

In a large, complex system, it’s important to minimize relationships between components. With tight coupling, changes in one part of the system cascade to others. It can become difficult to make a change anywhere without impacting a significant portion of the rest of the system. Even minor changes are risky because it’s difficult to estimate how they will affect other parts of the system.

In addition, tight coupling (or any coupling) restricts changes that can be made. Or it requires significantly more effort than should be necessary as all of the coupled classes need to be modified as well. And, the higher the coupling in the system, the more the changes cascade causing – requiring changes, testing, and debugging throughout the system.

By nature, an object-oriented system has significant amounts of coupling. Using module boundaries and data mapping can localize coupling complexity and significantly improve the stability of a large system undergoing changes.

If you have any corrections, comments, or suggestions, let me know on Twitter.