WordPress.org

Plugin Directory

wiki:Travelog

Travelog Plugin

Tags: travel, map, location, GPS, address, visit, GoogleMap
Contributors: swift
Version: 2.5
Released: 2006/06/11
Plugin websites:
http://dev.wp-plugins.org/wiki/Travelog
http://www.sublimity.ca/2005/09/01/travelog/

Travelog adds a geographic dimension to WordPress by helping you keep track of the places you've been. You can create trips, add locations to posts ("posted from...") and easily create embedded !GoogleMaps of any places/trips in your Travelog.

Download the Travelog plugin here or here.

To view the source code, go here.


Upgrading

If you have had a previous version of the plugin installed, follow these steps to upgrade to the newest version. If this is your first installation, follow the instructions below.

  1. Back-up your WordPress database. This step is important as there are database changes between versions of the plugin, and any error in upgrading *could* result in lost data. The handy Backup plugin (accessed via the Manage section of the Admin interface) that comes with WordPress v2.x does the trick nicely...
  2. Deactivate the old version of the Travelog plugin from within WordPress.
  3. Delete the old "travelog" folder from the wp-content/plugins/ directory on your server, and replace it with the new version.
  4. Upload the "travelogmce" folder to wp-includes/js/tinymce/plugins/ directory. This installs the Travelog button on the rich-text post editor toolbar, providing an easy WYSIWYG interface for adding maps/links to posts.
  5. Activate the new version of Travelog from within WordPress.
  6. Start using the new features in your new and improved Travelog.
  7. If you are upgrading to v2.5, you need to generate a new GoogleMap API key, check the Options page for information

Installation

  1. Upload the 'travelog' folder from this archive to the /wp-content/plugins/ directory on your webserver.
  2. Upload the 'travelogmce' folder from this archive to the wp-includes/js/tinymce/plugins/ directory on your webserver. This installs the Travelog button on the rich-text post editor toolbar, providing an easy WYSIWYG interface for adding maps/links to posts.
  3. Active the "Travelog" plugin in WordPress's Site Admin Plugins page.
  4. Modify your WordPress theme so that location information is displayed for posts in summary view. The easiest way to do this is to use the standard Travelog output function, travelog_summary_info(). This is done by adding the following code to your index.php file, right after the post title section. For the default theme, you would change:
    <h2><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>">
    <?php the_title(); ?></a></h2>
    <small><?php the_time('F jS, Y') ?> <!-- by <?php the_author() ?> --></small>
    
    to be:
    <h2><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>">
    <?php the_title(); ?></a></h2>
    <?php echo travelog_summary_info(); ?><br />
    <small><?php the_time('F jS, Y') ?> <!-- by <?php the_author() ?> --></small>
    
    Make similar modifications to archive.php and search.php. Alternatively, You can create your own customized location information output using the Travelog's PHP functions, which are listed and described below.
  5. Modify your WordPress theme so that location information is displayed for posts in detail view. The easiest way to do this is to use the standard Travelog output function, travelog_single_info(). This is done by adding the following code to your single.php file, right after the post date information. For the default theme, you would change:
    on <?php the_time('l, F jS, Y') ?> at <?php the_time() ?>
    and is filed under <?php the_category(', ') ?>.
    
    to be:
    on <?php the_time('l, F jS, Y') ?> at <?php the_time() ?>
    <?php echo travelog_single_info(); ?>
    and is filed under <?php the_category(', ') ?>.
    
    Again, you can create your own custom output using Travelog's PHP functions listed and described below.
  6. Review the Travelog options by clicking on 'Travelog' on the Options page sub-menu of WordPress's Site Admin.
  7. Create a GoogleMaps API key for your website so that you can embed Travelog maps on your website. See the info on the Travelog Options page for details.
  8. Start adding locations to your Travelog by clicking on Travelog on the Manage page sub-menu of WordPress's Site Admin

Usage

