An update

We’ve been neglecting this blog for far too long.

There has been a huge amount of work done on both the Canalplan AC website and the Canalplan Plugin for WordPress.

A few months ago we took over the day to day running of Jim Shead’s Boat Index which involved moving the data over to our server and rebuilding the query pages so that they fitted in with the rest of the Canalplan Website. That integration also allowed us to add features to both the Boat Index and also to Canalplan such as tagging boats in photos and also the first steps of a boat tracking system.

Most of the work with the Canalplan Plugin for wordpress has been addition of minor new features such as being able to include links to Canalplan “Features” in your posts and lots of bug fixing in the Route importing code. The big new feature was replacing the “Where am I” widget which used to use Google Latitude with a version that uses Backitude which also links to the boat tracking feature in the main canalplan site so you can update both your blog location and your location on Canalplan in a single go.

Posted in Uncategorized | Leave a comment

The Canalplan Plugin : Configuration Part One

It’s time for the second post about the Canalplan Plugin for WordPress. The first post covered the way you can use the plugin short codes to embed links to Canalplan Gazetteer entries and Canalplan maps into your posts and gave a basic introductions to some of the features of the plugin.

This one will cover the general configuration of the plugin so its probably going to be a little boring in places but hopefully not too much.

Overview

Once the plugin has been downloaded and activated you should see a new menu in the WordPress Admin menu – this menu (CanalPlan AC) has a set of submenus which allow you to set up various parts of the plugin :

General Options
This sets up various general options for the Canalplan plugin such as the Distance Format and your Canalplan AC link code

Home Mooring
This allows you to set your home mooring location and give it a customised name

Favourite Locations
This allows you to set up some favourite locations and give them customised names.

Google Map Options
This allows you to set up the various options to do with how Google Maps are displayed.

Diagnostics / Version Information
Provides information and diagnostics – You’ll need to refer to this page if you’ve got problems.

I’ve actually skipped three sub menus because they’re associated with interaction with Canalplan AC at a much deeper level which will be covered in a subsequent post :

Import a route from CanalPlan AC
This is the starting point for importing a route from Canalplan AC and creating a set of blog posts for the imported route

Manage Imported Routes
Once you’ve imported a route you might need to make adjustments to the daily totals – this page allows you to do that

Bulk Link Notifier
During normal use the Canalplan AC website will learn about links from you blog back to it’s gazetteer. However if you’ve just added a set of posts you might want to let Canalplan AC know about all the links.

Now we can get onto each of the sub menus in detail :

General Options

This page contains a few things that really need to be set up before you can use the Canalplan Plugin in any meaningful way.

Canalplan Data

Before you can do anything with the Canalplan Plugin you need to get a copy of some data from the live Canalplan AC website. When the plugin is first installed there is no data there and you will be presented with the folowing screen:

Click on the Get Data button and wait a few minutes…. The plugin needs to go to the Canalplan website and pull down a subset of its database. The download is approx 1.8MB (the main Canalplan database is 225MB) so hopefully it shouldn’t take too long. One thing that is very important to remember is that the data pulled down by the plugin can be up to 24 hours old as it is built once a day from the live database so if you’ve just added a place it wont appear in your plugin if you immediately refresh the data.

Once the data has downloaded the screen will refresh and you’ll be presented with the following:

Notice that there is no button to allow you to download the data again. The plugin will not display the download button until at least 24 hours have passed at which time it will display it again.. the following screen shot is from a system that had not updated its Canalplan data for quite some time:

At the moment the plugin doesn’t automatically run an update on a fixed schedule but its something that I might look at adding if there is enough demand.

Note for Networked blog users : As the plugin only uses 1 set of tables per network then any blog that runs a data update for their blog actually runs the data update for all the blogs in the network.

Distance Format

Traditionally canal distances are measured in Miles and Furlongs but rather than force that on everyone the plugin allows you to set the default measurement unit that is used when the plugin is displaying distances as part of its trip blogging features :

The distance formats supported are:

  • Decimal Kilometres (3.8 kilometres)
  • Kilometres and Metres (3 kilometres and 798 metres)
  • Decimal miles (2.3 miles)
  • Miles and Yards (2 miles and 634 yards)
  • Miles and Furlongs (2 miles , 2 ¾ flg)

It is possible to change the distance format on a route by route basis so if you usually blogged about trips in the UK but then wanted to blog about a trip in France then you could change the distance format for that specific set of blog posts.

Canalplan Key

One of the features of the Canalplan plugin is its deep linking between your blog and the Canalplan Website. This is done silently in the background and involves using a Key to uniquely identify links from your site. This option shows you what your current key is, the blog url and the title of the blog it is associated with. If you have not previously set the key then the Plugin goes out to Canalplan and negotiates a key and prompts you to save it:

