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:

• spider: the Overall report. No parameters.
• section: the Section report. Parameter CCC=section_name, where section_name is the name of the GENUKI section being reported. In most cases this will be the 3-character Chapman County Code.
• section_files: the Files report. Parameter CCC=section_name (see above).
  • HTML files. Parameter mtype=0.
    • Section home pages. Parameter type=1.
    • Town/parish pages. Parameter type=2.
    • Parish map pages. Parameter type=3.
  • image files. Parameter mtype=1.
  • other files. Parameter mtype=2.
• section_problems: the Problems reports. Parameter CCC=section_name (see above).
  • spider. Parameter type=0.
  • link. Parameter type=1.
  • redirects. Parameter type=2
  • timeout. Parameter type=3.

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:

• http://www.genuki.org.uk/cgi-bin/problems?LAN&Non%20Existent%20Place
• http://www.genuki.org.uk/cgi-bin/problems?SAL&Shropshire&chdb
• http://www.genuki.org.uk/cgi-bin/problems?&maintainers&PERS=pts

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 www.genuki.org 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:

• $COUNTY - The name of the county.
• $PLACE - The place name supplied as the second parameter to the cgi-script. If no place name is given, the text provided is "the town/parish".
• $PLACEORCOUNTY - The place name, or if none is supplied then the county name is substituted instead.
• $BURL - The base URL of the section e.g. the URL of the county page

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:

• gaz: In your list of town and parish pages you can add a call to the gaz script to enable users to find the pages for other places within your county. Remember to include a hidden CCC parameter to default to your county. Can be called without specifying any parameters in which case a form is displayed allowing searches to be made. Parameters:
  • PLACE=Name of the place you are searching for.
  • CCC=Chapman county code used to restrict searches to a single county. YKS searches all four parts of Yorkshire.
  • TYPE=The of search to perform. The values allowed are:
    1. Complete word (default)
    2. Exact match
    3. Word ending
    4. Word beginning
    5. Word containing
  
  
• gazplace: A means to display a parish style page for an individual gazetteer entry with links to online maps and any other location specific information. The three parameters required should make it possible to match a single gazetteer entry. However if that entry changes you will need to change the link to find it again. Parameters:
  • GR=The grid reference.
  • PLACE=A field to hold the name of the place you are searching for. This is not the name field that is in the gazetteer database entry, but an adjusted one used for smart searching. It is therefore all upper case, with extraneous words removed e.g. "in", "by", "cum" etc. and with punctuation e.g."-" replaced by space, and all multiple spaces converted to a single one.
  • CCC=Chapman county code.
  
  
• nearby: Shows all the places within a specified distance of a specified start point. It is recommended that you add a link on a town or parish page to search the gazetteer and show nearby places, using the button bar at the top of the page. The call to locate nearby places is via a link to the nearby cgi script. Parameters:
  • CCC=xxx section/chapman code
  • GRIDREF=xxnnnnnn OS grid reference
  • LAT=nn.nnnnnn latitude
  • LON=nn.nnnnn longitude
  • PN=xxxxx place name (used to make the results page more informative)
  • UNITS= m or k (miles or kilometres, default is miles)
  • DISTANCE=n (default is 5)
  
  
• howfar: Calculator to find the distance between two places. Parameters:
  • FROMGR=The grid reference of the starting point.
  • FROMLAT=Alternative to using FROMGR.
  • FROMLON=Alternative to using FROMGR.
  • FROMPN=The place name of the start point. Not used in searches but makes the following pages easier to understand.
  • CCC=Chapman code of the start point.
  • The following parameters are not normally used on initial calls to this script, but are used at later stages by the script itself:
    • GRIDREF=The grid reference of the destination.
    • TOPN=The place name of the destination.
    • TOCCC=The Chapman county code of the destination.
  
  
• maplink: A quick and easy interface from a grid reference to provide links to online maps, nearby places and the howfar distance calculator. Rather than link directly to a mapping site, it is recommended that all links to online maps are made via this script. Parameters:
  • GR=The grid reference of the starting point.
  • CCC=The Chapman code of the start point. If you don't supply it there won't be link to the oldmaps site.
  • PLACE=The place name of the destination. Only used to make subsequent screens easier to understand.
  
  
• placemaps: Under the Maps category heading on a town/parish page, you can put a call to the placemaps script, which shows a page with links to online maps for all the places recorded as being within this town/parish. If it is called with no parameters it uses the URL of the page on which the link is placed as the key to find the information, i.e. it shows the names of all places in the gazetteer which have the same URL in the url field as the page from which the call to placemaps was made. But some browsers don't always supply this information so it's better to supply a GR= parameter. However, if there's not an exact location for the town/parish in the gazetteer, using the GR= parameter will mean changing both the gazetteer entry and the call to this script when the exact location is determined. Parameter:
  • GR=The grid reference of the starting point.
  
  
• showmap: This is the script that provides our primary interface to Google maps to show places. The original functionality, and new displays are obtained by the use of parameters:
  • GR=The grid reference of the starting point.
  • T=The type of map to be drawn.
    • PP - Places in the parish (the original script functionality).
    • SP - Draw Google map for for a single place.
    • NP - Draw Google map for the place specified and mark the nearby places identified as primary township/parish pages.
    • AP - Draw Google map for the place specified and mark all nearby places.
  • Z=The initial zoom level on the Google map. The default is Z=5. Increase this value if you are standing further back from the map and want to see a larger area with less detail. Z=9 seems to be suitable to show the whole county.
  • D=The distance, in miles, for searches for nearby parishes. the default is D=5.
  
  
• gazextract: Provides a dynamic report listing the urls of the section's town and parish files. This list is obtained from those gazetteer entries for the section which have been flagged as primary entries.
  
• places: This is now deprecated.
  

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

• piclink: Similar to maplink above, this script provides a quick and easy interface to online picture sites. The parameters are the same as for maplink.