LAYER_TYPES.txt in Openlayers 6.2

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.