GENUKI Maintainers' Pages

Version 1.17

Developer CGI Scripts

Contents scripts

A separate page is provided which documents the instructions on how to generate the files needed to display the GENUKI Contents and Site Map web pages. The documentation includes descriptions of the Perl scripts, templates, dBase files and other structures required.

Spider scripts

The cgi scripts used to generate the various spider reports each generate a different format, and content, of report as follows:

Problem reporting script

The GENUKI problem reporting script, problems, is usually invoked from the standard page terminator (see the parish terminator as an example). However, depending on parameters, it can be invoked from other locations. The final result of invoking the problems script is that an email is sent from a user to a maintainer.

The script uses the GENUKI maintainers table to find the maintainers email address, and the section table to identify who is responsible for web pages and other section roles.

The script can be invoked with up to three positional parameters, and a keyword parameter, separated by ampersand (&).

The first positional parameter is the section code, which in the case of a county section is the Chapman county code (see here for a list of section codes).

The second positional parameter is some text used to identify the web page which is the subject of the email and, in the case of a county section, is usually the name of the parish or township. Spaces in the parish or township name should be replaced with %20 as usual.

The third parameter is the role code and defaults to web if missing (also see here for a list of roles)

The keyword parameter is used to force the email to be directed to a specific maintainer identified via the maintainers table. The keyword is PERS=initials, where initials are the maintainer's initials used as the index to the maintainers table. See the maintainers page to locate the maintainers initials.

For examples:

The script builds a web page with a form for the user to enter their problem report. The web page is based on skeleton text that can be tailored for each section. The script adds a standard page header with an up-icon to the section web page indexed by the section code. When the user presses the "send" button, an email is sent to the page maintainer, and a final "Thank you for commenting" page is displayed to the user.

The skeleton text is obtained from a file named Help.txt located in the top level directory of the section. If the file doesn't exist at the section level, general GENUKI skeleton text in the top level directory at is used. Alternative file names of ChurchHelp.txt and gaz_Help.txt are used if the roles chdb or gaz are used as the third parameter.

A good example of a skeleton Help.txt file can be found on the Lancashire pages.

The skeleton text should consist of HTML code, but does not form a complete web page, as the headers and trailers are created by the cgi script. The following strings in the skeleton are replaced when the web page is built by the script:

If the task has been flagged as requiring a new maintainer appropriate text is inserted on the resulting web page with a link to another person to handle that via the problems script but using a section code for the country rather than the county. For non-county pages it uses the "Org" section code.

The maintainers script

The GENUKI maintainers script, maintainers, is intended to display entries from the maintainers table and the relationship between maintainers and sections. It can be invoked from any location. The final result of invoking the maintainers script is the presentation of an information page.

The script uses the GENUKI maintainers table to find the maintainers email address, and the section/task table to identify who is responsible for web pages and section tasks.

When invoked with no parameters the script lists all entries in the maintainers table in alphabetical order by maintainer surname. Each item in the list refers to one maintainer and includes a link to the maintainers details (also invoked using the maintainers script - see below), and a link to each section and/or task for which the maintainer is responsible.

The section/task link is executed by invoking the spider's section script (see above).

The maintainers detail page is presented by invoking the maintainers script with the parameter ID=initials where initials are the maintainer's initials used as the index to the maintainers table.

Gazetteer scripts

A number of CGI scripts are available to access the gazetteer information in a number of ways. See the gazetteer script definitions for details of how to use them.

Note that Ireland and the Channel Islands are now handled in a manner consistent with that used for the UK.

The gazetteer scripts are:

Controlling placement of the search results

This section refers to the displays produced by scripts places and nearby.

The search results are designed so that the places it shows are sorted according to the distance from the start point, with all the places covered by an individual town or parish page grouped together with it. This is achieved primarily by sorting by distance, but also using information in various database fields as well.

The search results initially appear as two sections, the first with links to GENUKI pages, and then the rest. The second section are those entries in the database with an empty URL field. It is expected that over time, the second section will disappear as URLs are aded to the existing entries.

The entries that are grouped under a town or parish page entry all have the URL of the town or parish page. The thing that distinguishes them as being subsidiary is the PRIME flag, which is set to "Yes" only for the town or parish page entry.

The places that can appear at the start of the subsidiary group as just a list of place names separated by commas without a distance and grid reference are defined as follows. They have the same grid reference and URL as the town or parish page entry but they also have the unspecific location flag set. This means that the place is somewhere within the town or parish but we don't know or can't say exactly where it is. This can also be used for alternative names e.g., Welsh and English, or where places have changed their name over time, e.g. Poulton le Sands is now called Morecambe. If you have an alternate name or alias for a place, create an identical entry to the primary, but put the alias in the place name field and set the UNSPEC field to "Yes".

Miscellaneous scripts