WP-Trip-Summary

An opinionated, multi-language, WordPress trip summary plugin to help travel bloggers manage and display structured information about their train rides and biking or hiking trips.

Contents

1. Is it good for you?
2. Features
3. Downloading the plug-in
4. Alternatives
5. Progress & Management
6. What it does
7. Supported languages
8. Changelog
9. Upgrade notices
10. Roadmap
11. Requirements
12. Limitations
13. Screenshots
14. Contributing
15. Credits
16. License

Is it good for you?

This plug-in is very good for you if:

• you are a travel blogger and you're writing a lot about your trips, as this is a very good way of also providing a bit of extra information (actually, I'm the occasional travel blogger myself and I wrote it with this very purpose in mind).
• you are a niche travel agency, as this would be a very helpful tool to have a highly professional approach to presenting your trips;
• you are a hotel or an accomodation unit and want to present the options your guests would have for spending time around you;
• you are government agency concerned with promoting turistic attractions, as you can have a website up and running in no time: just install WordPress, add this plug-in and you are ready to go.

Do you think this would be right for you but there's that extra thing that's missing? Let's chat!.

Features

• attach technical information to a post (ex. how long was your trip, how much did you totally climb, where from and where to, how hard do you think it has been, what kind of roads or trails did you encounter etc.);
• attach some GPS data to a post (see below for a detailed discussion on accepted file formats) and display that track on a map;
• allows management of the look-up data used to populate the fields presented as single or multi-selection options list (ex. Difficulty Level, Open During Seasons etc.);
• allows customization of the map layer:
  • map tile source (comes by default configured with OpenStreetMap);
  • enabling/disabling of available map controls;
  • customizing the visual representation of the track).
• allows customization of the measurement unit system used to represent various values (ex. Total distance, Total climb etc.);
• multi-language.

File formats accepted for import

WP-Trip-Summary supports the following file formats when importing GPS track data that should be attached to a post:

• GPX (see more details here);
• GeoJSON (see more details here).

GPX

An uploaded file is processed as a GPX file (and validated as such) if it has any of the following mime types:

• application/gpx;
• application/x-gpx+xml;
• application/xml-gpx;
• application/xml;
• application/gpx+xml;
• text/xml.

GPX documents are expected to comply with the GPX 1.1 schema and are parsed as follows:

• Only document name, description and keywords metadata elements are read;
• The following information is read for a point (<wpt> or <trkpt>), besides latitude and longitude:
  • altitude/elevation (<ele> element);
  • name (<name> element).
• The following information is read for a track part (<trk> element), besides the list of track segments;
  • name (<name> element).
• For a track segment (<trkseg> elements), only its points are read.

For the more technically inclined, the parser can be consulted here.

GeoJSON

An uploaded file is processed as a GeoJSON file (and validated as such) if it has any of the following mime types:

• application/json;
• application/geo+json;
• application/vnd.geo+json.

GeoJson documents are assumed to comply with RFC 7946 and are parsed as follows:

• Document metadata is only searched for is the root object is a FeatureCollection and the first Feature of that collection:

  • has a properties property;
  • its geometry property is null.

• A LineString is read as a track part with a single track segment;

• If a LineString geometry is contained within a Feature object, then the resulting track part's name is searched for in the feature object's properties property.

• A MultiLineString is read as a track part, and each comprising line string is added to the track part as a track segment;

• If a MultiLineString geometry is contained within a Feature object, then the resulting track part's name is searched for in the feature object's properties property.

• A Point is read as a document-level waypoint, regardless of where it is found in the geoJSON file;

• If a Point geometry is contained within a Feature object, then the waypoint's name is searched for in the feature object's properties property.

• All the points in a MultiPoint are each added as a document-level waypoint, regardless of where it is found in the geoJSON file;

• If a MultiPoint geometry is contained within a Feature object, then a name is searched for in the feature object's properties property and assigned to each of the resulting waypoints;