Formats

Most fields in the Travelog are pretty straight forward and should need no explination, but the dates_visited field requires a special format in order for the plugin to work properly. The proper format for a visit is 'yyyy/mm/dd hh:mm'. For example, a visit on February 21, 2005 at 1:21PM would be entered as '2005/02/21 13:21' while October 13, 2004 at 9:45AM would be '2004/10/13 09:45'. Hours must be entered in the 24 hour format, with a leading 0 if it is a single digit number. Specifying a time is optional, you can simply add a date in the 'yyyy/mm/dd' format, but if you start to use the Trips feature and have multiple locations visited on the same day, they won't likely be shown in the correct order unless you start specifying times.

Trips

The trips feature in Travelog provides you with a way of keeping track of your trips, where you went, when, and in what order. The first step to logging a trip is to enter it into Travelog by clicking on the Trips tab in the Travelog Manager. On the bottom of this page, enter the name for the trip, the start and end date/times (which follow the same formatting rules as visits - see above) and a description.

Once the trip has been entered into Travelog, you have to add locations (stops) to it. Each stop must be entered as a location in Travelog using the Locations Manager just like normal. Trips are built automatically by associating locations with specific trips, and then all visits to that location between the trip start and end dates are automatically added to the trip's itinerary. There are two ways to build this itinerary (adding visit and trip information to the appropriate locations):

  1. After all the stops (locations) have been created, create the Trip by adding a new trip in the trips section. Once it has been created (name, start & end dates set etc.), open it up in the trip editor. At the bottom of the Stops section, there is a section called "Add Stop". In the box, enter the name of the location you want to add to the trip and click on the appropriate entry in the box that appears. Once a location has been chosen, a new section will appear below where you can enter a new visit date/time for when the stop was visited on the trip. Once that is set, click the "Add stop" button, and your location will be added to the trip itinerary. Repeat these steps with other locations and/or date/times to build your trip itinerary (always check the itinerary after each addition to make sure it is correct).
  2. The second method involves editing each location individually to add the stop as a visit, and associate the location wit the trip. This method is only easier if the stop locations are not in your Travelog already and you have to create them anyway (in which case you just set two more fields when you create each location). If you're doing it this way, you have to create the trip before creating the locations, otherwise you'll not be able to set the options properly and will have to go back and edit every location again. When creating the locations, in addition to the normal fields (name, category, coordinates, address etc.), you need to select the trip in the Trips section, and add a visit in the Vists section that corresponds to the time you visited the location on the trip. Check the trip in the trip editor occasionally to ensure that the itinerary is being built properly, and if there are problems, go back and edit the affected stop location.

To remove a stop on a trip, delete the appropriate visit (by editing the location), or to completely remove all occurances of a location in a trip, delete the trip from the location (in the Trips section of the location editor).

In Posts

There are two different Travelog tags/features that you can use in posts - location names (with links) and embedded maps. If you have installed the WYSIWYG tag maker (v2.5+, see installation/upgrade instructions) and are using the rich-text editing environment, all you have to do is set the cursor to where you want to insert Travelog content and then click on the Travelog button in the editor toolbar directly above the post editing area. Follow the instructions in the window that appears and you can quickly and easily build your map/link. If you are not using the rich-text editor, you can manually create the required tags by typing them directly into the post. Here's everything you need to know in order to build the tags:

To insert a link to a GoogleMap of a location from your Travelog, you have to use the custom <travelog attributes>link text</travelog> tag. The allowed attributes are:

  • id - the id number of the location you want to appear on the linked map.
  • use - determines what information you want to use to map the location, either 'address' or 'coordinates'.
  • view - the map type of the linked map, either 'map', 'satellite' or 'hybrid'.
  • zoom - zoom level of the linked map, values from 1 (whole earth) to 17 (street-level) are allowed.

An example of how to use the tag in a post is:

