first import

This commit is contained in:
Bachir Soussi Chiadmi
2015-04-08 11:40:19 +02:00
commit 1bc61b12ad
8435 changed files with 1582817 additions and 0 deletions

View File

@@ -0,0 +1,36 @@
Current for 6.x-2.0-alpha2
This file contains the main API functions for OpenLayers and its sub-modules.
Please refer to the project page for more up to date information and
documentation:
* http://drupal.org/project/openlayers
# Advanced Help
Browsable documentation is available through the [Advanced Help
module.](http://drupal.org/project/advanced_help)
# Map Build Process
The parts to build a map - layers, behaviors, maps, and styles - are loaded
with menu loaders, like `openlayers_layer_export_load`. They should not be
loaded manually because menu loaders do the necessary instantiation and
cache-clearing.
In 2.x, layers, behaviors, and styles contain more logic for 'rendering
themselves' than before, but cannot completely exist on their own. The functions
that iterate over included layers, behaviors, and styles are in
`openlayers.render.inc`.
`openlayers_build_map` and `openlayers_render_map` are the two essential parts
of the actual map building and rendering, and are included in
`openlayers.module`.
The map building process does not directly deal with map data: in the case that
Drupal is rendering data (as in openlayers_views), this functionality is
encapsulated in the `render()` method of the layer type. See
`modules/openlayers_views` for an example of how this works.

View File

@@ -0,0 +1,124 @@
Current for 6.x-2.0-alpha6
# Creating a new OpenLayers Behavior from Scratch
First, you'll need to create a module. Of course, skip through this step if
there's already a module that exists to which this behavior will be added. But
if not, create a file called `modulename.info` with the contents
core = "6.x"
dependencies[] = "openlayers"
name = "modulename"
package = "OpenLayers"
project = "modulename"
In this case, you're creating a module just for this feature. So you'll need to
implement a hook to notify OpenLayers that your module can do something for it.
There's a hook called `hook_openlayers_behaviors` for this, and since your
module is called modulename, its implementation should be
`modulename_openlayers_behaviors`. A basic implementation would be
function modulename_openlayers_behaviors() {
return array(
'openlayers_behavior_mybehavior' => array(
'title' => t('My Behavior'),
'description' => t('Does something'),
'type' => 'layer',
'path' => drupal_get_path('module', 'modulename')
.'/includes/behaviors',
'file' => 'openlayers_behavior_mybehavior.inc',
'behavior' => array(
'class' => 'openlayers_behavior_mybehavior',
'parent' => 'openlayers_behavior',
),
),
);
}
Note the essentials here: this tells the OpenLayers module that there is a file
in `modules/modulename/includes/behaviors/` which implements a class called
`openlayers_behavior_mybehavior`. It isn't strictly necessary to create an
includes folder and a behaviors folder under it, but it's good practice so that
your module doesn't become cluttered.
So on to the PHP that this hook refers to: usually there's only a small amount
of PHP written for each behavior. On the first level, the file simply must
include a class that extends the class openlayers_behavior:
class openlayers_behavior_mybehavior extends openlayers_behavior {}
There'll be a little bit for this one, but it's not very functional - only
adding JavaScript code and declaring forms.
Here's what you'll write for this behavior:
class openlayers_behavior_mybehavior extends openlayers_behavior {}
function options_init() {
return array(
);
}
function options_form($defaults) {
return array(
'filteredlayer' => array(
'#type' => 'select',
'#options' => $this->map['layers'],
'#description' => t('Select layer to filter'),
'#default_value' => isset($defaults['filteredlayer']) ?
$defaults['filteredlayer'] : NULL
),
);
}
function render(&$map) {
drupal_add_js(drupal_get_path('module', 'mybehavior')
.'/includes/behaviors/js/openlayers_behavior_mybehavior.js');
return $this->options;
}
}
As you can see, there's an options_form method which is called when the list of
behaviors is generated for each map, and given a `$defaults` array if there
have already been values saved. It isn't required to implement this method,
although many behaviors will need it. And at this level - in the options_form,
you have access to the map object with $this - so you can get layers, styles,
and other parts of the map to play around with The `render(&$map)` function
is indeed required, since it is called for every behavior.
There's quite a bit of Javascript to write for this behavior:
/**
* Maptimeline Behavior
*/
Drupal.behaviors.openlayers_behavior_mybehavior = function(context) {
var data = $(context).data('openlayers');
var slider_div = {};
if (data && data.map.behaviors['openlayers_behavior_mybehavior']) {
behavior = data.map.behaviors['openlayers_behavior_mybehavior'];
layer = data.openlayers.getLayersBy(
'drupalID',
behavior.filteredlayer)[0];
// Do things with this feature, etc.
});
}
}
Note the essentials of this file: all of the functionality needed is contained
in a single function, `Drupal.behaviors.openlayers_behavior_mybehavior`. The
facts that the containing function is called `openlayers_behavior_mybehavior`
and that it receives a single argument, `context`, are essential, but besides
those restrictions, behaviors can contain any Javascript code whatsoever.
Behaviors are called after all layers and styles are added to the map and the
map is rendered.
This code demonstrates a few core concepts of behavior-writing:
* The OpenLayers [Map object](http://dev.openlayers.org/releases/OpenLayers-2.8/doc/apidocs/files/OpenLayers/Map-js.html)
is accessible via `$(context).data('openlayers').openlayers`
* The [jQuery Data function](http://api.jquery.com/jQuery.data/) is used in the
OpenLayers module to simplify variable scope and avoid the possibility of
memory leaks.

View File

@@ -0,0 +1,2 @@
This is maintained on Drupal.org at the following URL:
http://drupal.org/node/177400/release

View File

@@ -0,0 +1,46 @@
Current for 6.x-2.0-alpha3
Obviously there are many points at which advanced users will want to push the
limits of what the OpenLayers module can do. In many cases, these changes can be
make without any 'hacks' to the module, and before hacking, it is highly
recommended to think about ways that changes could be incorporated into the
module proper via patches.
# Performance
The largest performance hit of OpenLayers at the moment seems to be in the very
large size of the OpenLayers.js library. The real route to fixing this problem
is by narrowing down the set of components included in the Javascript file. In
order to do this:
## Manually
svn checkout http://svn.openlayers.org/trunk/openlayers/ cd openlayers/build
edit full.cfg or lite.cfg to include the components your map uses.
python build.py [yourcustomized.cfg]
This will produce a compacted, slimmed OpenLayers.js file.
After doing this, make sure to set the ImgPath and ThemePath in the OpenLayers
administration - these are per-map settings. The OpenLayers library guesses
the location of its style.css and images, so if you make a compacted
OpenLayers.js in an otherwise empty folder, it will fail in this task and have
blank images and a nonfunctional ZoomBox control (the red 'zooming box') will
not appear.
## Map Performance
Using multiple domain names for layers will [dodge the browser connection
limit](http://trac.openlayers.org/wiki/OpenLayersOptimization) and allow more
tiles to load in parallel. However, this has a bad interaction with the default
buffer setting, making tiles outside the viewport load first in many cases, so
buffer should be set to 0 if multiple urls are enabled.
# Custom Behaviors
If behaviors similar to those included are necessary, just clone the behaviors
and create a tiny new module that includes the copy. The same goes for layers,
etc.

View File

@@ -0,0 +1,61 @@
Using the OpenLayers Javascript from the OpenLayers module can present some
problems with rendering vector layers in IE.
The root cause of the issue:
Internet Explorer has a thing called VML: Vector Markup Language, which it uses
to draw graphics. VML is what you use in IE: canvas4ie is way slow, google maps
uses VML to draw routes, and OpenLayers uses it to draw vectors.
VML elements are styled by creating CSS-like styles in a namespace. OpenLayers
creates an ol: namespace and then creates styles like ol:line ol:circle, etc.
To do this, it has to access document.namespaces. Document.namespaces is not
always around: notably, you can't depend on it being around before
document.ready.
But, sometimes document.namespaces *is* around before document.ready and that's
the thing that messed up my worldview. So, the theory was, there are modes.
Something in HTML can prevent document.namespaces being filled in before
document.ready.
Here's how it goes.
### $( or $(document).ready()
* If there is a broken image on the page, then namespaces is not filled in.
* If the page has no broken images, then document.namespaces is accessible
### document.load()
* document.namespaces is always filled in.
### 31 stylesheets
IE cannot handle more than 31 stylesheets on a page at a time. This is clearly
the devil's work, but it persists beyond IE8. If there are 31 stylesheets and
you run an OpenLayers map, it cannot add another stylesheet to initialize its
VML namespace. Therefore, the map breaks. You must aggregate your CSS.
### The Fix
We can't move openlayers to document.load() because it is dependent on the
Drupal behaviors stack, that runs on document.ready(). We need to just define
document.namespaces before OpenLayers asks its VML renderer whether the current
browser is capable of rendering VML (a task it tries to complete by calling
!!(document.namespaces))
### Other Fixes
Adding a tag
<code><meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" /></code>
will allow IE8 to render vectors if it doesn't render them correctly on a normal
pageload. Note that this must be the first element inside the header tag.
### Image Opacity
The opacity of image pointers are created with IE filters, which do not function
correctly when combined with semi-transparent PNG images. Thus it is necessary
to set opacity of such elements to 1.0 in order for alpha-transparent PNG images
to appear correctly.

View File

@@ -0,0 +1,34 @@
Current for 6.x-2.0-alpha3
The OpenLayers module aims to add minimal abstraction in Javascript to what is
already provided by the [OpenLayers](http://openlayers.org/) Javascript library.
However, it does create certain structures that may not be immediately obvious.
# Data Storage
The module stores all settings initially under Drupal.settings.openlayers. It
does this in a slightly modified way if your server supports native JSON writing
- this basically means that, instead of using Drupal to encode the settings
array, it uses a PHP extension (written in C). This greatly increases
performance for displaying many points on maps.
# Keeping Track of Maps
The OpenLayers map object, which contains pointers to all layers, etc., is
stored with the [jQuery data() method](http://api.jquery.com/jQuery.data/),
which provides the phenomenal convenience of storing arbitrary data within the
DOM itself. This means that the map object is attached to the openlayers-map-0,
or so on, div element in your page. So, to access it, one could use a line like
$('#openlayers-map-0').data('openlayers')
In FireBug, Safari, or Chrome.
Note that the 2.x branch strives to not duplicate map information: it exists in
the Drupal settings array and then is transformed into a map object, but after
that point, the canonical location for data about maps is in the map object.
This is for purposes of both flexibility, since the map object lets developers
access objects by better getter methods, and for the purpose of keeping
OpenLayers behaviors and layer initialization code less tied to Drupal than
before.

View File

@@ -0,0 +1,29 @@
Current for 2.x
# KML
Many users find it necessary to include KML files on their websites, and often
KML files are located on remote servers; especially dynamic KML. However, the
core of the [XMLHttpRequest](http://en.wikipedia.org/wiki/XMLHttpRequest)
object, the Javascript convenience that allows AJAX to happen, prevents requests
across domains.
This means that a site
http://www.hello.com/
cannot load KML from
http://world.com/
Without a special workaround.
# Proxy Host
For this, there is a special setting in every map called "Proxy Host." It is
in the 'General information' tab, at the bottom of the page. You can use any of
a number of [PHP
proxies](http://www.google.com/search?sourceid=chrome&ie=UTF-8&q=php+proxy) for
this purpose, or you can use the [proxy
module](http://drupal.org/project/proxy), which integrates with Drupal.

View File

@@ -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.

View File

@@ -0,0 +1,11 @@
Current for 6.x-2.x
# Filtering map views
The best way to handle filtering the points on maps is to use normal OpenLayers
exposed filters, whose input is passed through to the underlying Data
view. If there are no other views on the same page, like tabular listings,
that can 'own' and display the exposed filters, it is recommended to make the
filters blocks via the views interface and make sure that they appear on
the specified page with the block system or context module.

View File

@@ -0,0 +1,65 @@
Raw layers are an addition to OpenLayers post-alpha7 which allow users to
manually add points to a layer type. In comparison to the layer_type
method of pulling in custom data, this allows you to 'push' data into the
layer data array itself. In any case where reusability is a priority,
layer_types should be utilized (as documented in LAYER_TYPES.txt). However,
this is a quick method for success that may be more accessible to more
developers.
A brief, example-only implementation of an arbitrary layer is below.
/**
* Implementation of hook_ctools_plugin_api().
* Required to provide layers
*/
function geolocator_ctools_plugin_api($module, $api) {
if ($module == "openlayers") {
switch ($api) {
case 'openlayers_layers':
return array('version' => 1);
}
}
}
/**
* One can have the 'features' => element point to a function
* or be built on the fly within the _layers method. However,
* close attention must be paid to ctools caching in order to
* insure that dynamic data stays dynamic
*/
function geolocator_openlayers_layers() {
$layers = array();
$layer = new stdClass();
$layer->api_version = 1;
$layer->name = 'afghanistan';
$layer->title = 'One Point on Afghanistan';
$layer->description = '';
$layer->data = array(
'layer_type' => 'openlayers_layer_type_raw',
'projection' => array('900913'),
'features' => array(
array(
"wkt"=> "POINT(65 33)",
"projection"=> "4326",
"attributes"=>
array(
"name"=> "Afghanistan",
"description"=> "248"
)
)
)
);
$layers[$layer->name] = $layer;
return $layers;
}
/**
* map_preprocess_alter allows one to add a new layer to a map
* before layers are rendered and data is pulled from them.
*/
function geolocator_openlayers_map_preprocess_alter(&$map) {
$map['layers']['afghanistan'] = 'afghanistan';
$map['layer_activated']['afghanistan'] = 'afghanistan';
$map['layer_switcher']['afghanistan'] = 'afghanistan';
}

View File

@@ -0,0 +1,13 @@
Documentation for upgrading is managed on Drupal.org.
For Upgrading from 6.x-2.x -> 7.x-2.x:
==========================================
* http://drupal.org/node/1136810
For Upgrading from 6.x-1.x -> 6.x-2.x:
==========================================
* http://drupal.org/node/714366

View File

@@ -0,0 +1,283 @@
<?php
/**
* @file
* Hooks provided by the OpenLayers suite of modules. This file allows
* hooks to be documented automatically with Doxygen, like on api.drupal.org.
*
* @ingroup openlayers
*/
/**
* OpenLayers Map Preprocess Alter
*
* Map array alter. Fired before processing the array, and
* before checking for errors. The whole array is passed
* along and will allow you to alter it in any way. This
* is a good place to alter the map, if the other hooks
* do not provide the functionality you need.
*
* @param $map
* Map array
*/
function hook_openlayers_map_preprocess_alter(&$map = array()) {
// Do something to the $map
}
/**
* OpenLayers Map Alter
*
* Post-processing Map array alter. Fired after processing the array, and
* before checking for errors. The whole array is passed
* along and will allow you to alter it in any way. Adding behaviors,
* pre-defined layers here will not work. This is good for minor tweaks
* after the map has been processed.
*
* @param $map
* Map array
*/
function hook_openlayers_map_alter(&$map = array()) {
// Do something to the $map
}
/**
* OpenLayers Layer Types
*
* Provides information on layer types. This is a CTools plugin. Please
* see LAYER_TYPES.txt in the module for more information.
*
* @return
* Return a nested associative array with the top level
* being a unique string identifier key which corresponds to the
* layers' types. The next level being an array of key/value
* pairs:
* - "description":
* - "layer_type":
*/
function hook_openlayers_layer_types() {
// Take from openlayers.layer_types.inc
return array(
'openlayers_layer_type_google' => array(
'title' => t('Google'),
'description' => t('Google Maps API Map'),
'layer_type' => array(
'path' => drupal_get_path('module', 'openlayers') .'/includes/layer_types',
'file' => 'google.inc',
'class' => 'openlayers_layer_type_google',
'parent' => 'openlayers_layer_type',
),
),
);
}
/**
* CTools Registration Hook
*
* IMPORTANT:
*
* In order to support styles, maps, and layers in an external module,
* one must notify the CTools module that that module provides implementations
* of the hooks for styles, maps, and/or layers.
*
* This function is just an example implementation of
* hook_ctools_plugin_api() and should be alter according to
* your module's name.
*
* @param $module
* Name of a module that supports CTools exportables.
* @param $api
* Name of the kind of exportable supported.
* @return
* If $module is 'openlayers', and $api is a type of exportable that
* your module provides, and you are using Openlayers 2.x, then
* return array with the following values:
* - version => 1
*/
function openlayers_example_ctools_plugin_api($module, $api) {
if ($module == "openlayers") {
switch ($api) {
case 'openlayers_maps':
return array('version' => 1);
case 'openlayers_layers':
return array('version' => 1);
case 'openlayers_styles':
return array('version' => 1);
}
}
}
/**
* OpenLayers Layers
*
* This hook tells OpenLayers about the available layers
* that can be used by name in maps.
*
* Ensure that you are telling CTools about this as well.
* @see openlayers_example_ctools_plugin_api().
*
* Please note, that to support translation for exportable
* code for potx extraction, you should include separate code
* of translatable string.
*
* @return
* Return an associative array with index being a unique string
* identifier, and simple objects with the following properties:
* - "api_version":
* - "name":
* - "title":
* - "data":
*/
function hook_openlayers_layers() {
// Taken from openlayers.layers.inc
$layers = array();
$layer = new stdClass();
$layer->api_version = 1;
$layer->name = 'google_satellite';
$layer->title = 'Google Maps Satellite';
$layer->description = 'Google Maps Satellite Imagery.';
$layer->data = array(
'isBaseLayer' => TRUE,
'type' => 'satellite',
'projection' => array('900913'),
'layer_type' => 'openlayers_layer_type_google',
);
$layers[$layer->name] = $layer;
return $layers;
// Extra code to support potx extractors
$potx = array(
t('Google Maps Satellite'),
t('Google Maps Satellite Imagery.'),
);
}
/**
* OpenLayers Behaviors
*
* This hook tells OpenLayers about the available behaviors
* that can be used in maps.
*
* Ensure that you are telling CTools about this as well.
* @see openlayers_example_ctools_plugin_api().
*
* @return
* Return a nested associative array with the top level
* being a unique string identifier, and the nested array
* containing the following key/pairs:
* - "title":
* - "description":
* - "file":
* - "type":
* - "behavior":
*/
function hook_openlayers_behaviors() {
// Taken from openlayers.behaviors.inc
return array(
'openlayers_behavior_attribution' => array(
'title' => t('Attribution'),
'description' => t('Allows layers to provide attribution to the map if it exists.'),
'type' => 'layer',
'path' => drupal_get_path('module', 'openlayers') .'/includes/behaviors',
'file' => 'openlayers_behavior_attribution.inc',
'behavior' => array(
'class' => 'openlayers_behavior_attribution',
'parent' => 'openlayers_behavior',
),
),
);
}
/**
* OpenLayers Styles
*
* This hook tells OpenLayers about the available styles
* that can be used in maps.
*
* Ensure that you are telling CTools about this as well.
* @see openlayers_example_ctools_plugin_api().
*
* @return
* Return an associative array with index being a unique string
* identifier, and simple objects with the following properties:
* - "api_version":
* - "name":
* - "title":
* - "data":
*/
function hook_openlayers_styles() {
// Taken from openlayers.styles.inc
$styles = array();
$style = new stdClass();
$style->api_version = 1;
$style->name = 'default';
$style->title = t('Default style');
$style->description = t('Basic default style.');
$style->data = array(
'pointRadius' => '5',
'fillColor' => '#FFCC66',
'strokeColor' => '#FF9933',
'strokeWidth' => '4',
'fillOpacity' => '0.5'
);
$styles[$style->name] = $style;
return $styles;
}
/**
* OpenLayers maps
*
* Define map objects.
*
* @return
* Return an associative array with index being a unique string
* identifier, and simple objects with the following properties:
* - "api_version":
* - "name":
* - "title":
* - "data":
*/
function hook_openlayers_maps() {
// Taken from openlayers.maps.inc
$default = new stdClass();
$default->api_version = 1;
$default->name = 'default';
$default->title = t('Default Map');
$default->description = t('This is the default map that comes with the OpenLayers module.');
$default->data = array(
'projection' => '900913',
'width' => 'auto',
'default_layer' => 'osm_mapnik',
'height' => '400px',
'center' => array(
'initial' => array(
'centerpoint' => '0,0',
'zoom' => '2'
)
),
'options' => array(
'displayProjection' => '4326',
'maxExtent' => openlayers_get_extent('4326'),
),
'behaviors' => array(
'openlayers_behavior_panzoombar' => array(),
'openlayers_behavior_layerswitcher' => array(),
'openlayers_behavior_attribution' => array(),
'openlayers_behavior_keyboarddefaults' => array(),
'openlayers_behavior_navigation' => array(),
),
'layers' => array(
'osm_mapnik' => 'osm_mapnik',
)
);
return array('default' => $default);
}