PT Commons

h1. Basic Mapping Documentation

Modules to be installed

* addressfield

* ctools

* geocoder

* geofield

* geophp

* openlayers

* views

* proj4js

OpenLayers javascript libraries installed in sites/all/libraries.

The data format for mapping with OpenLayers in Drupal is handled by content types with particular data type fields associated with those content types.  We've covered two field data types, which allow us to map points, more specifically longitude and latitude.  Those fields are Postal Address field and Geofield.

If we use postal address field, we also have to use geofield.  First add the postal address field; there's only a single widget option, Dynamic address form.  In the configuration, set this field to be required, filter to particular countries if that's needed for data entry.  The rest of the defaults should be fine.  Then add a geofield to the content type in order to transform the entered address into a longitude and latitude.  The widget for this field needs to be set to Geocode from another field.  Set this field to be required, choose the address field as the Geocode from field that will be transformed into geolocation data, and finally choose the geocoding service.  We used Google during the demo, but there are privacy issues to be discussed around actual data.  When entering data, only the address field appears on the edit form, but when viewing the entered content the longitude and latitude appear as well.

If we use just the geofield, there are several options.  We've covered the map-based data entry option.  When adding the geofield to the content type, select Openlayers Map as the widget.  Set the field to be required and adjust the default map center and zoom for data entry if that's needed.  The rest of the defaults should be fine to accept.  When editing the content, the map appears for the user to enter the data, but only the longitude and latitude appear when viewing it.

The geofield supports other types of data, such as direct input of longitude and latitude and two dimensional shapes.

With some data now entered as content in Drupal, we need to create a map. Creating a map with OpenLayers in Drupal requires three components

# Aggregating the data and transforming from the Drupal format to standardized mapping format

# Creating the map that assembles base and overly layers

# Creating the page where the map is rendered

# Mapping with OpenLayers in Drupal uses Views to aggregate the data.

** Create a new view.  Name it and select content type from the Content dropdown, select the particular content type from the above which we've added all out data to and select the sort to be unfiltered.  Note that the latter is only a minimal query optimization setting.  Since we're returning the data and mapping it, the order in which they're selected from the database is irrelevant and should speed up return from th database.  This will be more important with larger data sets.  Deselect the automatic creation of Page.

Click Continue & Edit.  

** Under the Fields section, the Title field should be listed.  We need to add at least the field with the geocoded data, our longitude and latitude data in the above example cases.  The options for this field will ask what kind of formatter do we want to use; WKT (Well Known Text) should be selected.  The Data options should be to use full geometry.  We can also add a description field if we've used that for some of the data entry.  Drupal automatically adds a body field that can be used for the description, but other description fields might be needed and can be handled.  

** Once we've added our field with geocoded data, and possibly our description field, click to + Add a new display type.  Choose the OpenLayers Data Overlay.

** Under Format click Unformatted List and select the option OpenLayers Vector Data Overlay.  Click Apply.  The next screen will map the Drupal content type fields to the OpenLayers Data fields.  This mapping is where the Drupal formats are transformed into the standardized map formats.  For WKT Field select the geocode field that should be in the dropdown list.  For Title and Description, select those as well if needed.  Then apply and save the View.

# The OpenLayers modules provides several example maps that we're going to clone and configure for the map we want to create.  Under Structure > OpenLayers > Maps, there should be a list of the example maps (and any other maps we've created in the past).  Click the down arrow in the Operations column for the map we want to clone and click the Clone option.  

** Rename the map, including the machine name.  

** The Center & Bounds tab allows us to set the center and zoom of the map as we want it to render.  

** The Layers & Styles tab allows us to set the different layers we want to make available on the map.  The cloned map should include preselected base layers.  Multiple base layer options will allow the end-user to select the base over which the mapped data is rendered.  The overlay layers needs to include the layer we created in Step 1 above.  Note that it's possible include multiple layers (which is a data organization question) and give the user the option to turn layers on and off.  It's also possible to style each layer with different colors, point representations, etc.

** The Behavior tab allows the configuration of different features we want to add to the map, like zooming features, hover and tooltip information pop ups, clustering, etc.

** Click Save when all the configuration is done.

# OpenLayers with Drupal also uses Views to render the map we just created in Step 2 onto a page that renders the enabled base and overlay layers into a single map that the user can interact with.  This can be done with either a completely separate view or by adding a Page display to the data aggregation view we created in Step 1.

** To use a completely separate view

*** Add a new view, deselect the automatic creation of a Page, the rest of the options don't matter because we're going to be overwriting everything when we edit.  Click Continue & Edit.  

*** Click the + Add dropdown under display.  Select Page.  

*** Click Unformatted List and select the OpenLayers Map option.  The configuration will ask which map to use; select the map we created in Step 2.

*** Click the / under Path and give it a URL alias where the map should be rendered.

*** Click Save.

** To use the same view

*** Open the data view and click the + Add dropdown under display.  Select Page which should add a second display to the view.  

*** Click Unformatted List and select the OpenLayers Map option.  *YOU MUST SELECT TO APPLY THIS TO _This page (override)_ OTHERWISE THE DATA AGGREGATION VIEW WILL BE CHANGED AND EVERYTHING WILL BREAK.* The configuration will ask which map to use; select the map created in Step 2.

*** Click the / under Path and give it a URL alias where the map should be rendered.  

*** Click Save.

The map should now be rendered at the path given in the last step.