Once you have done that then the key is valid until you need to change it:

If you change your blog URL or title, or if you need to change your key for other reasons, then you can click on the Reset Canalplan Key and a new key will be issued to you

Note for Networked blog users : The key is unique to your blog so each blog in a network has its own key.

Route Page Slug

This is, as with the distance format option, related to the route blogging features of the Canalplan plugin. If you don’t intend to use the route blogging features of the plugin then you don’t need to worry about this.

The idea is that you have a single page in your blog which contains links to each of the trips you’ve blogged, and each of those trips contains a link to the individual posts for that trip. For this to work you need to have a specific page set up for this, and this option allows you to set what that page should be. In single blog (i.e non networked) mode this page slug is not initially set:

Once you’ve set a page slug the plugin will tell you what page it expects to find :

In the above example we’ve set the trips page slug to be trips.. so we would need to make sure that the page existed and that it contains the text {BLOGGEDROUTES}

Note for Networked blog users : To allow the “root” blog in a network to have a single page to display all the trips that have been blogged about in the network the slug is set centrally by the network administrator so you will not get the option to change it in your blog. Instead this option will display something like:

In the next post we’ll cover the next steps you need to carry out to get the most out of the Canalplan Plugin for simple blogging. Using the Trip importer and the route blogging features will be covered in its own post.

Posted in News, Programming, Wordpress Plugin | Tagged , , | Comments Off

A quick introduction to the Canalplan AC Plugin

I thought that it might be a good idea to do a set of posts on the various features of the Canalplan AC Plugin for WordPress and how to use it even though the plugin does contain its own user guide.

The plugin enables three distinct sets of functionality:

  1. Easy linking of Canalplan places, canals etc into your blog posts.
  2. Back Linking from Canalplan Gazetteer entries to corresponding posts in your blog.
  3. “Cruise” blogging from a route imported from CanalPlan.

I plan to cover each of these areas of functionality in separate blog posts along with one covering the various customisation options the plugin supports. In this post I plan to basically cover some of what the plugin can do in general, and if you think bits of this sound familiar its because I’ve “borrowed” bits from previous posts on the subject.

Canalplan Locations – linking and Micro maps

WordPress makes adding links to a post quite easy but to add links to places in Canalplan you’d need to keep getting the urls from Canalplan and posting them into new links. This might be OK for one or two posts but what if you want to actually put a lot of Canalplan places into a blog post.. it would become a complete and utter pain. So the Canalplan Plugin makes this a complete doddle by adding a new input to the Edit Post screen which allows you to find a Canalplan location and insert a link into your post simply by typing a few letters and clicking on a button. You can insert places as either links to Canalplan Gazetteer entries such as :

[[CP:Market Drayton|tnj9]] which presents a link Market Drayton

or you can do it as “micro map”

[[CPGM:Market Drayton|tnj9]] which renders a little Googlemap of the location:

There are a couple of additional options which can be manually inserted to override the defaults which are set on the Plugin page. These options allow you to change some of the map parameters. For example

[[CPGM:Market Drayton|tnj9|height=400,width=300,type=t]] produces a larger map that the normal map and I’ve changed the map type to “t” (terrain) :

Of course for those of you who want to show somewhere off the canal system – well you can do that too!

Here is somewhere I used to work :

which was produced using the following code:

