Download the latest stable release of the Geofield module to your site’s modules directory.

Download the latest stable release of the Libraries module to your site’s modules directory. The Libraries module is used by Drupal modules like Geofield that require a third-party library or plug-in.

If it is not already there, create a libraries directory inside your Drupal installation’s sites/all directory.

Download the geoPHP library (alternatively, the git repository can be cloned, or it can be downloaded as a zip file from the project’s github page).

Extract the downloaded geoPHP library and place it inside sites/all/libraries. The file should now show in your directory structure as sites/all/libraries/geoPHP/geoPHP.inc.

Enable the Geofield and Libraries modules at admin/modules. Neither of these modules require any further configuration or permissions.

From the Content types page, add a new content type at admin/structure/types/add.

Enter User Group as the Name.

Enter A local Drupal user group as the Description.

Change the “Title field label” to Group name.

All other options can remain as default for now. Click the “Save and add fields” button.

You are now taken to the “Manage fields” page for this content type at admin/structure/types/manage/user-group/fields. The third field listed should be “Body.” Click the “edit” link to change this.

Change the “Label” field from Body to Group description. All other fields can stay with the default values. Click the “Save settings” button.

On the “Manage fields” page, go to the “Add new field” row. Enter Group location as the Label and group_location as the Field name. In the “Select a field type” drop-down, choose “Geofield.” In the Widget drop-down choose “OpenLayers map.” Your configuration should now look like Figure 3-1.

Figure 3-1. Configuring the user group content type

Click the Save button at the bottom of the page to create this field.

You are first taken to the field level settings; there is no further configuration for this widget, so click “Save field settings” on the next screen.

On the final screen, tick the “Required field” checkbox so that a location has to be set for this content type. Enter some useful Help text, too: Click on the map to set the location for this group. There is currently just one option in the “OpenLayers Map” drop-down (Geofield Widget Map). As we go through the exercises in later chapters, more maps will be added to this list.

It is possible to set a default location for nodes of this content type by clicking on the map in the “Default value” section, but this is not useful for this example. It is also possible to change the “Number of values” for the location field, but leave this set to 1 for this example. Click the “Save settings” button.

Create a sample “User Group.” From the “Add Content” page at node/add, add a “User Group.” Enter the name of the group (e.g., New York City). Enter a description for the group. Zoom in on the map and click to set the location of the group. This should look something like Figure 3-2.

Figure 3-2. Adding content

Save the node.

When viewing this node, you’ll see the location displaying something like “POINT (-73.9987036058 40.7345513658).” This is the location in Well Known Text (WKT) format, as described in Data Types. Unless you are a robot, this display isn’t useful when searching for your local Drupal user group. To see what other display options are available, go to the “Manage Display” page for the User Group content type at admin/structure/types/manage/user_group/display.

In the “Format” column for the “Group location” field change the display from “Well Known Text (WKT)” to “OpenLayers.”

Click on the cog symbol on the right side to open the configuration options for the field display. Again, at this point, the only available map is the one that comes with the Geofield module for this purpose, so select “Geofield Formatter Map.” For the data option select “Use full geometry.” It should look as shown in Figure 3-3. Click “Update” to save your settings, then click “Save.”

Figure 3-3. Configuring Geofield display settings

Go to the content management page at admin/content/node and view the “User Group” content that you have just created. The location should now be shown as a dot at the center of a map, as shown in Figure 3-4.

Figure 3-4. A location displayed on a map

Download the latest development release of the Location module to your site’s modules directory.

Enable two modules at admin/modules: the Location and Location CCK modules.

Configure permissions for the Location module at admin/people/permissions#module-location. The first three permissions should only be assigned to the Administrator role, but the “Submit latitude/longitude” permission will need to be given to the Authenticated User role. Click the “Save permissions” button.

No changes are needed on the Location module configuration page at admin/config/content/location.

The more important configuration page is the Geocoding options tab at admin/config/content/location/geocoding. Geocoding is the process of turning some text (such as an address) into numerical spatial information (such as a latitude and longitude). It will be discussed in more detail below in Geocoding.

The first field on the form sets how accurate we require geocoding to be. For our example, we are mapping the location of Drupal businesses, so it is quite important to know where these businesses are. However, people are not going to be using our maps to drive or walk to the location. To require a higher level of accuracy than the default, change the setting to “Town.”

