News, Announcements and Other similar items

These items don't need to be created as separate pages, or even as part of existing pages, and may not need any HTML usage at all, or even assigning a page reference (URL). Using the Drupal Story concept will automatically ensure that each such item will appear as a separate item in the RSS feed. It is assumed that none of these items need to appear in the navigation menu.

In the Administer page go to Create content->Story (or use http://www.britgo.org/node/add/story [1]) and then:

• Title

  should include the word Tournament or Teaching Event if it is one (this duplicates the News type, but it appears in the RSS feed item)

• News Type

  Always select the correct one (as this means that you can see all items of the same type together)

• Tournament Date

  This and the following three fields should not be used except for Tournament Reports and perhaps Diary entries. The To Date should only be entered for a tournament/event over multiple days

• Tournament Type

  Can be ignored

• Venue

  Could be omitted, but it's desirable to have at least the town and postcode

• Body

  Assumes the Input format defaults to Markdown (if not then change it):

  • Diary Entries should be entered as (mmm is Month and YY year)
    [Diary Entry added or updated](/tournament/index.html#mmmYY)
  • Tournament results should be entered as
    [Results added](/results/year/name.html)
  • Other Site Updates should be entered as
    [xxxx added](/page.html)
  • Any text can be used for all other News Types, with an internal britgo.org link being entered simply as
    [text](/ref)

• All other options should normally be the defaults (URL path settings and Menu settings do not need to be used except in exceptional circumstances).
• In the event of doubt the Publishing options should be

  Promote to Front Page (creates an RSS entry)

• ALWAYS PREVIEW BEFORE SUBMITTING
• When you're happy with what it looks like then press SUBMIT

That's it

• There's no need to create a URL reference, unless this needs to be referred to from a menu, as Drupal handles all the internal references.
• The list of new news items is generated automatically.
• If you need to create another kind of link to this item then you can use /node/NNNN as the reference, rather than having to use a .html one.

New Pages

If you're adding a new (static) page to the site, which should happen infrequently now that the vast majority of the site is set up, then you need to consider whether the page should appear in the RSS feed. In general, we wouldn't expect such pages to be in the feed, but if it's a totally new aspect of information then it might be. If so, then look at the News, Announcements section.

Otherwise in the Administer page go to Create content->Page (or use the URL http://www.britgo.org/node/add/page [2]) and then:

• Title
  If a colon (:) is used in the Title, then any changes won't appear in the Site Updates lists
• News Type
  Probably irrelevant
• Menu settings
  link into appropriate place in the menu hierarchy
• URL path settings
  Only need to be used when this page is to be linked to explicitly from another page. This may not be necessary if it is only used by clicking on the left hand side menu (see below). In any event you could use /node/NNNN as the reference, rather than having to set up a specific path (with possible clashes).
  Section 6 provides some guidelines for creating an appropriate URL.
• Menu settings
  Link into appropriate parent in the menu hierarchy (not to a disabled item)
  Note: you may need to change the weight in order for this item to appear in the correct order in the children of this parent. Drupal normally order things in alphabetic order otherwise. You must supply a title that will appear in the menu hierarchy (typically an abbreviation of the page title)

Creating a new URL

The following was written before the usage of URLs (URIs) was much reduced through the use of Drupal's Books, Stories and navigation systems.

The URLs of particular pages are part of the user interface of this web site and should be chosen carefully, if they are needed. Although many users will never manually type a URL, they may see them in the address bar of their web browser, they may copy and paste them into emails to friends, and they may see them in print in articles, for example in the Journal.

URLs should never change. Once a page has been published, it may get bookmarked, linked to from other sites, indexed by search engines, and so on. This means that it is important to get the URL right first time. If in any doubt, please consult with someone else (the webmaster?) for guidance. Having said that, if absolutely necessary, a page can be moved to a different URL, and things can be done to ensure that people trying to visit the old URL get redirected.

Since getting URLs right first time is quite important, the webmaster considered a policy that you must ask every time before creating a new page. However, this was rejected this as unnecessarily draconian. You may still want to ask the webmaster anyway, since he may need to work out where any new page should fit into the site structure, where it should be linked from; and the indexer will need to be informed of the new page's existence. It is not that the webmaster thinks you are likely to make mistakes (at least no more likely than he is), but that correcting a mistake later is painful, and the more pairs of eyes that look at what is proposed before it is set in stone, the more chance there is of any mistakes coming to light when they can be fixed painlessly.

When choosing the URL for a new page, please consider:

• People looking at the URL should have a reasonable idea what it points to.
• URLs should be as short as possible (URLs longer than one line of a plain text email—about 72 characters—are particularly bad).
• Only lower-case letters should be used in URLs. Upper-case letters are perfectly valid, but unusual, and users should not have to think about upper/lower case when they are entering a URL, so keep it all lower-case.
• Similarly, avoid all punctuation other than ‘/’ and ‘.’.
• When running two words together (don’t, unless you have to) be careful. ‘danpromotion’ is OK. Something like ‘fortypee’ would be ambiguous (forty pee, for type e, OK, you could probably make up a better example yourself), and should be avoided.

• The URL should describe the contents of the page identified, and not the technology used to produce it. So avoid URLs like:

  • ‘/cgi-big/…’
  • ‘/tournaments/index.html’ (Keep the file as /tournaments/index.html on the server, but always refer to it as plain ‘/tournaments/’ in URLs)
  • ‘pagename.php’, ‘pagename.shtml’, and so on—the user is not interested in how the page they are viewing was generated. (Even ‘.html’ is arguably bad, however, HTML is the format of the information in the page, not how it was produced, so may convey some useful information. For example you could have pages ‘fred.txt’, ‘fred.html’, ‘fred.pdf’ which present the same information in different formats. And in URLs like ‘image.png’ and ‘image.jpeg’ the information about file format certainly is useful.)

• Particular extensions:

  • Use ‘.html’, not ‘.htm’
  • Use ‘.jpg’, not ‘.jpeg’

  The webmaster has now modified the setup so the rules about particular extensions are enforced. That is, if you attempt to go to the page something.htm, it will immediately redirect you to something.html.

Note: Drupal does not require that you include an extension, and arguably it's better if we don't use them in future. However, any reference to another page on the site must match exactly the URL that is allocated for the item in question. That is, if an extension is used when the item is created then is must be quoted in the reference. If not, then not.

All existing pages have their URL recorded on the system with and without .html for ease of access and to preserve existing links. There are additional short-cut URLs that don't have the .html.

Generally the one held on the page is the one without the .html, with the one with the .html declared as an additional alias against the node.

News stories do not have meaningful URLs recorded against them.

Hyperlinks

Linking between pages

The specification (RFC 1808 [3]) is not exactly readable. However, for now you will just have to work from the following examples:

• To link from anywhere to the home page, use
  href="/".
• To link from a page like http://www.britgo.org/tournaments/publicity.html to http://www.britgo.org/tournaments/ use
  href=".".
• To link from a page like http://www.britgo.org/tournaments/2003/mk.html or http://www.britgo.org/tournaments/2003/ to http://www.britgo.org/tournaments/, use
  href="..".
• To link from a page like http://www.britgo.org/tournaments/ to http://www.britgo.org/tournaments/publicity.html, use
  href="publicity.html"
• To link from one part of the site to another, for example, to link from anywhere which is not in the results area, to the results or a particular tournament, use something like
  href="/results/2003/mk.html"
  (that is, start with a slash to get you to the top level, and work from there).
• To link within one part of the site, for example, to link from http://www.britgo.org/results/2003/mk.html to http://www.britgo.org/results/2002/mk.html, use
  href="../2002/mk.html"
  (that is, work up as few levels as necessary using .., then work down again).

Named anchors within pages

These are used sometimes to be able to reference to a section of a page. That is, having <a name="fred"> in one place, and <a href="#fred"> or <a href="pagename.html#fred"> in another. The <a name="fred"> should go inside any block-level element, and just surround the text. That is should look like this:
<h2><a name="britc">British Championship</a></h2> Not like this:
<a name="britc"><h2>British Championship</h2></a> In theory, it should be possible to do:
<h2 id="britc">British Championship</h2> But this sometimes fails to work in Netscape 4.X. Since there is a not much more complicated method that does work, please use the
<a name="britc"> form. Note that the rules for forming names [4] are:

name tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").

However, the recommendation is to stick to letters and digits. The punctuation characters cause problems. (Underscores are a problem in CSS, the others in JavaScript. If you absolutely must use one, use a hyphen.)

Link Text

When putting a link on the page, you should make the text of the link (that is, the words in the sentence that the user must click on to follow the link) meaningful. The classic bad example is:


To find out more about the BGA, click here [5].

‘Click here’ gives absolutely no clue about where this link goes, which makes skim-reading the page to find a particular link much harder. That is bad. It gets worse: for a blind or partially sighted using a screen-reader to access the site, this sort of thing makes the site almost unusable. Then, to add insult to injury, the sentence uses the word ‘click’. That assumes that the reader is using a computer with a mouse, which is not universally true. Where possible, avoid assumptions like that. If you must instruct the user, tell them to ‘follow’ the link, or ‘go to’ the page that the link points to (or synonyms). They will know the appropriate procedure for following links with their set-up. Now for some good examples:


There is another page giving the results of British go tournaments [6].

Based on the [7] of 5th May 2004.

The ratings FAQ [8] explains this table, and how to use the information it contains.

[The BGA] also has a selection of promotional material [9] for use by Go clubs and at publicity events.

If you plan to take children to a Go tournament, you should read the BGA policy on working with children and young people [10].

Writing sentences so that there is a sequence of words that can naturally be used as the text of the required link is something of an art. It is not always easy, although it does get easier with practice. Sometimes you have to be prepared to completely reorder the sentence to make it happen. If you are stuck, it often helps to ask another person. I am always happy to be asked about this sort of thing.

Punctuation and links

The rule here is that almost all punctuation goes outside the link. If the link is at the end of the sentence, or before a comma, the full stop, exclamation mark, comma, or whatever, goes outside the link. This applies even if the link forms an entire sentence. If a link is in brackets, then the brackets go outside the link. However, it only a part of link text is bracketed, those brackets go inside the link.

Worked examples

Example A

For example, Simon Goss asked my about three examples from the policies page [11].

Not so good: (Simon’s comment: Naff repetition.)

3. Working with Children & Young People

See BGA Policy on Working with Children and Young People [10].

Better: (The sentence now at least conveys some other information, the fact that a policy exits as a separate document, as well a repeating the title. That seems unavoidable, since the policy has a good clear name that describes exactly what it is.)

3. Working with Children & Young People

The BGA has a separate Policy on Working with Children and Young People [10].

Example B

Not so good: (Simon’s comment: Ungrammatical construction.)

The BGA provides facilities for distributing tournament entry forms with the newsletter and hosting them on the BGA web site. These facilities and many other recommendations are described in Publicising Go Tournaments [12].

Better: (Nothing wrong with putting the link at the start of the sentence.)

The BGA provides facilities for distributing tournament entry forms with the newsletter and hosting them on the BGA web site. The page Publicising Go Tournaments [12] explains how this works, alongside other recommendations for tournament organisers.

Example C

Not so good: (Simon’s comment: Stilted workaround to avoid ungrammatical constructions.)

The official version of the rules for the British Go Championship, the British Pair Go Championship and the British Youth Championships is the BGA Championships Rules [13] page.

Better:

The BGA Championships Rules [13] page contains the official rules for the British Go Championship, the British Pair Go Championship and the British Youth Championships.

Checking Links

Web sites have an unfortunate habit of changing, which means that links to other people’s web sites that used to work fine have a habit of breaking. Therefore, you should check all the links on the pages you are responsible for periodically.

It would be very boring if you had to go and manually click on all the links yourself. Fortunately, you don’t have to. There are any number of computer programs to automate the process.

The webmaster normally uses the W3C link checker [14]. Go there, type in the URL of the page you want checked, and click on the ‘Check’ button. It is a very thorough checker, so if it finds no problems on your page, you can be happy. However, if it does find some problems, you will discover that it has a bit of an attitude problem! Its error messages are fairly forthright, some might even say rude.

However, if using the checker as above is too much trouble, you can make the process simpler. In your web browser, create a bookmark/favourite called something like ‘Check links’, and with location/address/URL:

javascript:(function(){location.href="http://validator.w3.org/checklink?uri="+escape(location.href)+"&hide_type=all&depth=&check=Check"; return 0;})()

(Don’t worry, you don’t need to understand that. Just copy and paste it into the location/address/URL field of the bookmark). It can be quite difficult to create a bookmark from scratch. The secret is to bookmark a random page, then find that bookmark, open it's properties dialog box, and then edit the various bits.

Once you have set that up, go to any web page you like, then open that bookmark, and you should find that it checks the links of the page you were just looking at. Magic! The webmaster finds this so convenient that he keeps it on his personal toolbar.

Book and Hardware/Software Reviews

These can be added as either Story's or normal Pages (depending on whether or not you want them to appear in the RSS feed), but with the News type of Book Review or Software Review.

In order to ensure they appear in the correct order in the Reviews list you need to enter the date or the review into the Sort field in the form: ccyy-mm.

The start of the review should be in the following format (assuming Markdown input), to ensure consistency and that the correct BGJ is shown in the Review list (note that there is a blank line between the date/picture and the reviewer):

<i>BGJ 154 Winter 2010</i>
<img src="/files/review_winninggo.jpg" class="floatright" width=300>

<i>Reviewer: Glynn Forsythe</i>

In addition a reference should be added to the relevant page about that issue of the BGJ, i.e. /bgj/bgjNNN.html, in the form:

<li>Book Review: <a href="URL (node/NNNN)">TITLE</a></li>

Tournament Results

Tournament results are normally added as new pages with a type of UK Tournament Results or Foreign Tournament Results as appropriate. There will often also be a separate news Story with type of UK Tournament Report or Foreign Tournament Report.

The generation of the results cross-table is an automated process invoked by this page [15].

This will take an email address and a file on your machine, which should be the web file output from the godraw program, e.g. EastMidlands_11.web, convert it and mail back to the email address an email whose body is the converted file.

The page should be created with an appropriate title such as "East Midlands Tournament Results". As well as the type field, enter the Tournament Name field and the Tournament Date in the fomat shown. If it lasts more than one day also enter the End Date.

Paste in the portion of the converted file from the email from below the skeleton date line to the end of the table. You can also add extra paragraphs of information about the event such as location, handicap system used or associated events.

If the event has many rounds you can narrow the width of the Country column by changing its title to "Cy" in order to reduce the width of the table.

Set the url of the page to be eg /results/2011/eastmidlands and later add an additional alias of /results/2011/eastmidlands.html using the Add alias form.

Add the new page to the results index for the year eg /results/2011 (access e.g. via Tournament Results tab, Results for other years, Old format: 2011). The link should be e.g. /results/2011/eastmidlands.html and is normally already there, commented out at the top of the page to allow easy cut and paste, for events that happened the previous year. This list should contain all UK and Ireland events where the results are available.

The winner should be recorded in the Hall of Fame pages: add to the tournament's entry on /hof/past and move the title from the existing holder to the new one in /hof/current (noting entries are sorted by number of titles held).

If it is British Championship event then the /bchamp section will also need updating and possibly also the points tables in the /reps section.

If a youth event or young players have taken part, then the Junior Section may need updating - for a news item, the list of winners, or the Youth Grand Prix Points. Ensure the Junior Section editor is informed.

Documents

When adding a new document that mainly intended to be browsed online, such as this one, the recommended format is as a Book. The BGA Policies is another such an example. Drupal generates a table of contents, browsing within the various pages (back, forward, up and down) and also has a user option to produce a printer-friendly version of the whole document, omitting all the website header/footer etc.

In the Administer page go to Create content->Book Page and then create a page for each section:

• Title
  It's recommended, but not essential to include a section number (if any) followed by period. (See Weight below)
• Parent
  All pages except the first page have the first page as their parent (first page = )
• News type is probably irrelevant
• Body
  If you need a sub-section heading then encase it in <h2>...</h2>
• Weight
  Probably not needed to be used if you use section numbers and there are less than 10 sections as Drupal will automatically sort the other sections into the correct order and create a menu of subsequent pages on the first one.
  In other conditions use a number between -15 and 15 to sort pages into the order you want (lower numbers are first).
  Note: it may be easier to get it into the correct order by going to the Administer Page->Books and editing the outline screen after all the sections have been entered.
• Menu settings
  For first page only link into appropriate place in the menu hierarchy if appropriate (not to a disabled item)
• URL path settings
  Only need to be used when this page is to be linked to explicitly from another page. This is probably necessary only for the first page. In any event you could use /node/NNNN as the reference, rather than having to set up a specific path.
• Publishing options
  Promoted to front page should be OFF, except for the First Page WHEN you're happy that the whole document is correct and notification of it is to be published via RSS notification.

Our Drupal system is configured so that the Book Navigation Block appears to the right of every book page. It is recommended that when you create the first page of a Book that you configure this block to exclude the first page of the book, as otherwise this will duplicate the automatically generated table of contents at the bottom of the page.

Note: There is a list of all created Books available from the Administration System.

Uploading Files

Files that are only likely to be referenced from a single page can be added at the same time as you enter the page or news item. You do this by using the File Attachment option and selecting the local file for uploading. However, please note that all these images will be loaded into the /file directory, so if the local file name is already in use then Drupal will automatically load the file using a slightly different name. You can reference the image using
<a img src="/files/xxx.extension ...
(see more in section 5) or a document using
<a href="/files/xxx.extension>document name or title</a>

Files that are likely to be used more widely, or that should be part of a more organised folder structure, e.g. the British Go Journal, can be uploaded by FTP. Contact the webmaster for help and advice on this.

In general files should be uploaded in a neutral format and proprietary formats should be avoided. It's also desirable that formats that prevent the inclusion of viruses should also be avoided - this means that we don't recommend the use of Microsoft Office formats (no matter what software produces them).

• For photos and other images the recommended format is JPEG - extension jpg
• For documents in a printable format this is Adobe's PDF - extension pdf
• For editable documents the main suggestion is Rich Text Format - extension rtf, but other formats are also acceptable since this format doesn't necessarily support the desired content/format

The system holds a list of valid file extensions and the maximum file size for upload; these can be changed if need be (the last changeable for each user).

But, in any event if this sounds too prescriptive, remember that our mantra is Content is King, so upload the content even if you break these rules.

Adding Images

Photographs can be used to liven up pages where what they add to the page outweighs the extra download time.

People

Photographs in which individuals are identifiable should only be added to the site after the people pictured have been asked whether this is OK.

We will not normally add identifiable photographs of people under the age of 18 to this site.

File size

Pictures inline in a page should be quite small thumbnails, a reasonable limit would be 10kB for images that are mainly decorative, but often you will be able to get them under 5kB. For pictures that convey significant information, more is fine. They say a picture is worth a thousand words. A thousand words of text in HTML format will average about 7kB!

If it is necessary to show a large image, consider putting a small thumbnail inline, which links to the large image. The British Go Association Picture Gallery [16] is a good example of this.

File format

Photographs, and similar images, should be in JPEG format, with a ‘.jpg’ file extension.

Diagrams, with large areas of solid colour and sharp outlines, should be in PNG format, with a ‘.png’ extension. However, if you can't avoid it, use GIF format.

File names and places

The name of the file should be the surname followed by the first initial (that he/she's known by) and the extension in lower case, e.g. hitchensb.jpg. Thumbnails are probably not needed anymore: Where you have both a high-resolution image, and a corresponding thumbnail image, then the thumbnail image should have the same name as the full-sized image, with ‘-t’ added at the end of the name and before the file extension. For example ‘th.jpg’ and ‘th-t.jpg’ in the picture gallery.

In general pictures of people should be added to the directory /files/people and then referenced from there, as in done of the People involved in running the BGA [17] page. To get a picture added to the gallery, ask the webmaster.

Pictures that go only with a particular page can be added to that page as a file attachment in which case they will be loaded into the /files directory. Only to be used in exceptional circumstances now.

If there are a lot of pictures with the same theme, for instance photos of a particular tournament, then a gallery can be created and the photos added to that with appropriate captions. For instance, see a WMSG gallery [18].

Alternatively photographs that were intimately related to a particular part of the site can be put in a relevant subdirectory within /files using FTP. For example /files/people on the BGA People [17] page.

alt and title text

If you look at the specification for adding images to HTML [19], you will see that all images should have some ‘alt text’. This is text that can be displayed if the image is not used. This might happen for several reasons: the person reading the page may be blind or partially sighted; they may be using a browser that cannot display images; or the may have chosen not to display them. Therefore, the alt text should be an alternative to the image. It should convey the same information. A good rule of thumb is this: imagine that you are dictating the web page to someone else over the telephone. What mention, if any, would you make of the image. That would probably be suitable alt text. For mainly decorative images, you might not think them worth mentioning. In that case, you should specify
alt="". You should also specify the size of the image in the HTML, so the template HTML for an image is:
<img src="..." width="..." height="..." alt="..."> You should also specify some text that is displayed as a tool-tip when the user mouses-over the image. The correct way to do this is to specify a
title="[some more information about the image]"
attribute on the image. Some people abuse the alt="" attribute for this purpose. This is a serious sin. Do not copy it. It does not work in all web browsers anyway.

Image positioning

Unless you take special precautions all images will be displayed inline with the text, i.e. left aligned as if it were a separate paragraph. The most common alternative for positioning is to make it appear to the right of some text. To do so use the following CSS reference that we've set up for you as part of the <img reference:
class="floatright" Another alternative is to use a table if you have a series of images that need to be displayed vertically in a separate column. See Pictures [16] for an example of this.

Tournament Entry Forms

We don't have a standard entry form available, but you can create your own using this one as a template and cloning it: British Open [20]

Clicking on the Submit button at the bottom will send an email to the address in value in the <input type="hidden" name="recipient" value="?@?.uk" /> line.

You must also change the URL on the <input type="hidden" name="return_link_url" value="/britishopen/form.html" /> line.

You will undoubtedly need to make other changes and don't forget to test it before announcing it publicly!