Index: modules_contrib/openlayers/docs/LAYER_TYPES.txt
===================================================================
--- modules_contrib/openlayers/docs/LAYER_TYPES.txt	(revision 177a5601ebd55a1cfb22292f9cb8e8e43ee9fc51)
+++ modules_contrib/openlayers/docs/LAYER_TYPES.txt	(revision 177a5601ebd55a1cfb22292f9cb8e8e43ee9fc51)
@@ -0,0 +1,78 @@
+
+Current for 6.x-2.x
+
+# Layer Types
+
+Layer types are one of the fundamental building blocks of the OpenLayers module.
+They are factories for layers themselves - a layer type is like a wrapper around
+an OpenLayers (javascript) object which lets you configure settings through the
+UI and also encapsulate other tasks that layers need to do, like loading
+information.
+
+## Structure
+
+Typically a layer type is a class that extends `openlayers_layer_type`, although
+it can extend another layer type class if necessary. All that's really needed is
+that it implements the right methods. Which are...
+
+* `render`: The `render(&$map)` function is called on each layer type when a map
+  is rendered. Since the map array is passed by reference, this function can
+  modify it in any way it wishes. However, typically render functions just
+  include layer javascript and then return their options array.
+* `settings_form`: The settings form of a layer type is different from the
+  options form in two very important ways. The first, practical reason for their
+  separation is that layer type settings are settings that you'll want to set
+  for an entire website, like a Google Maps API key or javascript location. So,
+  these settings are not attached to individual layers. The other, technical
+  difference, is that, while layer *options* end up in the data array, which is
+  serialized and exported, etc., layer *settings* are saved as Drupal variables,
+  so that they can optionally intercepted by modules like Spaces, which allow
+  users to customize domain-specific settings (like API keys) by space.
+* `options_form`: The options form of the layer is what the user sees when they
+  land on the layer add form. The results of this form submission are
+  automatically saved as the contents of the layer's 'data' property, which is
+  then sent to javascript and, depending on layer type, pushed into the
+  Javascript layer constructor. This means that exported layers can have more
+  properties than the OpenLayers Drupal Module knows about, and they will be
+  seamlessly pushed into Javascript and serve their function in Javascript-land.
+* `options_init`: The options_init function defines the default options of any
+  given layer. This is used for options that will not be set in the options
+  form, but would be awkward to code as hidden fields. If your layer type class
+  has the correct __construct implementation (like those in the OpenLayers
+  Module), then these settings will be added whenever you initialize a layer
+
+## Vector
+
+* Map objects can contain an attribute called 'vector', defined in options_init():
+
+  function options_init() {
+    return array(
+      'vector' => TRUE,
+    );
+  }
+
+* This is an important attribute - it designates layers that are derived from
+  the OpenLayers Vector layer class [1]. Unlike tile or image-based layers -
+  like OpenStreetMap or Google Maps, these will typically be from data files
+  like KML, GML, or OpenLayers Data layers. And also unlike image-based maps,
+  they don't need to be in the projection of the rest of the map, since they are
+  easily reprojected by the OpenLayers Javascript library. So, it is possible to
+  have a WMS layer in the EPSG:4326 projection with KML data on it, and also put
+  that KML data on a Google Maps map in the EPSG:900913 projection, and the data
+  will be displayed on both. Thus setting the vector attribute allows certain
+  layers to be added to maps of any projection.
+
+[^1]: http://dev.openlayers.org/releases/OpenLayers-2.9.1/doc/apidocs/files/OpenLayers/Layer/Vector-js.html
+
+## Javascript
+
+OpenLayers Layer Types typically have a bit of Javascript accompanying them
+which follows a certain form. It will provide a method in the
+`Drupal.openlayers.layer` namespace, like `Drupal.openlayers.layer.cloudmade`,
+takes arguments `(name, map, options)`, and will return a fully initialized map
+object. These are basically factories for OpenLayers Layer Type objects, and are
+usually under 50 lines long. Note that if you plan on making a distinctly
+different layer type, it's best not to do it within this javascript file, but to
+create a new OpenLayers Layer Type (in javascript) - see the MapBox module for
+an example of a new OpenLayers Layer Type (`OpenLayers.Layer.MapBox`), which is
+entirely independent of the Drupal module.
