What happens?

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

Why does this happen?

Usually, the LuciadRIA map automatically re-sizes to the size of its DOM node: LuciadRIA can determine the size of the DOM node and ensure that every pixel in the DOM node is used to visualize the map. In some cases, the Map is not notified when the size of a DOM node changed. Because the Map doesn’t know about a change in DOM size, it won’t automatically adjust. Depending on how your application page is structured, the LuciadRIA Map might need some help to determine the size of its DOM node.

How does DOM node sizing work?

A LuciadRIA map is represented in a web page by a DOM node, usually a <div> node. As with any other DOM node, the browser styles the map DOM node according to a CSS stylesheet configuration. The CSS stylesheet includes the size of the DOM node.

The size of a DOM node is determined by its width and height CSS properties. 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 will always be 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 that is 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 is assigned 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 does not 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 is instantiated.

A web browser also fires events when the browser window is re-sized. The Map is automatically registered to this event. Each time the browser window is resized, the Map re-inspects the DOM and adapts the size of its HTML5 canvases as needed.

DOM nodes can be re-sized when the browser’s layout engine is triggered because of the following events:

  • The size of the browser window is changed

  • Properties of the DOM node are modified dynamically using JavaScript

  • The content of the DOM node is modified dynamically using JavaScript

Only in the first case does the Map get notified of the change in size. 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 is instantiated. Therefore, it is important that you instantiate the map after the page has loaded completely and the DOM node sizing has finished. You can accomplish this by registering a callback on the window’s onload event.

The loader/domReady! AMD loader plugin, which is used in the LuciadRIA samples, already does so. Other AMD loaders typically have a similar plugin available.

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 are not triggered, you will not get an automatic notification of a size change, and you will have to re-size the Map yourself. Particularly in cases where the properties or content of DOM nodes are modified by JavaScript, it can happen that the size of the DOM node changes without the Map’s HTML5 canvases adjusting to the new DOM node size. You will notice this when the size of the Map’s DOM node increases, but the Map does not use the extra space to render the Map.

Even if you do not explicitly manipulate the DOM node yourself, you may be using software components that do. For example, you might be using a JavaScript layout manager that allows you to organize the webpage in re-sizable regions. Re-sizing one or more regions will change the size of one or more DOM nodes. However, the Map will not be notified, unless you explicitly resize() it.

You can re-size the map manually. The Map object is equipped with a resize() method. If you invoke this method, the Map will calculate the size of its DOM node and update the size of its canvases accordingly.