1 | |
---|
2 | Current for 6.x-2.x |
---|
3 | |
---|
4 | # Layer Types |
---|
5 | |
---|
6 | Layer types are one of the fundamental building blocks of the OpenLayers module. |
---|
7 | They are factories for layers themselves - a layer type is like a wrapper around |
---|
8 | an OpenLayers (javascript) object which lets you configure settings through the |
---|
9 | UI and also encapsulate other tasks that layers need to do, like loading |
---|
10 | information. |
---|
11 | |
---|
12 | ## Structure |
---|
13 | |
---|
14 | Typically a layer type is a class that extends `openlayers_layer_type`, although |
---|
15 | it can extend another layer type class if necessary. All that's really needed is |
---|
16 | that it implements the right methods. Which are... |
---|
17 | |
---|
18 | * `render`: The `render(&$map)` function is called on each layer type when a map |
---|
19 | is rendered. Since the map array is passed by reference, this function can |
---|
20 | modify it in any way it wishes. However, typically render functions just |
---|
21 | include layer javascript and then return their options array. |
---|
22 | * `settings_form`: The settings form of a layer type is different from the |
---|
23 | options form in two very important ways. The first, practical reason for their |
---|
24 | separation is that layer type settings are settings that you'll want to set |
---|
25 | for an entire website, like a Google Maps API key or javascript location. So, |
---|
26 | these settings are not attached to individual layers. The other, technical |
---|
27 | difference, is that, while layer *options* end up in the data array, which is |
---|
28 | serialized and exported, etc., layer *settings* are saved as Drupal variables, |
---|
29 | so that they can optionally intercepted by modules like Spaces, which allow |
---|
30 | users to customize domain-specific settings (like API keys) by space. |
---|
31 | * `options_form`: The options form of the layer is what the user sees when they |
---|
32 | land on the layer add form. The results of this form submission are |
---|
33 | automatically saved as the contents of the layer's 'data' property, which is |
---|
34 | then sent to javascript and, depending on layer type, pushed into the |
---|
35 | Javascript layer constructor. This means that exported layers can have more |
---|
36 | properties than the OpenLayers Drupal Module knows about, and they will be |
---|
37 | seamlessly pushed into Javascript and serve their function in Javascript-land. |
---|
38 | * `options_init`: The options_init function defines the default options of any |
---|
39 | given layer. This is used for options that will not be set in the options |
---|
40 | form, but would be awkward to code as hidden fields. If your layer type class |
---|
41 | has the correct __construct implementation (like those in the OpenLayers |
---|
42 | Module), then these settings will be added whenever you initialize a layer |
---|
43 | |
---|
44 | ## Vector |
---|
45 | |
---|
46 | * Map objects can contain an attribute called 'vector', defined in options_init(): |
---|
47 | |
---|
48 | function options_init() { |
---|
49 | return array( |
---|
50 | 'vector' => TRUE, |
---|
51 | ); |
---|
52 | } |
---|
53 | |
---|
54 | * This is an important attribute - it designates layers that are derived from |
---|
55 | the OpenLayers Vector layer class [1]. Unlike tile or image-based layers - |
---|
56 | like OpenStreetMap or Google Maps, these will typically be from data files |
---|
57 | like KML, GML, or OpenLayers Data layers. And also unlike image-based maps, |
---|
58 | they don't need to be in the projection of the rest of the map, since they are |
---|
59 | easily reprojected by the OpenLayers Javascript library. So, it is possible to |
---|
60 | have a WMS layer in the EPSG:4326 projection with KML data on it, and also put |
---|
61 | that KML data on a Google Maps map in the EPSG:900913 projection, and the data |
---|
62 | will be displayed on both. Thus setting the vector attribute allows certain |
---|
63 | layers to be added to maps of any projection. |
---|
64 | |
---|
65 | [^1]: http://dev.openlayers.org/releases/OpenLayers-2.9.1/doc/apidocs/files/OpenLayers/Layer/Vector-js.html |
---|
66 | |
---|
67 | ## Javascript |
---|
68 | |
---|
69 | OpenLayers Layer Types typically have a bit of Javascript accompanying them |
---|
70 | which follows a certain form. It will provide a method in the |
---|
71 | `Drupal.openlayers.layer` namespace, like `Drupal.openlayers.layer.cloudmade`, |
---|
72 | takes arguments `(name, map, options)`, and will return a fully initialized map |
---|
73 | object. These are basically factories for OpenLayers Layer Type objects, and are |
---|
74 | usually under 50 lines long. Note that if you plan on making a distinctly |
---|
75 | different layer type, it's best not to do it within this javascript file, but to |
---|
76 | create a new OpenLayers Layer Type (in javascript) - see the MapBox module for |
---|
77 | an example of a new OpenLayers Layer Type (`OpenLayers.Layer.MapBox`), which is |
---|
78 | entirely independent of the Drupal module. |
---|