This guide is still work in progress and will be finished when final Mapbuilder 1.5 is released. The described changes apply to Mapbuilder releases 1.5rc1 and later, for applications based on Mapbuilder up to release 1.5-alpha1.
With the introduction of OpenLayers as rendering engine for Mapbuilder, some widgets have changed, and some configurations need to be updated when upgrading from releases prior to 1.5-alpha2. Some things can now be accomplished in an easier way, like Overview Maps (formerly known as Locator Maps).
Deprecated Widgets and Tools
no longer needed (see below)
New properties to all widgets that inherit from WidgetBaseXSL.js
- parseHTMLNodes (Boolean, default=false) if true, HTML entities (like found in RSS feeds) will be parsed and converted to HTML, instead of showing HTML source code.
Changes in the behavior of the map (MapPaneOL)
- WMS services can now be consumed using tiles. To do this, use server type "WMS-C" instead of "WMS" in your map context.
- For better caching of map images, MapPaneOL works with fixed zoom levels, as soon as WMS-C or commercial layers (Google, Microsoft, Yahoo) are used. In that case, zoom operations (like zoom in to a box) will not result in the exact extent of the dragged box, but in the next fixed zoom level that the box fits in entirely.
- The map is clipped to the maximum extent specified in the context xml. If it is desired to view the map outside this extent, the property
has to be specified in the MapPaneOL config. Note that this will only allow you to view the map to the extent of the map tiles containing the specified extent. So this ensures that there will be no white border around the map image, but it will not allow for showing arbitrary locations outside the map extent. If that is desired, the property <maxExtent> of MapPaneOL has to be set, e.g.
<maxExtent>10 50 20 50</maxExtent>
- The <fixedWidth> property of MapPaneOL is no longer available. Instead,
can be used to take the size of the map pane from the context document. For a dynamically sized map pane, this options should not be set. Instead, a proper css for the mapPane div will do. The AutoResize widget is no longer available.
Changes in the behavior of the GmlRenderer (GmlRendererOL)
- The <stylesheet> parameter has a different meaning. If the GmlRendererOL widget is directly connected to a WFS FeatureCollection model, it is not needed at all. Otherwise, a stylesheet to transform the data to a WFS FeatureCollection has to be provided here.
- The new <featureSRS> property tells the renderer the source projection of the features from the model. Based on this information, features can be reprojected to the map projection.
- SLD documents can now be used directly to render the GML features. For that, a StyledLayerDescriptor model has to be present in the config. The config property <sldModel> refers to that sld document. The properties <defaultStyleName> and <selectStyleName> refer to <UserStyle> names in the sld document that will be used to render features or selected features. NOTE: All this will only work if the sld document has a <NamedLayer> with the same name as the id of the GmlRendererOL widget (e.g. if you have <GmlRendererOL id="gmlRenderer">, your sld needs to have <NamedLayer><Name>gmlRenderer</Name></NamedLayer).
Different configuration for MapContainer widgets
OpenLayers does not use a MapContainer any more as described in Controlling Widget Output. This change affects all widgets that used to have a <mapContainerId> property. This property is usually replaced by <targetModel>, linking to the context model that the map belongs to (eg. mainMap). For widgets that perform actions on a different model than the map (those that already had a <targetModel> property), the map is referenced by the <targetContext> property instead.
New and different configuration options for some widgets
Please refer to the Component Register for an overview of all models/widgets/tools and their properties.
Removal of MouseHandler tools
The following tools no longer need to be added to the Mapbuilder configuration file, because they are now handled by the OpenLayers rendering engine:
This means that widgets no longer need a <mouseHandler> property.
The old way of defining locator maps as a separate context with widgets and tools for displaying and modifying the extent and zoom level of the main map is deprecated. It can still be used, but it is recommended to switch to the new OverviewMap widget.
If you previously used a configuration like the following (taken from the Feature Entry demo):
<Context id="locator"> <defaultModelUrl>../data/context/locatorMap.xml</defaultModelUrl> <widgets> <MapPane id="locatorWidget"> <htmlTagId>locatorMap</htmlTagId> <targetModel>mainMap</targetModel> <mapContainerId>locatorContainer</mapContainerId> <fixedWidth>180</fixedWidth> </MapPane> <AoiBoxWZ id="aoiBox3"> <htmlTagId>locatorMap</htmlTagId> <stylesheet>../../lib/widget/GmlRenderer.xsl</stylesheet> <mapContainerId>locatorContainer</mapContainerId> <lineColor>#FF0000</lineColor> <lineWidth>1</lineWidth> <crossSize>15</crossSize> </AoiBoxWZ> </widgets> <tools> <AoiMouseHandler id="locatorAoi"/> <ZoomToAoi id="locatorZoomToAoi"> <targetModel>mainMap</targetModel> </ZoomToAoi> </tools> </Context>
you could now simply add the following to the <widgets> section of your main map context:
<OverviewMap id="locatorWidget"> <htmlTagId>locatorMap</htmlTagId> <width>180</width> <layers> <layerName>basic</layerName> <layerName>topp:tasmania_water_bodies</layerName> <layerName>topp:tasmania_roads</layerName> <layerName>topp:tasmania_cities</layerName> </layers> </OverviewMap>