|
DocForOneOneThree
Installation, Upgrading, Configuration, Use, and Troubleshooting.
Geo Mashup Plugin Documentation For Version 1.1.3Contents:
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. Additional GuidanceIf you find yourself wanting more than you find here, Bruce at bioneural.net has contributed an implementation guide that steps through accomplishing many cool things with the Geo Mashup plugin. System RequirementsAs of version 1.1, WordPress 2.5.1 or higher is required. Installation
UpgradingWARNING: Upgrading to 1.1 or later from earlier versions will probably break your current map. At least some minor updates to geo mashup tags will be required to get things going again. See the TagReference for old and new tag formats. 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. 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. Getting StartedGeo Mashup lets you associate location information with any post or page, then use that information in Google maps. Adding the location to a post or pageNear the bottom of the advanced editing area below the 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:
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. KML AttachmentsNote: for now you'll have to use the browser uploader instead of the Flash uploader for KML files. See Issue 164 for details. Instead of searching for a location, you can upload a KML file with a post or page using the media uploader. The KML file (center) will be used to determine a default location for the post or page. If you include a map in that post or page, it will load and display the KML file. You can create a map in the My Maps tab of the Google Maps page and save it as KML using these instructions. Adding a MapYou can put a map in any page or post by typing the shortcode [geo_mashup_map] into the editor. Look at the TagReference for more options. If a post or page has location information associated with it, the map displays that. Otherwise, a global map of all located posts and pages is displayed. There are lots of ways to customize the map. You can put a map outside posts and pages with the template tag <?php echo GeoMashup::map(); ?>. The TagReference has details for template tags too. More Advanced FeaturesGlobal Mashup PageYou can have a single page with a global map that will be used in links generated by Geo Mashup. Create a page, include the [geo_mashup_map] tag in it, and fill in the "Default Settings for Global Maps" in the Geo Mashup options. The show_on_map_link tag and "Add Category Links" options will now create links to this page, which will load a global map appropriate for the link. Adding a "show on map" link to posts with a locationYou can add a link from any located item to your designated global map page, with the global map centered on the clicked item. Use the [show_on_map_link] shortcode tag for a single item, or the template tag <?php echo GeoMashup::show_on_map_link(); ?> to add links to all posts or pages. See the TagReference for details. Category Map LinksIf you have a list of category links in your sidebar, you can add a map link for each category that contains posts with coordinates. First set up a Global Mashup Page if you haven't already. 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. Your categories must have descriptions or a WordPress problem will cause the links to appear mangled. Category Colors and LinesMarkers in a category can be connected by a line on a global map. Categories can be assigned a color for lines and markers in the Geo Mashup options. At the bottom of Geo Mashup Options for global maps you should see your categories listed. For each category you can choose a color for the category markers and lines, and a "Show Connecting Line Until Zoom Level (0-17 or none)" setting. This allows you to specify that a line is only drawn for the category only up to the specified zoom level. When zoomed in closer than that, the line will disappear. Showing posts with the mapThis 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. Now you can use the Full Post tag as explained in the TagReference, then check 'Enable Full Post Display' in the options. Map StylesheetIf the file map-style.css is present in the geo-mashup plugin directory, it will be applied to maps. This file will not be overwritten by upgrades. Look at example-map-style.css for examples of CSS classes available. Custom JavaScriptIn the geo-mashup directory is a file named custom-sample.js. Rename this to custom.js and edit it to draw things and do other kinds of customization using the Googe Maps API. WidgetsA helpful user Marcel found this way to use Geo Mashup shortcodes in the WordPress text widget: I can use geo_mashup_map like shortcodes in the text-widget by adding the following code at the start of "functions.php" of my active template, just after the "<?php" tag add_filter('widget_text', 'do_shortcode');
Known Issues and General HelpDomain Name and API KeyYou 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:
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. Useful Background LinksUse of this plugin requires a little prior knowledge. You don't have to be an expert on these things, but some familiarity will help.
Help, Questions, and Troubleshooting
|