The second group of choices are which geocoding service to use for every country in the world. Not every country has a service that can geocode an address (e.g., North Korea doesn’t), but for almost every country that does, Google is the only choice. Unfortunately you have to manually select Google Maps for each country, so do this for every country that you care about. For the United States and Australia you also have the choice of using Yahoo!’s geocoding service; for Canada there is the option of GeoCode.ca.

After you click the “Save configuration” button, you will see a “Configure parameters” link next to each country for which you have enabled geocoding. Click on one of these links to bring up the form to enter the Google Maps API Key. Thankfully this API Key only needs to be entered once; it does not need to be repeated for each country. Go to the Google Maps API Sign Up page to get the key.

Read the terms, particularly the usage limits, as these can have a significant implication for your website if you expect high traffic volumes or if you are using the maps on an intranet or other site that is not accessible for free by the public.

Tick the box and enter the URL for your site. It is best to enter the domain without the www (e.g., http://mappingdrupal.com). If you have a development or local version of your site, this API key will work on subdomains of this URL (e.g., http://staging.mappingdrupal.com or http://local.mappingdrupal.com), but the API key will not work on other domains (e.g., http://localhost/mappingdrupal or http://mappingwithdrupal.com). You will need to sign up for a different API key for those other domains.

Copy your new API Key (the long string of letters and numbers) to the “Google Maps API Key” field on your site and click the “Save configuration” button.

From the Content types page, add a new content type at admin/structure/types/add.

Enter Drupal Company as the Name.

Enter A Drupal development company as the Description.

Change the “Title field label” to Company name.

All other options can remain as default for now. Click the “Save and add fields” button.

You are now taken to the “Manage fields” page for this content type at admin/structure/types/manage/drupal-company/fields. The third field listed should be “Body.” Click the “edit” link to change this.

Change the “Label” field to Company description. All other fields can stay with the default values. Click the “Save settings” button.

On the “Manage fields” page, go to the “Add new field” row. Enter Company location as the Label and company_location as the Field name. In the “Select a field type” drop-down, choose “Location.” In the Widget drop-down, choose “Location Field.”

Click the “Save” button at the bottom of the page to create this field.

The next screen that comes up is the Field settings for the Company location field. This determines both what information will be collected when someone creates a new Drupal company, and also what information will be displayed about that company when someone views the site.

Under “Collection settings”, change the Collect drop-down for “Location name” to “Do not collect.” We are using the title field for this information. Leave “Street location,” “Additional,” “Country,” and “Coordinate Chooser” set at “Allow.” Change “City,” “State/Province,” and “Postal code” to “Allow.” There is also a field to set a default value for each of these fields, and to use the “Force Default” option to only allow users to enter an address for a particular country, state, etc.

The Display Settings section allows certain fields to be hidden. Leave these all visible for now. Click the “Save field settings” button.

On the final screen, tick the “Required field” checkbox so that a location has to be set for this content type. Click the “Save settings” button.

Create some “Drupal Company” content. From the “Add Content” page at node/add, add a “Drupal Company.” Enter the name and description of a company, and a full street address. Click the “Save” button. You should now see something similar to Figure 3-5. If you do not see the address, check the modules page at admin/modules to make sure that you did not accidentally enable the Node Location module (see Warning).

Figure 3-5. A Drupal Company

It is useful to see the latitude and longitude below the address so that we know that geocoding has been successful, but we do not need to display this to people visiting our site. In this example we do not want to show the “See Map” link either. Go to the “Manage fields” page for the content type at admin/structure/types/manage/drupal-company/fields/field_company_location and edit the “Company location” field. At the very end of this form, under the “Display Settings” section, check the “Map link” and “Coordinates” checkboxes to prevent these from being displayed. Click the “Save settings” button to save your changes.

It provides a clickable map for entering the location of a node.

It provides a map to display a node’s location.

It integrates with the Views module to display the results of a View on a Google map.

There is not yet a stable release of the GMap module for Drupal 7, but the development version works fine. Download the latest development release to your site’s modules directory.

Enable two modules: the GMap and GMap Location modules at admin/modules. There are some permissions that can be set for these modules, but they apply to components that are not used by these examples.

Go to the GMap configuration page at admin/config/services/gmap. You will get a JavaScript error about the Google Maps API Key. Click OK to dismiss this message, and enter the same API Key that you entered earlier when configuring the Location module in Step 10. Leave all the other settings at their default value for now and scroll to the bottom of the page to click the “Save configuration” button.

When the page reloads after saving, you should not get the JavaScript error, and you should see a small Google Map of southern Europe and northern Africa. If you do not see these things, check that you have entered the API Key correctly.

Go to the Location module’s configuration page at admin/config/content/location/main and tick the “Use a Google Map to set latitude and longitude” checkbox. This will allow users to click on a map to set the business’s location instead of (or in addition to) entering an address. Click the “Save configuration” button.

Create some more “Drupal Company” content. From the “Add Content” page at node/add add a “Drupal Company.” Enter the name and description of a company. For this example, we will create a virtual company that does not have an office address, and instead has a PO Box like, “PO Box 23505, Brooklyn, NY 11202.” This address, when geocoded by Google, shows up in downtown Brooklyn. To see this, click the “Save” button.

Edit the company that you just saved. On the small map, zoom in until you can see the streets. The business owner of this company wants to be associated with downtown Manhattan, so click the map in that location and notice how the latitude and longitude fields change. (There are two pairs of latitude and longitude: one showing the current coordinates for the node under the heading “Current Coordinates”; and the other pair, further down the form, appearing as two text fields. The latter are the ones that change when you click a new location on the map.) Click the “Save” button again. The business still has the same address, but if you edit the business again, you will see that the location on the map is now lower Manhattan, where you clicked, and the “Source” for the current coordinates is now “User-submitted” instead of “Geocoded (Exact).”

As you edit the business and look at the map, you have found it unhelpful because it is a small map showing most of the world. To change this, go to the Location module’s configuration page again at admin/config/content/location/main. Toward the bottom of this page is a field titled “Location chooser macro,” which contains [gmap]. This is the GMap module’s way of setting up behaviors and display options for a map. The current setting uses the default values set on the GMap module’s configuration page, admin/config/services/gmap. The easiest way to create a new macro is to use the module provided for this purpose.

Go to the module page at admin/modules and enable the GMap Macro Builder module. Enable permissions for the roles that will need to configure map defaults at admin/people/permissions#module-gmap_macro_builder—usually just the “Administrator role.”

Go to the “Build a GMap macro” page at map/macro. The map at the top of this page is the one that will be set by the macro that you are creating. The first section is the “Overlay editor.” When someone is editing a location, the Overlay editor determines stuff like the colors of the map pins and lines. The defaults are fine for now.

The next section of the form contains the more important settings. If you are creating a website that has a particular geographic focus, you probably want a map that defaults to a location in that area, rather than one that shows the whole world. Enter a location that represents this focus in the “Address” field (for example, New York, NY). When you click or tab out of this field, the location will be geocoded and the latitude and longitude will be updated below, in the field labeled “The Latitude and Longitude of the centre of the map.”

If you scroll back to the top of the page, you will now see a small map centered on the location you entered. The map is still very zoomed out, so change this in the field labeled “The current magnification of the map.” This defaults to 3, so increase it and look at the updated map at the top of the page to see if the new value works.

We now have the map showing a more useful location, but it is still very small. To change the size of the map, we need to update the “Map width” and “Map height” fields. For a map that is being used to set a location, we want to use the full space available on the page, so change the width to 95%. Percentage heights are not well supported across browsers, so change the height to 300px.

As you have gone through these steps, you may have noticed that the last field on the page, “Macro text,” has been changing each time you changed a value. It should now read something like:

[gmap zoom=9 |center=40.7143528,-74.0059731 |width=95% |height=300px |control=Small |type=Map]

Copy this macro (it can not be saved) and go back to the Location module’s configuration page at admin/config/content/location/main. Paste the macro you created into the “Location chooser macro” field. Click the “Save configuration” button.

Now, if you create a new Drupal company, you will see that the map is much larger, it is showing at a more useful scale, and it is centered on the location that you set. If you edit an existing Drupal company, you will see that the map is centered on that company’s location, but that the zoom level is the same as you set in the macro, and the width and height of the map are also as you set.

Download the latest stable release of the Addressfield module to your site’s modules directory.

Enable the Address Field module at admin/modules. There are no configuration or permissions changes needed for this module.

From the “Content types page,” add a new content type at admin/structure/types/add.

Enter Event as the Name.

For the Description, enter A Drupal event.

Change the “Title field label” to Event name.

All other options can remain as default for now. Click the “Save and add fields” button.

You are now taken to the “Manage fields” page for this content type at admin/structure/types/manage/event/fields. The third field listed should be “Body.” Click the “edit” link to change this.

Change the “Label” field to Event details. All other fields can stay with the default values. Click the “Save settings” button.

On the “Manage fields” page, go to the “Add new field” row. Enter Event location as the Label and event_location as the Field name. In the “Select a field type” drop-down, choose “Postal address.” In the Widget drop-down, choose “Dynamic address form” (the only choice).

Click the “Save” button at the bottom of the page to create this field.

On the screen that comes up there are no further field settings, so click the “Save field settings” button.

The final configuration page for this field is where the field is configured for the Event content type at admin/structure/types/manage/event/fields/field_event_location. Set it to be a required field by checking the “Required field” checkbox.

Under the “Available countries” field, to enable all countries leave it at the default with nothing selected, or else select a few countries.

The “Format handlers” checkboxes allow different fields to be shown in addition to the default country-specific address form. For example, if you are using the address for shipping a product to customers, you might want to enable the Name and Organization fields. In this example just leave it as the default “Address form.”

It is possible to set a default value for the address or to allow multiple addresses (for example, for different invoicing and shipping addresses), but in this example just leave all the values unchanged.

Click the “Save settings” button.

Create some “Event” content at node/add/event. Enter the name and description of an event. Try changing the country in the drop-down and see how the address form changes. For the United States, there is a drop-down field labeled “State” and a field labeled “ZIP Code.” For Canada, the state field becomes “Province” and the ZIP Code becomes “Postal Code.” The United Kingdom has the same “Postal Code” field but the “State” field is a text field rather than a drop-down. The United States and Canada are the only countries with a list of states or provinces included with the Addressfield module.

For comparison, create some “Drupal company” content at node/add/drupal-company. With the United States as the country, start typing the name of a state and notice how it autocompletes. Most countries have states or provinces that will autocomplete like this. However notice how the labels of the fields do not change; it is always “State/Province” and “Postal Code.”

This comparison shows an important difference between the two approaches (Location and GMap versus Geofield and Addressfield). Location and GMap give you more functionality just by installing the modules. OpenLayers, Geofield, and Addressfield give you less ready-made functionality, but they try to be more semantically correct with the data, and they provide a pluggable API to add the data that you need. For example, if there is a country for which you need a list of states, you can look at the addressfield_example module that is included inside the Addressfield module to see how to do this (the example shows how to add states for Switzerland).

Download the latest release of the Geocoder module to your site’s modules directory. At the time of writing there is no stable release, so download the latest development release.

Enable the Geocoder API module. There are no configuration or permissions changes needed for this module.

On the “Manage fields” page for the Event content type at admin/structure/types/manage/event/fields go to the “Add new field” row. Enter Event geo as the Label and event_geo as the Field name. In the “Select a field type” drop-down, choose “Geofield.” In the Widget drop-down, choose “Geocode from another field.”

Click the “Save button” at the bottom of the page to create this field.

On the next screen that comes up, there are no further field settings, so click the “Save field settings” button.

This field will never be visible to a user of your website when they are creating events, so many of the settings on the final configuration page at admin/structure/types/manage/event/fields/field_event_geo are unnecessary. There are two important fields, though.

Under “Geocode from field,” select “Event location” (the field that contains the address).

Under the “Geocoder” drop-down, select “Google Geocoder.”

Click the “Save settings” button.

The final step is to set the display for this field. Rather than displaying the latitude and longitude, the location of the event should be displayed on a map. Go to the “Manage Display” page for the Event content type at admin/structure/types/manage/event/display. For the “Event geo” field, change the Label to “<Hidden>”. Change the Format to “OpenLayers.” Click on the cog on the right side to configure the “OpenLayers display” widget. In the “OpenLayers Preset” drop-down, select “Geofield Formatter Map.” In the “Data options” drop-down, choose “Use full geometry.”

Click the “Update” button to save the field display widget, and then click the “Save” button to save all the display settings.

Download the latest release of the Date module to your site’s modules directory.

Enable the Date, Date API, and Date Popup modules. There are no important permissions or other configuration changes needed for these modules.

Go back to the “Manage fields” page for the Event content type at admin/structure/types/manage/event/fields and go to the “Add new field” row. Enter Event date as the Label and event_date as the Field name. In the “Select field” drop-down, choose “Date.” In the Widget drop-down, choose “Pop-up calendar.”

Click the “Save button” at the bottom of the page to create this field.

The default field settings should be fine, so just click the “Save field settings” button. The default values on the next page are fine too, so click “Save settings.”