normal post text, but <travelog id="14" use="coordinates" view="satellite" zoom="10">this text is linked</travelog>
to a satellite view googlemap of location 14, mapped using coordinates and shown at zoom level 10.

Any text can be linked in this manner, generally you'll want to use the location's name, but there may be times when something else is more appropriate. If you are using the location name, you have to type that manually.

Embedded Maps

You can embed GoogleMaps in your posts by using the <!--travelogmap attributes --> tag. The allowed attributes are:

  • ids - This determines which locations are shown on the map. There are three possible formats for this attribute:
    • You can enter a comma seperated list of location id numbers (one or more numbers).
    • You can use this attribute to map the last X number of locations you have visited by using ids="last(X)".
    • You can have the map show all the locations in your Travelog by using ids="all".
  • category - This lets you specify the name of a category to map, and the map will show all locations that are in that category (eg. category="Beaches")
  • trips - This attribute allows you to specify trips to map. Mapped trips show markers at all their stops, and a line that connects the stops together in the order they were visited. Like the ids attribute, there are three acceptable formats for it:
    • A comma seperated list of trip id numbers (eg. trips="2,9,5")
    • You can also use this attribute to map the last X number of trips you have taken by using trips="last(X)"
    • You map all your trips by setting trips="all"
  • map_type - Lets you set the default map type for that particular map (overrides defaults). Allowed values are 'map', 'satellite' and 'hybrid'. If the attribute is not set, the default map type set in your Travelog Options is used.
  • height - height of the map in pixels. If not set, the default value from Travelog Options is used.
  • width - width of the map in pixels. If not set, the default value from Travelog Options is used.
  • zoom - Initial zoom level of the map, a number from 1 (whole earth) to 17 (street-level). If not set, the default value from Travelog Options is used.
  • controls - lets you set what type of controls you want to show on the map. 'small' will show the panning arrows and two small zoom buttons (in and out). 'large' will show the panning buttons and a full zoom controller with the zoom in & out buttons and a slider showing the current zoom level. 'zoom' shows only the two small zoom buttons (in and out). If not set, 'small' will be used for maps 300px or smaller, and 'large' for anything larger than 300px.
  • show_types - Determines whether or not to show the buttons that allow you to change map type. A value of 1 shows them, a value of 0 hides them. Default is 0 (hide).
  • scale - Determines whether or not to show the scale bar. 1 will show it, and 0 will hide it. Default is 0 (hide).

One thing to note is that you can specify any combination of 'ids', 'trips' and 'category' so that multiple locations/trips are displayed. Example calls are:

  • <!--travelogmap ids="last(5)" map_type="satellite" controls="large" width="500" height="500" --> shows a 500x500 satellite map of the last 5 locations you've visited with large controls.
  • <!--travelogmap ids="10" trips="2,1" --> shows a map with location 10 and all the locations on trips 2 and 1 (with lines connecting stops on each trip). Other settings are controlled by defaults set in Travelog Options.
  • <!--travelogmap category="Mountain Tops" width="200" height="400" scale="1" --> shows all locations from the category Mountain Tops in a 200x400 map with the scale visible.
  • <!--travelogmap ids="12,8,13,41" show_types="1" controls="large" --> shows locations 12, 8, 13 and 41 on a map with large controls where the map type buttons are visible.

In Templates

Embedded Maps

To show an embedded map in your template (on pages, in the header, footer, sidebar or pretty much anywhere), you need to call the PHP function Travelog::embed_map(). There is only one parameter to be passed - an array whose keys are the attributes for the embedded map tag used in posts (described above). To show the same 4 example maps listed in the above section, use these calls:

  • Travelog::embed_map(array('ids'=>"last(5)", 'map_type'=>"satellite", 'controls'=>"large", 'width'=>"500", 'height'=>"500"));
  • Travelog::embed_map(array('ids'=>"10", 'trips'=>"2,1"));
  • Travelog::embed_map(array('category'=>"Mountain Tops", 'width'=>"200", 'height'=>"400", 'scale'=>"1"));
  • Travelog::embed_map(array('ids'=>"12,8,13,41", 'show_types'=>"1", 'controls'=>"large"));