• A Polygon is read as a track part with a track segment for each of the polygon's contour lines;

• If a Polygon geometry is contained within a Feature object, then the resulting track part's name is searched for in the feature object's properties property.

• A MultiPolygon is read as multiple track parts, one for each comprising polygon; each track part is then comprised of the corresponding polygon's contour lines;

• If a MultiPolygon geometry is contained within a Feature object, then a name is searched for in the feature object's properties property and assigned to each of the resulting track parts.

For the more technically inclined, the parser can be consulted here.

Downloading the plug-in

You can get the plug-in:

• either from the WordPress plug-in directory: https://wordpress.org/plugins/wp-trip-summary/;
• or from the Releases section of the project's page: https://github.com/alexboia/WP-Trip-Summary/releases.

Alternatives to WP Trip Summary

So I figured it would be nice to list here what other WordPress plugins can be used, if WP Trip Summary does not cover all your needs or its philosophy just isn't for you. These certainly are not the only ones, but these are the ones I consider the most relevant.

Waymark

Waymark allows you to create maps as you would create posts, add various shapes to them. These can then be embedded to any post using shortcodes. It also knows how to import data (markers and lines) from GPX/KML/GeoJSON files, to be displyed on a map.
It's still constantly updated and I recommend it if all you want to define and organize general purpose maps, possibly a lot of them, and use them in any post.
Find out more and get it here: https://wordpress.org/plugins/waymark/.

WP GPX Maps

WP GPX Maps allows you to upload a GPX track and display it on a map, along with a couple of graphs: altitude, speed, heart rate, temperature, cadence, grade. It also looks up the media gallery for picture files that would match the coordinates on the track and display those on the map as well. You get central management of these tracks and you can embed them anywhere using shortcodes.
It's a bit behind with the updates, but I recommed it for a similar reason I recommended Waymark - if you'd like to manage your stuff centrally and use it anywhere - as well as for the wealth of graphs it provides out of the box. Find out more and get it here: https://wordpress.org/plugins/wp-gpx-maps/.

Lf Hiker

Lf Hiker is somwehat closer to WP Trip Summary's philosophy: it's a plugin that allows you to quickly display your gpx tracks with their profile elevation on an interactive map. It's also linked to a post; not directly, but through the media gallery, through which you upload your GPX files. Ultimately, you can embed those anywhere using shortcodes and also provide some custom information for each post, to be displayed alongside the core track data.
It's a bit behind with the updates as well, but I recommend it for a simpler, more track-centered approach.
Find out more and get it here: https://wordpress.org/plugins/lf-hiker/.

Progress & Management

The milestones area usually paints a good outlook on the workload for the current release, as well as the past and planned releases.
You might also be interested in the issues area, for the gruesome details about what's currently on the table.

Project board

Another area that might interest you is the project board.
Since, for some reason, the project does not appear in the Projects tab, I don't have any other option other than to announce it here.
At any rate, that's where you shall find pretty much every idea I have for this project along the way in a - for now - semi-formal to informal aspect.
Project notes that I commit to as actual development work will be converted to github issues and shall also appear here.

Stucture of the project board:

• To do bucket column: any idea enters the project management workflow using this column;
• To do for current version (x.y.z) column: ideas that are good candidates for implementation in the current version are moved here; not all may remain and they can either fall back to the To do bucket or move to Nice to have for current version (x.y.z) (see below);
• Nice to have for current version (x.y.z) column: ideas that may or may not be implemented in the current version, due to time constraints vs. usefulness ratio;
• In progress & Done columns: pretty self-explanatory.

What it does

This plug-in provides two basic features:

• allow some structured information to be filled in, according to a selected trip type;
• allow some GPS track to be uploaded and then rendered on a map.

Structured technical information

Structured technical information is supported for the following types of trips:

• Bike trips;
• Hiking trips;
• Train rides.

