GENUKI Contributors Technical Guide

See also the Contributors Quick Start Guide.

This document is intended to help people who have volunteered to help further develop individual GENUKI pages. Such volunteers - GENUKI contributors - have been provided with log in names and passwords, which they need to use in order to access the means by which such GENUKI pages are edited. Note that contributors are constrained by the system so as to able to edit only “their” pages. (Once they have logged in, the contributor's view of any GENUKI page that they are authorised to edit will contain "Edit" among its initial commands of commands - the others being "View", "What Links Here", and "Revisions".) 

The information provided to the viewers of GENUKI's pages ("GENUKI users") is held in a so-called "Content Management System" (CMS), in fact the Drupal system. The concept behind a CMS such as Drupal is that its role is the management of a website's data (i.e. of the website's "information content"), and of the look and feel of the website, leaving the contributors to the website to concentrate on providing the information without needing to know the technical details of constructing web pages. However, contributors are in fact able to exercise some control of the appearance of their information, so can define some of the "mark-up" (e.g. the use of italics and bold face characters), but do not need to know the intricacies of HTML (the web page coding language). 

Nodes and Pages

The Drupal component that matches GENUKI's pages is, in general, the "node". The node is constructed to hold the various pieces of information that will be shown in the page. The two main node types that have been defined for GENUKI are Place nodes (for all the standard county, town, parish, etc., pages), and Plain nodes for all those further GENUKI pages created to hold additional information in cases where this information is rather too big to go into the parish page. (A third type of node, a GENUKI topic node, which relates to part of a page rather than a whole page, is described below.) 

As a GENUKI contributor, after you have logged in (in fact to Drupal), you then have the ability to edit your Place nodes and Plain nodes, and so control the information content of the pages that these nodes define. When you have moved (either by following links, or by using the Search facility) to the page that you wish to edit, you can click on the Edit button and so reach an "Edit Template" for the node corresponding to this page. This shows you all the fields that comprise the particular type of node (Place or Plain), and provides "Help" information indicating how each field is used and is to be filled in. The initial fields in each node relate to such matters as page titles, contents listings, etc. You need to scroll past these fields to get to the field(s) where the actual data (information content) of the page is held. 

GENUKI's hierarchy of county, parish, etc., pages have a strictly defined structure and appearance. Within each such page, all information content appears under one or other of a defined set of topic headings ("Church Records", "History", etc.); a two-column listing of the contained topics is given at the head of each page. Drupal has been set up so as to facilitate, indeed to relieve maintainers from all responsibility for adhering to, this structuring. Thus each Place node's Edit Template provides an alphabetically-ordered set of separate "fields" (in particular "topic boxes") for all the possible topics. The Edit Template shows the topic boxes that already have some information content ahead of those that are still empty. Adding to, or editing existing information just involves editing the contents of the appropriate topic box.

When information is added to a previously empty topic box,  and the Save button (near the top of the Edit Template) is clicked, the Edit Template closes and the web page will be shown with the new topic in its correct place, i.e. all the topics with information content will be visible, in alphabetical order, with the correct topic headings, below an augmented two-column listing of the topics contained.

These two columns typically appear either side of a map. The address from which Drupal is to obtain this map is defined in one of the fields that preface the set of topic fields. (In fact the vast majority of parishes already have parish pages in GENUKI, complete with maps, so contributors will mainly find themselves with the straightforward task of filling in or editing topic fields in existing Place pages.)

Some information, such as map links, nearby places from the Gazetteer, and churches from the Church Database, is added to the place pages automatically, under appropriate topic headings. (Note: Such automatically-added information will not be shown in Place nodes' Edit Templates, and can only be edited via the facilities of the Gazetteer and the Church Database.) The inclusion of this information in place pages is achieved simply by a preset and unchangeable unique "place code" in each place node. 

In Place nodes there are also fields for the basic headers such as the title and a descriptive quote. 

Each Plain node (such as the present node) similarly has various fields for the basic headers, with the actual information content of the web page being held just in the one "Body" field.

Each topic or body field will be set to show the contents of the field as it will be shown in the web page, but providing you with a WYSIWYG ("What You See is What You Get") editing facility - see below. In WYSIWIG mode no knowledge of HTML is required. In the  HTML mode the HTML is structured in the sense that it employs new lines and indenting to clarify the syntax of the HTML text. In this mode only a limited set of safe HTML codes can be used. (The allowable HTML codes are listed under the topic box.) 

A very important safeguard is that all nodes are set to make a new revision each time you edit them. If you make a mistake you can switch back to a previous revision. You can also compare revisions and see the changes that have been made.

As mentioned, the Edit Templates for both the Place and the Plain nodes are intended to be essentially self-documenting, i.e. they contain explanatory information aimed at describing exactly how the various fields are to be used and filled in. Suggestions for improving these explanations are welcome.

There is no direct means of changing the type of a page, e.g. a Place Page to a Plain page. You would have to create a Plain node, and cut and paste the information into it, and  give it a different (temporary) URL. Then once you have saved the new Plain page and it looks alright, delete the no-longer needed Place node so that you can replace the new Plain page's temporary URL.

WYSIWYG Editing

The What You See Is What You Get (WYSIWYG) editor (whose actual name is ckEditor) shows a field's content (text and graphics) onscreen during editing in a form closely corresponding to the appearance it will have when it is shown as a web page. The editing is performed using a set of little editing buttons along the top of the box being edited - see the example figures in the Quick Start Guide. The meaning of these icons is fairly self-evident but can, if so wished, be discovered by hovering the cursor over them so as to reveal their "hints". (Here is some detailed tutorial material on this editing facility, should you need more detail than in the Quick Start Guide.) 

Of particular note is the Table icon. This enables you to create simple tables. Once a table has been created, if you position the cursor at the right hand edge of the table you can adjust the width of the table. Similarly you can position it on a column boundary to adjust the position of this boundary. If you position the cursor inside the table and do a right-click a small window opens up that provides you with a hierchical menu providing a rich set of facilities, e.g. for inserting or deleting cells, rows or columns, and for configuring cell size, type, colour, and content alignment.

There are also icons for "Find" (a little magnifying glass) and "Replace" ("^b_a"). These operate within a single field. When the "<>Source" icon (see below) is set to show formatted text (i.e. to allow rich text editing), these two icons are very similar to each other. Each when pressed opens up the same little window with two Tabs - "Find" and "Replace" - the Tab that has been selected simply depending on which icon was pressed. The Find Tab has a “Find what” box that allows one to match case, and/or match a whole word, and to determine whether to search cyclically for the desired item. The Replace Tab has a similar “Find What” box, plus a second box for the replacement text, and allows one to specify Replace or Replace All. (Thus the facilities provided by the Replace icon and Tab are an extension of those provided by the Find icon and Tab.)

The WYSIWYG editor shows a field's content in a box whose size matches that needed to show the entire content.  If you are editing a large text box (i.e. larger than a single screen, as often happens in Plain nodes), it is suggested that you first press the WYSIWYG "maximise" button (the icon with the 4 arrows pointing to its 4 corners). This has the effect of keeping all the WYSIWYG editor buttons at the top of the screen while you can scroll up and down the box's content, and perform any required editing. Pressing the maximise button again will return you to the full Edit Template - something you will need to do in order to press "Save" in order to preserve the results of your editing actions.

The WYSIWYG editor's "<>Source" icon provides a way of switching between seeing the content of the field as rich text, i.e. as it will appear as a web page, and as structured HTML (structured in the sense that it employs new lines and indenting to clarify the syntax of the HTML text). 

Find and Replace are still available when the “<>Source” icon is set to show HTML, but involve temporarily overwriting the top line of the HTML text with a "command line", and using the "Return" key to cause the command to be executed. The "Find" icon allows any sequence of characters to be specified - the first occurrence of these characters will be highlighted when Return is pressed. The "Replace" icon provides a Replace command line that includes a changeable specification of the last text to be selected (e.g. by use of "Find"). Then when Return is pressed a "With" command line takes the place of the Replace command line, and provides an opportunity to specify the replacement text. When Return is pressed again the command line is replaced by one that states "Replace?" and provides four little button"Yes", "No", "All" and "Stop" which can be used to indicate what is to be done. (This line will disappear, revealing the first line of the HTML text again, when one of these buttons, or indeed anything else, is clicked.) So once again, even when operating at the HTML level, the facilities provided by the Replace icon are an extension of those provided by the Find icon.

The WYSIWYG editor incorporates SCAYT (Spell Check as You Type), a facility that is invoked and controlled using the icon which contains "ABC" above a tick mark. (This icon is positioned just after the "Maximise" icon.) The SCAYT facility can be turned on ("enabled") using the menu that opens when you click on the icon. When SCAYT is enabled, there is a blue line under the icon, and any mis-spelled word will have a wavy red line under it. Right-clicking on such a word brings up a menu that proves some suggested alternative spellings and allows you to decide what should be done about the mis-spelling. Whether or not enabled SCAYT provides a "Check spelling" menu item that provides a means of spell-checking the entire current page, in a separate small window that is opened for the purpose. (This small window has three tabs, one for spell-checking, the others for a thesaurus and a gramar checker.) 

Note: The WYSIWYG editor re-arranges (in effect “standardises”) the format of each field’s HTML when first used on that field. It does this through the use of new lines and tab as formatting characters, and HTML formatting constructs such as “<p>&nbsp;</p>". This does not effect the field's visual appearance in the page, apart from its vertical spacing.  But it can cause searching problems with sets of pages which are a mixture of (i) such standardised HTML pages and (ii) original (perhaps rather idiosyncratic, or poorly structured) newly-imported or newly-created HTML pages. Such standardisation will be applied to all fields of text whose formats have been "enabled for rich-text editing”  by default. (Such enabling is done in the maintainer’s account page (user profile), by ticking the "Filtered html” and "Genuki topic” boxes in the Edit tab. If WYSIWYG is not set as a default, standardisation will be applied to a field’s HTML only when the enclosing page’s edit template is opened and the field's “enable rich text” command is used.) Thus searching problems (unexpected failure to find what is being sought) can occur if the chosen search term involves HTML text whose representation in standardised and un-standardised fields and pages might differ. However searches for single HTML “words”, i.e. strings of alphanumeric characters that do not contain spaces or new line characters, should not be affected. If and when all the pages being searched have previously been opened for WYSIWYG-enabled editing, this problem should not occur.  

See also note Caveats Regarding Use of the Drupal Editor.

WYSIWYG Tables

Extensive facilities are provided in the WYSIWYG Editor for defining and editing tables - see separate page on Creating WYSIWYG Tables.

Checking of links

The procedure for checking for missing and broken links is quite complicated - please see separate page on checking of links. 

Users, Contributors and Maintainers

In contrast to ordinary users (casual visitors to the published pages), contributors have a user name and password to logon to Drupal and gain access to the Contributor facilities and documention, and can be noted as the author of any page they edit. As the "author field" can be changed it is really the term for the (current) contributor of the page's content. GENUKI contributors cannot create new pages - this is facility that is provided to maintainers. We also have another role for some people, of 'GENUKI administrator', with more privileges such as the ability to edit nodes for which they are not noted as the author.

Each contributor has a user account (or "profile"), reachable via the link "My Account" in the top right hand corner of each page. The Edit tab on the user account page allows contributors to perform such tasks as: Change their password, Specify a signature to be used at the foot of each of their pages, and the details of their contact form, etc.

Searching

The Search box in the top right hand corner of each page is a Drupal-provided facility, based on Lucene, that enables all GENUKI users (not just contributors and maintainers) to do case-insensitive searches on the displayed information content – not the HTML encoding - of all the current GENUKI implemantation pages, but not any pages that have yet to be converted from our previous static html format. (Note that only text that is in nodes' edit templates, not text that is dynamically added in, e.g. text from the Church Database inserted into parish pages, will be searched.)

Multiple search terms (complete words or phrases, i.e. groups of words surrounded by double quotes, such as "birth certificate") can be specified; at least one of these terms must have two or more characters.  (The search that is performed is an 'or' search that identifies pages containing any of the specified words or phrases. To do an 'and' search you must specify the AND in upper case. Thus a search specifying: 

    Clovelly AND "Herring Boats"

will only report pages that include both these terms.

It is possible to perform so-called wildcard searches. The single character wildcard search uses the '?' symbol - so to search for 'John' or 'Joan' use the search:

    Jo?n

To perform a multiple (zero or more) character wildcard search use the '*' symbol - thus the search: 

   Church*

will find 'Church', 'Churches', 'Churchyard', etc. (Both '?' and '*' can be used within a term, but cannot be used as the first character of a search, or within a phrase.)

The use of '-' before a term excludes pages that contain the term. Thus to search for pages that contain "Clovelly" but not the word "Sydney" or the phrase "Western Australia" use the query:

    Clovelly -Sydney -"Western Australia"

The resulting page of Search results includes a left hand column, the county filter, that shows the GENUKI sections, i.e. countries or counties, in which the obtained results have been found, and the numbers of such results.  This column can be used to restrict the displayed results to those from particular counties or counties. Once a given country or county has been selected as a filter,  further searches performed using the search box in the Search results page will be restricted to the selected country or county until the filter is disabled, which is done by clicking on the appropriate "(-)". 

The above outlines only some of the facilities that are provided by the Search box - more details can be found in the (rather opaque) Lucene query language documentation.

GENUKI Topic Pages

A third node type, that of  of 'GENUKI Topic', has been defined where you can put in a single topic, for a single place. There are fields to record the Place code, the topic type, and optionally the topic source. In the Pane that displays the Place node, there is a view which searches for this additional information, and automatically displays it as part of the Place page alongside anything under that topic that may already be part of the Place node. (The facilities for creating this type of node have yet to be made generally available.)

By this means we can have people supplying and maintaining additional information that is automatically integrated as part of the Place Pages. Additionally we could also combine it in different ways. So if we did it for a gazetteer, we could see the appropriate section on the Place Page, but also have a page that showed all the places in a county, just as it would appear in the original gazetteer.

Reports, Errors & Statistics

Via your Accounts page (reached via a link in the top right hand corner of any of the nodes that you are authorised to edit), you can find a listing of sections containing these nodes, and a listing of the numbers of errors, such as broken links, redirections, etc., that have been detected in these nodes. Clicking on these numbers will allow you to get to  all these nodes.

These error listings are in fact part of the regularly updated listing that is provided for the entirety of GENUKI, organised by section (county), of the numbers of nodes, broken links, redirections, etc.

Also available to you are the Monthly Archive, which provides the headers of, and access to, each page in a section that has been newly-added, and a Monthly Changes report, that lists all the pages in the section that had been changed, during the month. 

Miscellaneous minor issues

There is a problem with logging in using Safari on the Mac. When you move to another page after logging in, the page you reach sometimes shows you as logged out. The workaround is simple. When this happens, get your browser to refresh the page - you should then be shown as logged in.

It is not currently possible to create a link in one WYSIWYG field to an anchor defined in another WYSIWYG field, e.g. between a left or right contents list and the body of a Plain page. The workaround is to edit the source html. And Drupal doesn't like numerical anchors - a problem easily avoided by adding "Anchor" or even just "A" to each such anchor - and of course to any links to it.

Due to sloppy HTML the link text of an external link sometimes is not shown in blue and underlined (because it is missing the quotes round it), though the link is marked with a little box and up arrow, and does work. However if you open an Edit window on the page with this problem the WYSIWYG view of the page shows the link text complete with blue colouring and underlining. An effective and simple work-around for this problem is then to select this text and press the little link button (in the line of editing buttons), so that a window opens showing the Link Info. This information is correct, and by simply pressing OK, and then Save to return to the problem page, it will be found that the link text is now showing properly.

The "Revisions" tab does not appear on Place or Parish pages until the page has been revised (when the tab provides means of reverting to an earlier version, or of comparing two versions). And in fact it seems that bulk editing operations do not cause revised versions of the affected pages to be created, or for the "Revisions" tab to appear.

After updating a page, and logging out, one might find that the page shows initially as unchanged, even if the changed page had been visible before logging out. The delay before the changed page becomes visible to ordinary users has been known to be as short as a minute, or as long as an hour.

URLs ending in slash ("/") get reported as an error both by  the Spider and in the Drupal  "Statistics & Errors" report. However things work with or without them, so at present such error reports can be ignored.