License

The Travelog plugin is licensed under the GPL (the same license that WordPress uses), and to sum it up, you can freely use, distribute and modify this plugin however you desire. If you do use it on your site, I'd appreciate you leaving a comment on my site telling me what you think about it, but it's more to satisfy my curiousity about what ends up happening to this little project of mine than anything else, so it's not a big deal.

If you find any bugs (I'm sure there are some in here), or have ideas about things you'd like to see in future releases of this plugin, please let me know (especially if you'd like to help implement them). I'll do my best to implement suggestions, but I can't make any rock-solid promises as there is more to life than coding...

Change Log

Version 2.5

  • Switched the entire Travelog Management interface to AJAX so it's now real-time and easily searchable
  • Updated all the GoogleMaps code to be API v2 compliant
  • Added a WYSIWYG Travelog tag builder for use with the rich-editing environment in WP v2
  • Minor updates to ensure compatibility with WP v2.x
  • Changed the embedded maps so that they are now directly embedded in each page rather than in inline frames. This switch means a new API key is required
  • Fixed a bug where Travelog locations could not be assoicated with posts until after they had been published (now you can add Travelog data to a post at the time you publish it)
  • Added the Travelog Explorer, (file wp-travelog.php) that provides a simple but powerful way to let visitors explore your Travelog via a map
  • Added the "Stop Adder" feature to the trip editing page to allow stops to be added quickly and easily from there (rather than having to go into each location and change its settings)

Version 2.0

  • Added the ability to embed GoogleMaps within posts and WordPress templates. Maps can be fully customized to show various locations (specific ones, all, X most recent), categories, trips (with lines between them),
  • Added 'Trips' to keep track of your various adventures and when you went. It is fully integrated with locations and visits to provide an easy set-up and editing system, and the new GoogleMaps feature can show a map of your trip.
  • Fixed bugs with Internet Explorer (add/edit locations now work with maps turned on)
  • Fixed bug where leaving lat, long or elevation blank would cause errors
  • Changed the visit data format (now yyyy/mm/dd hh:mm) to allow times to be recorded for each visit in addition to dates (really helpful for keeping trip stops in the right order)

Version 1.1

  • Added 'City', 'State' and 'Country' fields to each location, so now when used with the old 'Address' field, address information is broken down into logical pieces.
  • Added ability to provide URLs to GoogleMaps or MapQuest maps that map the location based on address rather than coordinates.
  • Ability to use the GoogleMap on the edit location page to get coordinates for the location. Simply click on the map where you want your location to be, and the coordinates will automatically be entered.
  • Removed several of the mapping services that seemed redundant or excessively specialized.
  • Merged the 'Edit Location' and 'Add Location' interfaces into the same layout.
  • Added 'hint' values for the 'Add visit' field (date format for Travelog is yyyy/mm/dd).

Version 1.0

  • Initial public release.

Function Reference

The Travelog plugin provides several functions for interacting with your Travelog. There are three sets of functions provided; General Functions, Advanced Functions and Internal Functions:

General Functions

These functions allow for basic retrieval and output of location information for posts

travelog_summary_info()
Outputs a string with location information about the post. It shows the location name (which is linked to a GoogleMap of the location) as well as the coordinates of the location in degree-minute-second format. This is meant to be used on your index.php page right below the post title. If there is no location associated with the post, nothing is displayed.

travelog_single_info()
Outputs a string with location information about the post. It shows the location name (which is linked to a GoogleMap of the location) as well as the coordinates of the location in degree-minute-second format. This is meant to be used on your single.php page down at the bottom in the metadata section. If there is no location associated with the post, nothing is displayed.

the_latitude()
Outputs the latitude of the location associated with the post in decimal degree format.

the_latitudeDMS()
Outputs the latitude of the location associated with the post in degree-minute-second format (dd˚ mm' ss").

the_longitude()
Outputs the longitude of the location associated with the post in decimal degree format.

the_longitudeDMS()
Outputs the longitude of the location associated with the post in degree-minute-second format (dd˚ mm' ss").

the_location_name()
Outputs the name of the location associated with the post.

the_location_description()
Outputs the description of the location associated with the post.

get_latitude()
Returns the value of the latitude for the location associated with the post in decimal degree format, with north latitudes being positive and south latitudes being negative. This can be used if you want to display the latitude in some other format, check to make sure there is a latitude for the post or output different latitudes differently.

get_longitude()
Returns the value of the longitude for the location associated with the post in decimal degree format, with east longitudes being positive and west longitudes being negative. This can be used if you want to display the longitudes in some other format, check to make sure there is a longitudes for the post or output different longitudes differently.

get_location_name()
Returns the name of the location associated with the post.

get_location_description()
Returns the description of the location associated with the post.

map_location_url($map, $location_id, $map_type)
Returns the URL for a map of the location whose ID is passed as $location_id. $map_type can be set to either 'address' or 'coordinates', and dictates what information is used to create the map URL.$map lets you choose which mapping service to use. Acceptable values for $map are:

  • 'GoogleMaps' - supports both 'coordinates' and 'address' map types.
  • 'MapQuest' - supports both 'coordinates' and 'address' map types.
  • 'GeoURL' - supports only 'coordinates' map types.
  • 'GeoCache'- supports only 'coordinates' map types.
  • 'DegreeConfluence'- supports only 'coordinates' map types.
  • 'TopoZone'- supports only 'coordinates' map types.

distance_between($id1, $id2, $unit)
Calculates the distance between the two locations whose ids are passed as $id1 and $id2 (using their latitudes & longitudes), and returns the value as a number in terms of the units specified in the $unit parameter. For kilometers use 'k', for miles use 'm' and for nautical miles use 'n'.

Advanced Functions

These functions control the inner workings of the Travelog plugin, and provide advanced access to the information contained in your Travelog. You should have at least moderate experience working with PHP if you want to use these functions.

NOTE: All the advanced functions are contained in the static class 'Travelog'. To call them in your templates, you must add 'Travelog::' in front of their names (eg. to call get_categories(), you would use <?php $categories = Travelog::get_categories(); ?>

add_location($location)
Adds a location to your Travelog based on information passed in the $location parameter. $location must be an object with variables for each of the Travelog database fields.

get_locations($category, $limit, $order, $search, $ids)
Returns an array of objects, one object for each location from your travelog that matches the criteria (is in category $category, whose name contains $search or whose id is in the csv string $ids), and each object has a set of variables containing the all information about that location.

get_location($id)
Returns a location object with all the information for the location whose id is passed as the id parameter.

get_post_location()
Returns a location object with all the information for the location associated with the post. If no location is associated with the post and a default location is set, the location object will contain information about the default location.

get_categories()
Returns an numerically-indexed array of all of the Travelog category names

coordinate_DMS($value, $coordinate)
Returns a HTML string showing the value of the coordinate passed as $value in the degrees-minutes-seconds format. $coordinate must be either 'latitude' or 'longitude' to tell the function which direction (N/S or E/W) to append on the end.

Internal Functions

These functions control the inner workings of the Travelog plugin, and should not be used in your templates. If you want to make changes to how the Travelog plugin works, this is where it should be done, but only if you have an advanced understanding of PHP, as making any changes could destroy your Travelog. All functions that are not listed above are considered Internal Functions, and if you can't figure out which ones they are (and exactly what they each do), you shouldn't be editing them - so I won't bother with discussing them here.

Last modified 12 years ago Last modified on 06/13/06 11:52:25