For bike trips

The following fields are available:

• Total distance;
• Total climb;
• Difficulty level;
• Access information (how to get to the start point and return from the end point);
• Open during seasons;
• Path surface type (eg: dirt, asphalt, grass etc.);
• Recommended bike type (eg: MTB, road bike etc.).

For hiking trips

The following fields are available:

• Total distance;
• Total climb;
• Difficulty level;
• Access information;
• Open during seasons;
• Path surface type;
• Route markers.

For train rides

The following fields are available:

• Total distance;
• How many trains were exchanged;
• Line gauge (mm);
• Railroad operators used;
• Line status (closed, operational etc.);
• Whether the line is electrified or not;
• Line type.

The track

I really wanted to host the GPS tracks myself for various reasons:

• Didn't want to depend on any third party provider;
• It was good fun writing this feature;
• I want to use the resulting data in the near future to do some other stuff on my website.

Thus, I developed a module to do just that: upload a GPS track (currently only GPX and GeoJSON files can be uploaded), parse it and display it.

JSON-LD front-end data

The plug-in, as of version 0.2.8 inserts structured JSON-LD data in the post and page details page, if there is track data attached to that post or page.

This behaviour is configurable and can be disabled or enabled in the plug-in's configuration page. By default, it is disabled.

Here is a sample JSON-LD data set inserted by this plug-in:

<script type="application/ld+json">
{
	"@context": "https://schema.org",
	"@type": "Place",
	"geo": {
		"@type": "GeoShape",
		"box": "45.69152 23.72547 46.01246 25.27592"
	},
	"name": "Towards Eagle's lake"
}
</script>

Maintenance

As of version 0.2.8, there is a new Maintenance section, which allows you to carry out various maintenance tasks:

• Clear all cached track data information;
• Clear all plug-in related information (all post trip summary, all cached data and all stored track files);
• Detect which posts that should have track data information are actually missing track files.

The box is described by the south-west and north-east points, in lat-lng format: Lat1 Lng1 Lat2 Lng2.

Supported languages

The following languages are supported:

Language	Code	Notes
English	en_US	Also serves as default language
French	fr_FR	-
Romanian	ro_RO	-

Changelog

Version 0.2.8