[[CPGM:Steve's Office|nothing|lat=52.077994,long=-2.299249,type=s]]

If you hover over the pin in the map you’ll see it contains the text that is shown in the tag, and I suspect you might have already worked out that if you change the text in the first part of the Canalplan tag that it changes the text used in the link/map – so:

[[CP:Market Drayton (Newcastle Road)|tnj9]] would make the following link Market Drayton (Newcastle Road)

So that’s single places dealt with but Canalplan AC also has complete canals in it… so it would be good if the plugin allowed you to basically do what we can do with single locations but with whole canals wouldn’t it? Well it can:

Canalplan Waterways – linking and Maps

Say you’re writing a blog post about the Leeds and Liverpool canal, specifically the Main Line – Wigan to Leeds, and you’d like to link to the Canalplan gazetteer entry for the canal. You could do it by creating a link containing the following url : http://www.canalplan.eu/cgi-bin/waterway.cgi?id=779v

Or you could use the Canalplan linker and again by typing a few letters (to pick the right canal) and a click and your post ends up with [[CPW:Leeds and Liverpool Canal (Main Line - Wigan to Leeds)|71jn]] which creates a nice link for you: Leeds and Liverpool Canal (Main Line - Wigan to Leeds)

But rather than link out to a map wouldn’t it be even better to have a map in your blog post?

[[CPGMW:Leeds and Liverpool Canal (Main Line - Wigan to Leeds) |71jn|type=h]] produces a nice map in your post:


Or how about the Shropshire Union Canal (Llangollen Canal - Main Line)

The two examples above show single parts of a Canal which is how CanalPlan stores its canals. But what if you want to show an entire canal? You don’t need to try to patch together bits, we do that for you.

So here’s the complete Leeds and Liverpool Canal :

Or how about the sprawling mess that is the Shropshire Union Canal ?



These last few examples show customisation to the default map with different colours and differing thickness for the line used to draw the canal.

These link and map codes are the basis of most of the functionality of the plugin. In the next post I’ll cover how we actually embed these short codes into a blog post.

Posted in News, Programming, Wordpress Plugin | Tagged , | 20 Comments

What’s under the bonnet in CanalPlanAC: Part 2 – data formats

Over the years CanalPlanAC has accumulated a host of data formats for various purposes. At least two – a custom C-like syntax (surprisingly similar to another I’ve adopted!) and “quick load” place and link files – are entirely obsolete but support for them still lurks in the interpreter.

Here are the main ones that anyone playing with the system might come across:

  • SQL – since summer 2008 the main database for CanalPlanAC, the users, the information about photographs, some of the program flow control and state information during a session have been stored in SQL databases. I’m using SQLite – this is small and can be directly integrated into the interpreter making setup very easy.
  • XML – until then XML was used for the master data file, and quick-read varieties in a sort of unstructured text file were generated. The unstructured files are also obsolete (although some support may still exist in route.c until I rip it out) but XML is still used although much more round the edges these days. In particular, it’s used for:
    • Sending data to some Javascript utilities.
    • Storing the configuration file /cgi-bin/config.xml which tells the program where all the data should be stored and similar things
    • To store the default user options in a file, and the user options (in a blob) in the user SQL database
    • To define options for gazetteer plugins (to be described some other time!)
  • JSON – not used statically, but used for a number of inter process and code communications (particularly those involving Javascript)
  • HTML – static pages are written in HTML
  • CST - ClearSilver Templates. Since summer 2007 pages are generated from template files. This is an extended form of HTML with ClearSilver directives built into it – see the website for more.
  • HDF – this is the configuration file language for ClearSilver. I didn’t have to use this, I’ve integrated ClearSilver so tightly I can easily pass it any format I like, but it seemed sensible. The most important HDF file is /templates/default/config.hdf which controls all the menus and buttons on all the pages.

So there you are. A pile of formats, but many of them widely known, and many of them only used in a few places. In the next few articles I’ll show how to add a sophisticated new feature (the Virtual Cruise) to CanalPlanAC and you’ll see how these various languages and formats are used.

Posted in Programming | Tagged , , , , | Comments Off

What’s under the bonnet in CanalPlanAC: Part 1 – programming languages

OK, at the moment no-one is developing the program apart from myself. But it struck me that if I documented a few things as if people were, then I’d have a lot of stuff ready if ever I get a co-developer or even hand on the project.

The Canal Planner situation has, I think, shown us the danger of a project like this being all in the mind of one individual.

So what I’ll be doing from time to time is documenting how I did particular things, in a sort of “tutorial” way.  But before I do that, I thought I’d start with a sort of apology for the number of languages (big and small) used in CanalPlanAC.  I thought it might be fun to document them all – but don’t let this put anyone off: you don’t need all of them at any one time.

  • C – the Interpreter that underlies CanalPlanAC is written in C.  This can remain unchanged for months, until I discover a bug or find the need to add a feature right into the language.  What tends to happen is that I write something in the scripting langauge but find it too slow or too cumbersome, so add it as a language feature instead.    There is – as yet – no modular extensibility to the C: there are about 35 thousand lines of C in 87 source files that I’ve written,and a chunk more in various pieces of “foreign” code that are linked in.
  • CanalPlanAC scripting language.  I have no name for this language, which can be invoked interactively by /cgi-bin/canal/ or to execute a file as /cgi-bin/canal file.can.  This is a basic like language that deserves another dozen items on the syntax.  It was vaguely inspired by Superbasic which could give you a few pointers to some of the syntax.  Key things about it are:
    • An intermediate typing system where all values are one of a number of types, and get coerced from one to the other when assigned.
    • Support for associative arrays (called “lookup” tables) and lists
    • Inline operators: this is a mixed blessing – a line like «if a contains “hello” then …» is easy to read, but precedence sometimes goes wrong.  (So «print ‘this is me and you’ after ‘me’ contains ‘you’» produces the whole string (because it parses as evalutate «’me’ contains ‘you’» which is 0, then returns the original string after character 0.
    • Built-in comprehension of a waterways network with the ability to plan routes aroung it and travel along them.
    • Built-in read/write of SQL, JSON and XML
  • There are a few small bash scripts, mainly to kick off CanalPlan programs.
  • There is the whole automake/autoconf nest of snakes in /source/ but that shouldn’t need touching.
  • Many web pages use Javascript (both home written and some appropriately licensed utilities) to do place name lookup, display maps etc.

Next – the data formats that these programs use to store data, communicate with them selves and talk to the user

OK, at the moment no-one is developing the program apart from myself.

But it struck me that if I documented a few things as if people were,

then I’d have a lot of stuff ready if ever I get a co-developer or

even hand on the project.

The Canal Planner situation has, I think, shown us the danger of a

project like this being all in the mind of one individual.

So what I’ll be doing from time to time is documenting how I did

particular things, in a sort of “tutorial” way.  The first thing to do

is to start with an apology for the number of languages (big and

small) used in CanalPlanAC.  I thought it might be fun to document

them all – but don’t let this put anyone off: you don’t need all of

them at any one time.

*C – the Interpreter that underlies CanalPlanAC is written in C.  This

can remain unchanged for months, until I discover a bug or find the

need to add a feature right into the language.  What tends to happen

is that I write something in the scripting langauge but find it too

slow or too cumbersome, so add it as a language feature instead.

There is – as yet – no modular extensibility to the C: there are

about 35 thousand lines of C in 87 source files that I’ve written,

and a chunk more in various pieces of “foreign” code that are linked

in.

*CanalPlanAC scripting language.  I have no name for this language,

which can be invoked interactively by /cgi-bin/canal/ or to execute a

file as /cgi-bin/canal file.can.  This is a basic like language that deserves another dozen items on the syntax.  It was vaguely inspired by Superbasic which could give you a few pointers to some of the syntax.  Key things about it are:

**An intermediate typing system where all values are one of a number of types, and get coerced from one to the other when assigned.

**Support for associative arrays (called “lookup” tables) and lists

**Inline operators: this is a mixed blessing – a line like «if a contains “hello” then …» is easy to read, but precedence sometimes goes wrong.  (So «print ‘this is me and you’ after ‘me’ contains ‘you’» produces the whole string (because it parses as evalutate «’me’ contains ‘you’» which is 0, then returns the original string after character 0.

**Built-in comprehension of a waterways network with the ability to plan routes aroung it and travel along them.

**Built-in read/write of SQL, JSON and XML

*There are a few small bash scripts, mainly to kick off CanalPlan programs.

*There is the whole automake/autoconf nest of snakes in /source/ but that shouldn’t need touching.

*Many web pages use Javascript (both home written and some appropriately licensed utilities) to do place name lookup, display maps etc.

Posted in Programming | Tagged , , , | Comments Off

Version 9.2.8.0

Here are the bug fixes and enhancements for Version 9.2.8.0

  • Extended that to all the SQL command interface, since it seemed to be working for that, but still getting problems elsewhere
  • And to the SQL database open as well
  • Added code to check database integrity. Started adding places for which I had photos but no places.
  • Prevented the “moderator’s” box for adding places from emails displaying for everybody else (as I’d always intended)
  • Started work on code to let places be added breaking lock flights
  • Input page for places that break the lock flight added – nice new slider added for splitting locks
  • Logon status added to new place page
  • Fixed a bug in the SQL locking code from Monday
  • The “moderators” box thing didn’t work – made it hard wired to me instead, as I’m the only person ever likely to do it
  • All updates are now executed as single transactions, so will be rolled back if they fail leaving the database consistent
Posted in Releases | Tagged , , | Comments Off

Version 9.2.7.0

Here are the bug fixes and enhancements for Version 9.2.7.0

  • Place with odd punctuation don’t break in “add a place” – failing to show anywhere else
  • Local end doesn’t fail when multiple changes affect the same bit of waterway (distinction between version in database and version in memory)
  • Added some random sleeping to the SQL code to prevent failing with database busy at the drop of a hat
Posted in Releases | Tagged , , | Comments Off

Version 9.2.6.3

Here are the bug fixes and enhancements for Version 9.2.6.3

  • Prevented pasted places going in if there is one with that ID already
  • Added a “COMMIT” stage to transaction logging, so failed transactions don’t clutter up the log
  • Fixed some bugs I’d introduced into “create user”
Posted in Releases | Tagged , , | Comments Off

Version 9.2.6.2

Here are the bug fixes and enhancements for Version 9.2.6.2

  • The simple edits to fields – text of places etc – are now tranasction logged
Posted in Releases | Tagged , , | Comments Off

Version 9.6.2.1

Here are the bug fixes and enhancements for Version 9.2.6.1

  • Fixed a bug in javascript for new place adding
  • Transaction logging working at both ends for new places. Added a number of recent new places to live version to test this – and because it needed doing.
  • Restored photo adding – small typo in hacked-out code
  • Typo in Makefile fixed so transaction logs don’t get sent
Posted in Releases | Tagged , , | Comments Off