Geo Mashup Plugin Documentation (Stable Version)

You should find what you need to use the plugin here. If you have questions or need help, try searching or posting in our Google Group. Please submit an issue if you run into problems, or would like to request a feature.

System Requirements

As of version 1.0.6, WordPress 2.3 or higher is required.

Installation

1. If you have the Geo Plugin installed, deactivate it.
• Note: If your templates call any of the Geo tags, you'll have to remove these or replace them with GeoMashup calls.
2. Download the latest Geo Mashup archive.
3. Extract the geo-mashup folder from the archive. The folder name must be 'geo-mashup'.
4. Upload this entire folder to your wp-content/plugins directory (not just the files, the whole geo-mashup folder).
5. In the WordPress Admin Panel, activate the Geo Mashup plugin on the Plugins tab.
6. Visit the Options | Geo Mashup tab to configure the plugin.

Upgrading

In general you can follow the installation instructions, overwriting existing files. It shouldn't hurt to deactivate the plugin first, but it doesn't seem to be necessary.

You should update your Geo Mashup Options once to add any new values. This is important for the 1.0 release.

If you have a custom-marker.js file, you'll need to rename it to custom.js and make a few changes. See custom-sample.js for an example.

Configuration

The Geo Mashup plugin provides some configuration options for customizing a Google Maps mashup page on your blog. Find these options in the Administration Panel under Options | Geo Mashup.

Quick Start: Adding a Geo Mashup Page

1. Save a location for at least one post, or the map will center by default at (0,0) off the coast of Africa.
2. Get your Google Maps API key and enter it in the options.
3. Create a new page with the tag <!--GeoMashup--> in the page content.
• If you are using the rich text editor, you'll have to use the Code tab to enter this tag. It won't show up in the Visual editor.
• If you want the category name to appear for category queries, enter the tag <!--GeoCategory--> where it should appear.
• If you want to create an area for the full post to be shown, you can enter the tag <!--GeoPost--> where it should appear.
4. Choose the map page in the options.
5. View the page and play with your new blog map!

Domain Name

You can get away with skipping this section, but this is an issue that all websites have to deal with. Here is a solution all nicely explained for you, then you can rest at ease that your site works for everyone. If you are getting a blank gray map with no markers, this may solve the problem.

