DRAFT: not yet complete
There are several options for how widget output will be added to the web page. In the examples given below, other widget properties are omitted for clarity, and only a generic Widget object is shown, and only <DIV> elements will be used for widget output. Any HTML element type can be used to hold widget output and widgets can output any element type.
The HTML Document Object Model (DOM)
Looking first at the HTML DOM, your page is generally coded something like this:
At runtime, it will look like this, with variations as configured in the Mapbuilder configuration file:
At various points of your application's execution, the widget output may change dynamically in response to changes in the model and user interaction with the page.
Mapbuilder configuration file
In the simplest case, a widget's id attribute is used to identify the node in the DOM to append output to. The widget's config id is the same as the id attribute value in the DOM.
There is also an <htmlTagId> property of widgets that can be used to override this behaviour. The value of <htmlTagId> will always override the value of id for selecting the HTML node the widget will insert in. This allows us to maintain unique _id_s for all the widgets in the config file.
Multiple widgets can also share the same HTML node if more than one widget uses the same htmlTagId value. In this case, widget output is just appended one after the other, but there is no guarantee about their order.
In general, the id of the widget generated content is automatically assigned to the widget output (i.e. the value widgetOuptut above). In some cases, you want widgets to replace other widget content. We can do this by assigning a value to be used for the widget output id using the <outputNodeId> property, in which case widget output will replace other widget output.
A MapContainer is special kind of widget for widgets that render their content in 2 dimensions. In this case, there is an extra <div> inserted into the DOM to hold output of all widgets that share the same <mapContainerId> property. Mouse event handlers assigned to the MapContainer and widget output is stacked using CSS absolute positioning. So in this case the DOM will end up like this: