What happens?

My LuciadRIA map should adjust its size to the web page size, but it’s too large or too small.

Why does this happen?

Usually, the LuciadRIA map automatically re-sizes to match the size of its DOM node. LuciadRIA determines the size of the DOM node and puts every pixel in the DOM node to use to visualize the map. In some cases, the Map doesn’t receive a notification when the size of a DOM node changed. Because the Map doesn’t know about the change in DOM size, it won’t automatically adjust. Depending on the structure of your application page, the LuciadRIA Map might need some help to determine the size of its DOM node.

How does DOM node sizing work?

In a web page, a DOM node represents a LuciadRIA map, typically a <div> node. As with any other DOM node, the browser styles the map DOM node according to a CSS style sheet configuration. The CSS style sheet includes the size of the DOM node.

The width and height CSS properties of the DOM node determine its size. These properties can have fixed values or relative values. An example of a fixed value is width: 400px. In this case, the width of the DOM node always is 400 pixels. An example of a relative value is width: 75% or width: 40em.

The actual size in pixels of a relative value depends on other properties of the page. A width of 75% means that the DOM node takes up 75% of the pixel width of the DOM node parent. A width specified in em indicates that the DOM node takes a pixel width relative to the font size used in the node. The letter "m" is used as the reference letter to determine the font size. 40em means that the DOM node gets 40 times the width of "m".

What does this have to do with the size of my map?

A LuciadRIA Map renders on an HTML5 canvas. LuciadRIA creates the HTML5 canvases in the DOM node that you pass to the Map constructor. However, the width and height of an HTML5 canvas must always be expressed in absolute pixel values. It doesn’t understand relative pixel widths. LuciadRIA takes care of the conversion of absolute DOM sizes to relative canvas sizes: it queries the DOM for the pixel size of the DOM node, and adapts the size of its HTML5 canvases accordingly.

When is the size of my map determined?

A LuciadRIA Map determines the size in pixels of its DOM node when it’s instantiated.

A web browser also fires events when the size of the browser window changes. The Map automatically receives those events. Each time the size of the browser window changes, the Map re-inspects the DOM and adapts the size of its HTML5 canvases as needed.

The size of DOM nodes can change when these events trigger the browser’s layout engine:

  • The size of the browser window changes

  • Properties of the DOM node change dynamically through JavaScript

  • The content of the DOM node changes dynamically through JavaScript

The Map get notified of the change in size in the first case only. In the other cases, the Map needs some help.

How can I fix it?

Instantiate your map only after the page has loaded

A LuciadRIA Map determines the size in pixels of its DOM node when it’s instantiated. Therefore, it’s important that you instantiate the map after the page has loaded completely and the DOM node sizing has finished. You can do so by registering a callback on the window’s onload event.

Manually re-size your map

The resize and onload events are the only browser events that indicate that the size of a DOM node has changed. If those events aren’t triggered, you don’t get an automatic notification of a size change, and you must re-size the Map yourself. Particularly in cases where JavaScript code changes the properties or content of DOM nodes, the size of the DOM node may change without the Map’s HTML5 canvases adjusting to the new DOM node size. When that happens, notice this when the size of the Map’s DOM node increases, but the Map doesn’t use the extra space to render the Map.

Even if you don’t explicitly manipulate the DOM node yourself, you may be using software components that do. For example, your JavaScript layout manager may organize the webpage in re-sizable regions. Re-sizing one or more regions changes the size of one or more DOM nodes. The Map won’t be notified though, unless you explicitly resize() it.

You can re-size the map manually. The Map object has a resize() method. If you invoke this method, the Map calculates the size of its DOM node and updates the size of its canvases as a result.