Your domain name (cyberhobo.net, for me) is important to this plugin in a few ways. The most common issue is that most websites will work with either the bare domain name (http://cyberhobo.net), or with a www. prefix (http://www.cyberhobo.net/). This plugin will not work with both names unless you follow these guidelines:

1. Register your Google Maps API key for your bare domain name (like http://cyberhobo.net). This key will also work with a www., and will work for all pages on your site.
2. Decide whether you want to use the www. prefix or not, and use the www-redirect plugin to seamlessly direct visitors to your site to the domain you choose.
3. Update the WordPress address URL and Blog address URL settings in the WordPress options to use your chosen domain name. You're all set.

Why is this important to the Geo Mashup plugin? AJAX. Geo Mashup uses this technology to communicate with your site behind the scenes to get markers and posts. Most browsers these days only allow this kind of communication with the same domain as the site being visited. If a visitor comes to cyberhobo.net, and the Geo Mashup plugin tries to communicate with www.cyberhobo.net, it's considered a security violation. Such is modern life. Until browsers behave differently, we have to accommodate them.

Customizing

In the geo-mashup directory is a file named custom-sample.js. Rename this to custom.js and edit it to use your own icon (see the Google API documentation for more). There is an example of how to recenter the map. You can also draw things and do other kinds of customization in this file using the Googe Maps API.

Adding a "show on map" link to posts with a location

See the <?php GeoMashup::show_on_map_link()?> template tag below.

Using Categories

If you have a list of category links in your sidebar, you can add a map link for each category that contains posts with coordinates. In the Geo Mashup options, check Add Category Links and fill in the options for separator text, link text, and zoom level. Note that this will not work for dropdown-style category lists.

You can make your own links to the map page for a specific category, just add these query parameters to your map page URL ?cat=1&zoom=7 where 1 is the category ID and 7 is the zoom level to start the map on. A full example URL: http://www.cyberhobo.net/hobomap/?cat=14&zoom=4.

Showing posts with the map

This feature lets you display the full post that is currently selected on the map in a separate area on the page. There's a template requirement: your single post template must put the post inside a div like this:<div class="post">...</div>. Most templates do this, but you might have to add this div to the template yourself.

You can use the <!--GeoPost--> tag as explained in the Quick Start, or add <div id="geoPost"></div> to your map page template where you'd like the post to display. Then check 'Enable Full Post Display' in the options.

Styling the map info window

If the "Include style settings" option is checked, the presentation options are used to generate some simple CSS code for you. You can uncheck this and write your own CSS in your theme stylesheet instead. These ids and classes can be styled: #geoMashup, #geoPost, .locationinfo, h2, .meta, .blogdate, .storycontent.

Adding the location to a post

Near the bottom of the advanced editing area below the post editor, a Location area has been added. Look at the very bottom of this screenshot:

The area can be collapsed and expanded by clicking on the +(or -) icon on the right side. After expanding, the map may not show until you perform a search. Click in the Find Location textbox and type a place name (like Chartre in this example) to do a search:

Notice the help link next to the Find Location textbox. Clicking this will display the following instructions for other ways to search for a location.

Put a green pin at the location for this post. There are many ways to do it:

• Search for a location name.
• For multiple search results, mouse over pins to see location names, and click a result pin to select that location.
• Search for a decimal latitude and longitude, like 40.123,-105.456.
• Search for a street address, like 123 main st, anytown, acity.
• Click on the location. Zoom in if necessary so you can refine the location by dragging it or clicking a new location.

To execute a search, type search text into the Find Location box and hit the enter key. If you type a name next to "Save As", the location will be saved under that name so you can find it again with a quick search. Saved names are searched before doing a GeoNames search for location names.

To remove the location (green pin) for a post, clear the search box and hit the enter key.

Template Tags

• <?php GeoMashup::post_coordinates() ?>
• This tag may be used inside "The Loop" in the blog template to retrieve to coordinates of the current post. It can be used to determine if the post has coordinates at all. An example:

	<?php
	$coordinates = GeoMashup::post_coordinates();
	if ($coordinates) {
		echo 'Post location: ' . $coordinates['lat'] . ',' . $coordinates['lng'];
	}
	?>

• <?php GeoMashup::show_on_map_link('link_text') ?>
• This tag may be used inside "The Loop" in the blog template to generate a link to the current post on the mashup map. The link will only be generated if there are Geo coordinates for the post.
• The 'link_text' parameter is a string to use as the text of the link. Default value is 'Geo Mashup'.
• Send false as a second parameter to return the link as a string rather than displaying it.
• This tag used to be called <?php GeoMashup::post_link()?>, which will still work.
• <?php GeoMashup::the_map() ?>
• This tag may be used inside "The Loop" in the page template to generate the map instead of using <!--GeoMashup--> in the page content.
• <?php GeoMashup::body_attribute() ?>
• DEPRECATED. No longer needed, now does nothing.

Helpful Links

Use of this plugin requires a little prior knowledge. You don't have to be an expert on these things, but some familiarity will help.

1. Managing Plugins
2. Creating and Using Pages
3. Templates
4. Template Tags
5. Decimal Geo Coordinates

Troubleshooting

1. If you're not using the most recent version, your problem might have been fixed. You can just try an upgrade first, or check recent development posts to see what work has been done since your version.
2. Make sure you haven't missed anything relevant in the documentation above.
3. Search our Google Group. This is the place for questions and help - if you think there's a bug in the plugin, go to the next step.
4. Check the issues page to see if your problem has been reported yet, and if so what progress has been made on it. Only unresolved issues are listed by default, it might be worth searching solved issues to look for workarounds.
5. Submit a new issue if your problem is not there.