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.

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.

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.