WordPress.org

Plugin Directory

Changes between Version 38 and Version 39 of Travelog


Ignore:
Timestamp:
06/13/06 11:52:25 (12 years ago)
Author:
swift
Comment:

updating for v2.5

Legend:

Unmodified
Added
Removed
Modified
  • Travelog

    v38 v39  
    99http://www.sublimity.ca/2005/09/01/travelog/ 
    1010 
    11 The Travelog plugin for !WordPress lets you input and organize information about the places you've been (coordinates and/or addresses, dates visited & a description), and allows  individual posts or text within posts to be associated with these locations. The plugin can also provide direct links to online maps of the locations from various online mapping services, including [http://maps.google.com/ GoogleMaps] and [http://www.mapquest.com/ Mapquest]. 
    12  
    13 == New Version (2.5) Released! == 
    14 Success! I've managed to do some work on this, and have put out a new version (2.5) that *should* fix most of the issues, and also adds compatibility for !GoogleMaps v2. The whole admin interface is now run by AJAX (I had a lot of time on my hands without internet, so I did some Javascript to pass time) which I think is pretty slick - but may be buggy... One important note, for v2.5 you need to change your !GoogleMap API key (there's only one now) so that is created for your Wordpress directory. Please not that the readme hasn't been updated yet... that's the next job. Let me know if there are bugs or new ideas, things are getting exciting now with !GoogleMaps and there is a lot more that could be done! 
     11Travelog 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 [http://maps.google.com/ !GoogleMaps] of any places/trips in your Travelog. 
    1512 
    1613'''Download the Travelog plugin [http://www.redalt.com/External/plugins.php?p=travelog here] or [http://www.sublimity.ca/travelog_v2-5.zip here].''' 
     
    2219= Upgrading = 
    2320If 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. 
    24  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. I'd recommend the wonderful wp-backup plugin - get it [http://www.skippy.net/blog/category/wordpress/plugins/wp-db-backup/ here]. 
     21 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... 
    2522 2. Deactivate the old version of the Travelog plugin from within !WordPress. 
    26  3. Delete the old travelog folder from your server, and replace it with the new version. 
    27  4. Activate the new version of Travelog from within !WordPress.  
    28  5. Start using the new features in your new and improved Travelog. 
    29  6. If you are upgrading to v2.5, you need to generate a new GoogleMap API key, check the Options page for information 
     23 3. Delete the old "travelog" folder from the wp-content/plugins/ directory on your server, and replace it with the new version. 
     24 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. 
     25 5. Activate the new version of Travelog from within !WordPress.  
     26 6. Start using the new features in your new and improved Travelog. 
     27 7. If you are upgrading to v2.5, you need to generate a new GoogleMap API key, check the Options page for information 
    3028 
    3129 
    3230= Installation = 
    3331 
    34  1. Upload the 'travelog' folder from this archive to your /wp-content/plugins/ folder on your webserver. 
    35  2. Active the "Travelog" plugin in WordPress's Site Admin Plugins page. 
    36  3. 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: 
     32 1. Upload the 'travelog' folder from this archive to the /wp-content/plugins/ directory on your webserver. 
     33 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. 
     34 3. Active the "Travelog" plugin in WordPress's Site Admin Plugins page. 
     35 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: 
    3736{{{ 
    3837<h2><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>"> 
     
    4847}}} 
    4948 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. 
    50  4. 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: 
     49 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: 
    5150{{{ 
    5251on <?php the_time('l, F jS, Y') ?> at <?php the_time() ?> 
     
    6059}}} 
    6160 Again, you can create your own custom output using Travelog's PHP functions listed and described below. 
    62  5. Review the Travelog options by clicking on Travelog on the Options page sub-menu of WordPress's Site Admin. 
    63  6. Start adding locations to your Travelog by clicking on Travelog on the Manage page sub-menu of WordPress's Site Admin 
     61 6. Review the Travelog options by clicking on 'Travelog' on the Options page sub-menu of WordPress's Site Admin. 
     62 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. 
     63 8. Start adding locations to your Travelog by clicking on Travelog on the Manage page sub-menu of WordPress's Site Admin 
    6464 
    6565= Usage = 
    6666== Formats == 
    67 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'. 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. 
     67Most 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. 
    6868 
    6969== Trips == 
    70 Trips are new in v2.0, and provide 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. 
    71  
    72 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. In addition to the normal fields though, you need to specify that the location is part of the trip you're building. You set this in the Trip Information section of the Location Editor. Choose the trip you want to add the stop to from the pulldown menu that appears here. The final step is to add a visit to that location that corresponds to the time you visited the location on the trip. Any visit to a location (which has been set as part of a trip) that occured between the start and end date/times of the trip (as entered in the trip information) is assumed to have been a stop on the trip, and is automatically added as a stop on the trip. Locations can be given multiple visits within the date/time range of the trip, if this happens it means that that location will appear in the trip itinerary at each date/time specified. To see itinerary for a trip, view the trip in the Trip Editor, and click to show th itinerary. To remove a location/stop from a trip, remove the visit from the location that corresponds to that stop. 
     70The 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. 
     71 
     72Once 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): 
     73 
     74 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). 
     75 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. 
     76 
     77To 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). 
     78 
    7379 
    7480 
    7581== In Posts == 
    76 There are two different Travelog tags/features that you can use in posts, location names (with links) and embedded maps. 
     82There 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: 
     83 
    7784=== Links === 
    78 To insert a location link in travelog, you use the special ''<travelog attributes>link text</travelog>'' tag. There are several allowed attributes. They are: 
    79  * '''id''' - the id number of the location you want to have mapped on the linked !GoogleMap. 
     85To 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: 
     86 * '''id''' - the id number of the location you want to appear on the linked map. 
    8087 * '''use''' - determines what information you want to use to map the location, either 'address' or 'coordinates'. 
    8188 * '''view''' - the map type of the linked map, either 'map', 'satellite' or 'hybrid'. 
    82  * '''zoom''' - zoom level of the linked map, values from 1 (close-up) to 16 (world view) are allowed. 
     89 * '''zoom''' - zoom level of the linked map, values from 1 (whole earth) to 17 (street-level) are allowed. 
    8390An example of how to use the tag in a post is: 
    8491{{{ 
    85 normal post text, but <travelog id=14 use="coordinates" view="satellite" zoom="10">this text is linked</travelog> 
     92normal post text, but <travelog id="14" use="coordinates" view="satellite" zoom="10">this text is linked</travelog> 
    8693to a satellite view googlemap of location 14, mapped using coordinates and shown at zoom level 10. 
    8794}}} 
     95Any 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. 
    8896 
    8997=== Embedded Maps === 
    90 You can embed !GoogleMaps in your posts by using the ''<!--travelogmap attributes -->'' tag. Allowed attributes are: 
    91  * '''ids''' - This determines which locations are shown on the map. 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)". Alternatively, you can have the map show all the locations in your Travelog by setting ids="all". 
    92  * '''category''' - This lets you specify a category to map, and so the map will show all locations that are in that category.  
    93  * '''trip''' - This will map all the locations from a specific trip (with lines connecting the stops in order). Set this attribute equal to the ID number of the trip. 
    94  * '''map_type''' - Lets you set the default map type for that particular map (override defaults). Allowed values are 'map', 'satellite' and 'hybrid'. Default is set via Travelog Options. 
    95  * '''height''' - height of the map in pixels. Default is set via Travelog Options. 
    96  * '''width''' - width of the map in pixels. Default is set via Travelog Options. 
    97  * '''zoom''' - Initial zoom level of the map, a number from 1 (close-up) to 16 (world view). Default is set via Travelog Options. 
    98  * '''controls''' - lets you set what 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, but will show 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). Default is 'small' for maps 300px or smaller, and 'large' for anything larger than 300px.  
     98You can embed !GoogleMaps in your posts by using the ''<!--travelogmap attributes -->'' tag. The allowed attributes are: 
     99 * '''ids''' - This determines which locations are shown on the map. There are three possible formats for this attribute: 
     100  * You can enter a comma seperated list of location id numbers (one or more numbers). 
     101  * You can use this attribute to map the last X number of locations you have visited by using ids="last(X)". 
     102  * You can have the map show all the locations in your Travelog by using ids="all". 
     103 * '''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")  
     104 * '''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: 
     105  * A comma seperated list of trip id numbers (eg. trips="2,9,5") 
     106  * You can also use this attribute to map the last X number of trips you have taken by using trips="last(X)" 
     107  * You map all your trips by setting trips="all" 
     108 * '''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. 
     109 * '''height''' - height of the map in pixels. If not set, the default value from Travelog Options is used. 
     110 * '''width''' - width of the map in pixels. If not set, the default value from Travelog Options is used. 
     111 * '''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. 
     112 * '''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. 
    99113 * '''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). 
    100114 * '''scale''' - Determines whether or not to show the scale bar. 1 will show it, and 0 will hide it. Default is 0 (hide). 
    101 One thing to note is that you can specify any combination of 'ids', 'trip' and 'category' so that a group of locations is displayed. 
     115One thing to note is that you can specify any combination of 'ids', 'trips' and 'category' so that multiple locations/trips are displayed. 
    102116Example calls are: 
    103117 * ''<!--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. 
    104  * ''<!--travelogmap ids="10" trip="3" -->'' shows a map with location 10 and all the locations on trip 3 (with lines connecting them). Other settings are controlled by defaults set in Travelog Options. 
     118 * ''<!--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. 
    105119 * ''<!--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. 
    106120 * ''<!--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. 
     
    108122== In Templates == 
    109123=== Embedded Maps === 
    110 To show an embedded map in your template, use Travelog's function embed_map(). There is only one parameter to be passed, and that is an array that has keys named the same as the embedded map attributes above. To show the same 4 example maps listed in the above section, use these calls: 
     124To 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: 
    111125 * Travelog::embed_map(array('ids'=>"last(5)", 'map_type'=>"satellite",  'controls'=>"large",  'width'=>"500",  'height'=>"500")); 
    112  * Travelog::embed_map(array('ids'=>"10", 'trip'=>"3")); 
     126 * Travelog::embed_map(array('ids'=>"10", 'trips'=>"2,1")); 
    113127 * Travelog::embed_map(array('category'=>"Mountain Tops", 'width'=>"200", 'height'=>"400", 'scale'=>"1")); 
    114128 * Travelog::embed_map(array('ids'=>"12,8,13,41", 'show_types'=>"1", 'controls'=>"large")); 
     129  
     130  
    115131-------- 
    116132 
     
    121137 
    122138= Change Log = 
     139=== Version 2.5 === 
     140 * Switched the entire Travelog Management interface to AJAX so it's now real-time and easily searchable 
     141 * Updated all the !GoogleMaps code to be API v2 compliant 
     142 * Added a WYSIWYG Travelog tag builder for use with the rich-editing environment in WP v2 
     143 * Minor updates to ensure compatibility with WP v2.x 
     144 * 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 
     145 * 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) 
     146 * Added the Travelog Explorer, (file wp-travelog.php) that provides a simple but powerful way to let visitors explore your Travelog via a map 
     147 * 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) 
     148  
    123149=== Version 2.0 === 
    124150 * 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),  
    125  * 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 adn editing system, and the new !GoogleMaps feature can show a map of your trip. 
     151 * 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. 
    126152 * Fixed bugs with Internet Explorer (add/edit locations now work with maps turned on) 
    127153 * Fixed bug where leaving lat, long or elevation blank would cause errors 
     154 * 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) 
    128155 
    129156=== Version 1.1 === 
     
    148175''travelog_summary_info()''[[BR]] 
    149176Outputs 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. 
     177 
     178''travelog_single_info()''[[BR]] 
     179Outputs 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. 
    150180 
    151181''the_latitude()''[[BR]] 
     
    201231Adds 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. 
    202232 
    203 ''get_locations($category, $limit, $order)''[[BR]] 
    204 Returns an array of objects, one object for each location in your travelog, and each object has a set of variables containing the all information about that location. 
     233''get_locations($category, $limit, $order, $search, $ids)''[[BR]] 
     234Returns 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. 
    205235 
    206236''get_location($id)''[[BR]] 
     
    219249 
    220250== Internal Functions == 
    221 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. The functions are just listed briefly here to let you know generally what they do. 
    222  
    223 ''inline_locations($content)''[[BR]] 
    224 Used to process travelog tags that appear within posts 
    225  
    226 ''update_post($post_id)''[[BR]] 
    227 Does the processing of associating a location with a post 
    228  
    229 ''add_menus()''[[BR]] 
    230 Displays the Travelog links in the Options and Manage sub-menus in the !WordPress Site Admin 
    231  
    232 ''install_db()''[[BR]] 
    233 Create the travelog database table and initializes the Travelog's !WordPress options 
    234  
    235 ''edit_form_advanced()''[[BR]] 
    236 Controls what is shown on the Edit Post Page 
    237  
    238 ''show_adminheader()''[[BR]] 
    239 CSS and HTML to create the submenu on the Manage page 
    240  
    241 ''manage_locations()''[[BR]] 
    242 Handles the addition, updating and removal of locations and categories 
    243  
    244 ''manage_options()''[[BR]] 
    245 Handles the updating of Travelog's options 
    246  
    247 ''googlemaps_javahook()''[[BR]] 
    248 Outputs a javascript link in the page headers to allow !GoogleMaps to be embedded. 
    249  
    250 ''coordinate_metatags()''[[BR]] 
    251 Outputs some standard meta tags with location information 
    252  
    253  
     251These 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.