Route plugins

The plugins to generate the route output (route and itinerary at present, not PDF) are stored in /plugins/output/

To create a plugin:

add a directory with an appropriate name in /plugins/output/, for example /plugins/output/books/. This should be a single alphanumeric word - it is used as an identifier in code. Create the following files within the directory:
a config.hdf file
a code.can file (if needed) which will be run when generating the page
a template.cst file which generates the page
other template files can be here as well if you want to break it down
a javascript.js file which contains functions activated by users clicking on items in the plugin output, and any customisation code for the plugin (to adjust the output based on user options)
other javascript files can be present here to be loaded dynamically.

each of these is further documented below.

You can disable a plugin entirely by prefixing the name with _ (for example _information). This is useful when developing or to hide something that has broken that you intend to fix later

code.can

If all the code - probably for historical reasons - is in the main program, setting "nocode" in the config.hdf file prevents this from being used.

Otherwise, this file should contain a function Plugin that takes a single lookup parameter which is the parsed config.hdf.

If it calls any sub functions or procedures, it should use the name of the plugin as a namespace - for example books$do_stuff

It may also contain a function Plugin_preload that take no parameters. This is run before the route is generated and generally is used to set flags on places for when they are included in the output.

template.cst - NOT REWRITTEN/CHECKED YET

This should access the plugin data and configuration using data.plugins.plugin-name.data and data.plugins.plugin-name.config

To call a javascript function from the generated HTML, do it using Page_Call_Plugin_JS('plugin-name','function name,parameters) This will load the plugin javascript file if needed and call the function.

javascript.js - NOT REWRITTEN/CHECKED YET

Contains all JavaScript code in support of the plugin. Most functions should be called using Page_Call_Plugin_JS in response to user activity. All functions should be placed in an object derived namespace named after plugin_plugin-name - this means that a function definition looks like, for example plugin_photos.options_display = function() {

Can contains a function called personalise

This function will be called at page load if conditions met in config.hdf are met. This is to reconfigure the plugin display to user preferences (hiding some items for example).

Can contain a function called options_display

If the config for this plugin contains the "need_configuring" flag in the options block, then the JavaScript file will be loaded and this function called whenever the plugin is selected and the options relating to it displayed. It will also be called when any option containing the "has_dependencies" flag is altered. It should consist of a series of tests of option value that turn on and off, or set defaults, for other options.

config.hdf

All files should contain:

rank – a number that has no direct meaning, but plugins are output ordered by the rank. Initially set up with reasonable distances apart to allow space for new additions
title – to be displayed in the "collapse" banner and when setting options
text – explanation to be displayed when selecting in options
showon – a list of which pages (route/itinerary/printout) this plugin should be displayed on - all present as "yes" or "no"
template_prefix – without this, all modes will use "template.cst", with a prefix for a mode that template will be used instead
nocode - there is no need to load and run the code.can file
default_state - ("on" or "off"): should this be shown by default, or only when the user asks for it?
an options block - this is documented below
any parameters specific to a plugin and used only in that code/template

config.hdf - the options block

This block defines all options that are shown on the preference page, and captured in sessions and user records.

a group called options - this contains a list of items, each defining an option

Each option should be named by the value that will be used elsewhere in the code. So, for example, a block called "mode" in the "route" plugin will be displayed on the preferences page as outputopt_option_route_mode, and will be stored in the options variable as plugins.output.route.mode. The block of code for setting it on the preferences page will be called output_options_plugin_option and this is useful for showing/hiding individual options.

Because of this, option names must not contain underscores and must be valid identifiers otherwise (alphabetic strings recommended).

An option can contain the following fields:

type - "select" or "checkbox" at the moment
default - must be present, the default value for the option
label - the label text for the option

Option types has specific fields

select:

byindex - if present and "yes" then the value stored for the selector is the index, not the text
values - a 0,1,2,3... listed set of values for the selector if not "byindex"
values - a list of pairs of indices and texts for the selector

checkbox: