A basic map
There are three easy steps involved in adding a map to your web page. The first one is to paste the XForms namespace declaration on to the html root element:
Next, you need to paste a couple of script tags into your document's head:
These will load Ubiquity XForms and Google Maps. Google Maps requires you to get an API key from their site. When you have one, just paste it in place of the text: ENTER YOUR GOOGLE MAPS API KEY HERE
The third and final step is to add an XForms output control to the body of your document. The control must have the attribute class="geolocation" and a value attribute that evaluates to the location that you want to display. The location can be in the form of an address, or a semi-colon separated latitude and longitude pair of co-ordinates. For instance, the following markup displays a map showing the location of the webBackplane office in central London:
If you just want to display a static map on your page, then that is all you need. However, the presence of Ubiquity XForms enables things to get a lot more interesting than that.
User input
You may notice that the map in the previous example does not permit the user to change the location. There are buttons to zoom in and out, but the centre point is locked in place. This is because it uses output, which does not allow user input by definition. In order for a user to move your map around, you have to swap the output control for a range control. And, since range doesn't support the value attribute, you'll also need to add an XForms model containing the instance data that the range can be bound to:
You will see that, although the map looks similar to the last example, it now has buttons for panning the map north, south, east and west. Additionally, if you click and hold the left-hand mouse button, you can drag the map to move it to a new location. Each time you move the map, the bound instance data will get updated with the centre point, indicated by the red map marker. You can further verify this binding by adding a second map, bound to the same instance data as the first one. Each time you move the position of the first map, the position of the second will get updated automatically by the XForms dependency engine and vice versa:
Adding a hint
In XForms, each of the UI controls can be complemented with a child hint element. Ubiquity XForms makes use of hint for map controls to add contextual information to the map marker. When the user clicks the left-hand mouse button on the central map marker, an information bubble will pop up. In an output map control, this information might be static data:
For range controls though, you would most likely want the hint itself to be based dynamically on the current location of the map. Fortunately, this is straightforward to achieve with the ref attribute on the hint element:
Notice how, after the map is moved, clicking on the marker will display different information: the latitude and longitude of the newly selected location.
Styling your maps
Map controls can be further customised by setting the width and height via CSS. Depending on how much space you assign to display the map, Ubiquity XForms will make decisions about which adornments should be displayed. It also initialises maps to a zoomed out, progressively less detailed view as their size is reduced. In the following example, the output control will be displayed with no adornments and zoomed out, whereas the range control will be displayed zoomed in with a full set of adornments. But because they are bound to the same instance data, they are just different views of the same location. Panning the map in the range will also cause the location of the output map to shift:
| Attachment | Size |
|---|---|
| ubiquity-xforms-map-detail.jpg | 22.85 KB |