• Added shortcuts to plug-in's entry from the plug-in listing page;
• Added maintenance page with the following tools: clear cached track data, clear all trip summary info, detect posts that have missing track files;
• Added JSON-LD structured data to posts or pages that have trip summary track data (type Place, with box GeoShape);
• Added additional REST API field to WP-JSON post endpoint to return trip summary data;
• Fixed MysqliDb dependency - The MysqliDb generates deprectation warnings and needs to be updated (Issue #79);
• Fixed JS warnings caused by including editor scripts in non-editor pages (Issue #78);
• Added trip summary audit log to post edit and post listing pages (Issue #80);
• Updated UI + UX of the lookup data management editor page (Issue #77);
• Fixed trip summary shortcode block not rendering in post/page view;
• Fixed trip summary shortcode block editor widget not showing up.

See the entire changelog here

Roadmap

Road to Version 0.3

Version 0.2.0 was the first I deemed fit to actually be published as a plug-in. From there on the main purpose of all 0.2.* versions is to:

• improve stability of the plug-in by:
  • actual bug-fixing (of either reported or found as result of manual testing);
  • expand the set of available automated tests (in-progress);
  • gradually update the set of third party components (in-progress).
• improve the overall usability of the plug-in (meaning the minimum amount of features to render it usable enough for most of the users):
  • allow users to see at a glance, when listing posts, which post has trip summary information and track data and which has not;
  • improve trip summary editing experience;
• add some options to allow for quick customization:
  • customize the colour of the line used to plot the track on the map;
  • customize the weight of the line used to plot the track on the map.
• improve localization by adding at least one more language:
  • French translation has been completed.
• publish a guide for customizing the front-end trip summary viewer (planned for 0.2.5);
• add some nice to have features, which can be quickly implemented and provide some value, such as:
  • display minimum and maximum altitude (planned for 0.2.5);
  • compute and display an altitude profile;
  • display GPX waypoints;
  • allow the trip summary viewer to be added as a shortcode anywhere in the text (planned for 0.2.5).
• publish a list of things with which anyone can help, if he or she desires to do so;
• refactoring (on-going).

Version 0.3 and onwards

There are a lot of features I would like to see implemented in this plug-in and I would also be curious about your input on this matter. However, there is no definitive plan for it, but, as a general rule, I would like to see a maintenance realease every other release, to keep things stable enough.

Requirements

For running the plug-in itself

1. PHP version 7.4.0 or greater;
2. MySQL version 5.7 or greater (with spatial support);
3. WordPress 6.0.0 or greater;
4. libxml extension;
5. SimpleXml extension;
6. mysqli extension;
7. mbstring - not strictly required, but recommended;
8. zlib - not strictly required, but recommended.

For development

All of the above, with the following amendments:

1. xdebug extension is recommended;
2. phpunit version 5.x installed and available in your $PATH, for running the tests;
3. wp (wp-cli) version 2.x installed and available in your $PATH, for initializing the test environment, if needed
4. phpcompatinfo version 5.x installed and available in your $PATH, for generating the compatibility information files
5. cygwin, for Windows users, such as myself, for setting up the development environment, running unit tests and the build scripts, with the following requirements itself:
   • wget command;
   • curl command;
   • gettext libraries;
   • php core engine and the above-mentioned php extensions;
   • mysql command line client;
   • subversion command line client;
   • zip command.

Limitations

1. Currently it only works with the classic WordPress Editor. An update is planned for 0.3. (Now available since 0.2.4).
2. Not designed for (and not tested with) multi-site installations. No update is currently planned.
3. Currently only supports GPX and GeoJSON files as a way to upload GPS tracks. KML will be supported round about 0.3, maybe earlier.

Screenshots

Editor - Info

Editor - Map

Viewer - Info

Viewer - Map

Viewer - Map with altitude profile

How can you help

Despite my best intentions, it would be really hard to come up with a stellar product without any help from those who would either be really interested in using it or would like to work on such a product.
See here how one can contribute.

Credits

1. PHP-MySQLi-Database-Class - small mysqli wrapper for PHP. I used it instead of the builtin wpdb class
2. MimeReader - PHP mime sniffer written by Shane Thompson
3. jQuery EasyTabs
4. Select2 - A jQuery Single/Multi Select plugin
5. Leaflet - open source JavaScript library for interactive maps
6. Machina - JavaScript state machine
7. NProgress - slim JavaScript progress bars
8. Toastr - Javascript library for non-blocking notifications
9. URI.js - JavaScript URI builder and parser.
10. Visible - jQuery plugin which allows us to quickly check if an element is within the browsers visual viewport regardless of the window scroll position
11. blockUI - jQuery modal view plug-in
12. kite - super small and simple JavaScript template engine
13. Leaflet.MagnifyingGlass - Leaflet plug-in that adds the magnifying glass feature: enlarging a discrete area on the map
14. Leaflet.fullscreen - Leaflet plug-in that allows the map to be displayed in full-screen mode
15. Tipped JS - A Complete Javascript Tooltip Solution
16. PHPUnit - The PHP Unit Testing framework
17. Parsedown - Better Markdown Parser in PHP. http://parsedown.org
18. Faker - Faker is a PHP library that generates fake data for you
19. Mockery - A simple yet flexible PHP mock object framework for use in unit testing with PHPUnit
20. Parsedown Extra - Markdown Extra Extension for Parsedown

License

The source code is published under the terms of the BSD New License licence.

Donate

I put some of my free time into developing and maintaining this plugin. If helped you in your projects and you are happy with it, you can...