pages combined for online review and printing
for normal pages click home

The OnePoyle website drivers are designed for organisations wishing to maintain their own websites with minimal effort. The system features simple user support of content whilst delivering high-quality web pages with automatic menu maintenance. Support staff need have no more than basic PC skills.

Out of date web pages are of little use. The key design objective behind the OnePoyle website system has been to make it easy to keep a web site up-to-date.

Implementation is straightforward. The system can readily be applied to enhance existing websites or to launch new ones.

Implementation of a website may involve a new domain name, and if so, corresponding email addresses are available.

The system results from more than 15 years of operational experience and peer challenge. The two website drivers (main for normal pages; text for the visually disabled) and other supporting CGI scripts are free software. You can redistribute and/or modify them under the terms of the GNU General Public License [www.gnu.org/licenses/] as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Reference sites [new windows]

• surrey festival choir [https://surreyfestivalchoir.org/main.pl] dynamic website using all the options and main development environment
• community photographic website [www.u3aguildfordphoto.org.uk/main.pl?home]

Photos at the foot of these pages are from our photo gallery.

For more information please call Mike Hall on +44 (0) 1483 304234
or email mike.hall

pages/home.txt updated 08:34 Jan 19 2013

  scroll to top   home

Content management

Those involved in website maintenance (content management) need to read the introduction. For further background it may be useful to read how it fits together. The content section is the complete documentation about automatic formats for reference when necessary. The help section includes additional resources, for example on testing.

Implementors

Website implementors need to refer to most of the background and all the implementation section. You will also need to be familiar with content management.

The implementation section of the documentation is to be completed.

Decision makers

Those deciding which technology to deploy need to consult the background, features and the skills needed by content management staff and implementors. The introduction will help you to assess how easy it will be to maintain the website.

pages/summary.txt updated 08:29 Dec 24 2010

  scroll to top   home

image slideshow

During 2009 we introduced considerable enhancements to image handling, including a powerful slideshow. The photos shown on these pages are one result.

This development is relevant to audio and video display.

Google Translate

Machine translation has generally been poor. Google Translate uses a different approach and the results are much better. This technology was integrated into the drivers early in 2010 and is available as an option.

More background [new windows]

• Wikipedia
• Google translate support
• Google Translate for your own text

We will shortly optimise translations on this website, mainly a matter of protecting people's names.

pages/new.txt updated 08:29 Dec 24 2010

  scroll to top   home

All the applications are server-side PERL CGI scripts, dynamically generating high quality html pages when a web page is requested. They have been developed and enhanced over two decades and the resulting websites have been the subject of client and peer review as well as formal usability evaluation.

The overall objective has been to create an environment which allows staff with a minimum of technical knowledge to maintain a professional quality website and to configure and deploy the other applications. Website maintenance responsibility can if desired be shared between a number of staff, for example website content can be independently managed by a number of people whilst being certain that overall 'look and feel' remains consistent. These capabilities are targeted at making it easy to keep a website fully up-to-date.

Every website using these applications uses exactly the same CGI scripts (no variations whatsoever), thus upgrading is a simple matter of replacing the old scripts with the newer ones. Content, including menus, is entirely controlled by text files in a simple format. Website style is managed partly by the applications as determined by the text files, together with css style sheets. Since web pages are created dynamically, when any of the text files changes, content (and if relevant menus and layout) of the website is immediately changed.

All applications and text files are in UTF-8 format, which is becoming the standard Internet character encoding.

Main website drivers

From the same single set of content, menu and configuration text files, these three drivers deliver the appropriate website pages. This is a major maintenance advantage.

• main.pl Normal website driver. Functionality includes a full diary, an interactive repertoire and most recently an image gallery. Printing of web pages is particularly well handled. The site map, views of multiple or all pages and administrative page are generated automatically. Thus, the site map and the multiple page views are always consistent with the menu and no maintenance is needed.
• text.pl Driver for disability users conforming to EU guidelines

Supporting applications (most are password protected)

• [application_unavailable_to_unauthorised_browsers] Used for online updating of all files controlling website content and layout. Includes diary, database and gallery image uploads
• q.pl Flexible questionnaire driver. Questionnaires are set up with a single text file plus a few configuration settings
• qa.pl Questionnaire analysis application, including user-defined reports and a tabular interface for additional external spreadsheet analysis
• logan.pl Log file analysis, generally run offline (very resource intensive because of the large amounts of data in log files)

Database applications (password protected)

• email.pl Generation of selected email lists from an online members/contacts database. Selection is defined by role, which can include eg voice (SATB), contact database category or committee role. Selection by date (membership date or date to contact database) will be available shortly.
• list2email.pl Generation of email lists from a name list, including the option to generate emails of persons not on the list
• inf.pl Enquiry system to search an online members/contacts database

Conferencing

A suite of applications developed for a client for multi-language conference invoices for delegates and a multi-language online conference parallel session booking system that delegates themselves use.

The applications are written generically like the others, but might need some adjustments for other clients.

pages/servers.txt updated 08:35 Jan 19 2013

  scroll to top   home

main design aims

• easy maintenance with basic PC skills
• conforms to EU accessibility legislation
• website update direct from browser
• automatic print formatting
• independent content, menus and structure
• automatic site map
• automatic documentation features (eg web pages combined for review and print)

easy maintenance

• content, menus and configuration settings in text files
• pages added or removed in seconds
• boiler-plate text ensures consistency, simplifies maintenance
• all content can be managed from a web browser

additional features

• self-documenting document download page
• Google site search (public files)
• key words enhance search engine hits
• interactive image gallery and slideshow
• though rarely needed, html can be freely added for extended capability if desired
• optional diary consolidates data from multiple sources, discards past events
• optional interactive repertoire
• optional random selection of images
• questionnaire and questionnaire analysis applications
• log file analysis
  ...and much more

pages/features.txt updated 08:35 Jan 19 2013

  scroll to top   home

The upper part of the diagram shows web page delivery; the lower part shows content preparation. With the availability of the Update Utility, website content is usually updated online with any standard browser (Firefox, Internet Explorer...).

Content preparation

Content files defining menus and page content are edited directly on screen with a web browser using the Update Utility. Alternatively, files can be edited or created offline using any suitable text editor and then uploaded to the server.

Web page delivery

The user requests a particular web page from his browser, for example www.[domain]/main.pl?home, the home page. This request is routed to the website driver (main.pl PERL code). The driver interprets the request, gathers information from the uploaded files about the menus and the home page, assembles the web page and sends it out. The browser receives a stream of high quality HTML and displays it.

The web page does not exist on the server, but is built dynamically.

When a new page is added to the menu file, it is immediately available and the next time a page is loaded the additional page is visible.

pages/fit.txt updated 08:29 Dec 24 2010

  scroll to top   home

Content management covers the text format files controlling pages, menus, quotes, the diary (optional) and the configuration.

Skills needed for content management include:

• basic computer skills, including word-processing experience
• familiarity with the Internet
• good attention to detail
• ability to proof-read

pages/u_tasks.txt updated 08:29 Dec 24 2010

  scroll to top   home

In liaison with the client, implementors are responsible for:

• installing the PERL website driver application (no changes required)
• designing the website 'look and feel', including creating and installing style sheets, configuration files and images
• designing and implementing the initial menu structure and initial web pages

Skills required by implementors include:

• an understanding of how the introduction of the website is likely to affect the business and an ability to give advice and help to anticipate and prevent disruption
• advanced computing skills, including an understanding of server-side websites
• website design experience, including CSS (cascading style sheets)
• ability to configure connections to new email mailboxes
• training experience (to train content management staff)
• familiarity with an image editor (eg Photoshop)

PERL skills are not needed

pages/i_tasks.txt updated 08:29 Dec 24 2010

  scroll to top   home

The software uses session cookies to temporarily record which pages you have visited. The information is used to improve navigation and for internal security. These cookies are not used for tracking, and are deleted when the browser is closed. Please note that if your browser is set to restore windows when it reopens, it may also restore session cookies.

Cookies in use

Name	Value	Type
server	name of most recent website server	session
serverarea	location of most recent website server	session
query	name of last page visited with the main.pl website server	session
text (if used)	name of last page visited with the text.pl website server	session
driver (if used)	name of most recent website application	session
area (if used)	location of most recent website application	session
translate	whether Google translation is selected	session

pages/cookies.txt updated 09:23 Dec 14 2012

  scroll to top   home

The Update Utility allows authorised persons to manage website content directly from a web browser. You can make changes from minor spelling corrections to complete new pages and to the look-and-feel (configuration) of the website.

Because of its advantages for this task, where a page is first prepared by a word processor, the use of Libre Office Writer is both recommended and assumed. Other word processors, eg Microsoft Word, have not been tested and are not supported, though they might work.

pages/update.txt updated 12:53 Aug 18 2011

  scroll to top   home

Instructions for anything new on the computer often look daunting, but in practice you are likely to find the Update Utility very easy to use.

Click on website update. Enter your user name and password and click update menu, taking you to the Update Utility menu screen. (The first time you use one of the online applications, you will be prompted for a new password.)

Type a filename eg home into the edit existing page and click web page content

In the next screen, you can inspect the page content and edit it as you wish. Then click install

The final screen confirms that the page has been stored. Click the review '[page]' (test file) button to open a new window to review the web page.

Not satisfied with the result? See re-editing a page

pages/update_start.txt updated 08:29 Dec 24 2010

  scroll to top   home

Here's the easy way to make several minor changes to a page:

• click review '[page]' on the confirmation screen to display the page in a new window
• decide what further editing is needed
• select the confirmation screen window, click main menu and then web page content
  [depending on your browser, clicking back from the confirmation screen window may not include your latest edits]
• the resulting screen has the web page data as you left it after your previous edit
• make further edits and click update web page content
• select the review window and click refresh on the toolbar
• repeat as often as necessary

pages/update_amend.txt updated 08:29 Dec 24 2010

  scroll to top   home

Click on website update. Enter user/pw and click update menu, taking you to the main Update Utility menu screen. The screen is divided into several simple forms, one for each type of update for which you are personally authorised.

For safe testing, not affecting the live site, check the test box

Start of for example by typing a filename eg home into the edit existing page and click web page content

In the next screen, you can inspect the page content and edit it as you wish. Then click install

The final screen confirms that the page has been stored. Click the review '[page]' button to open a new window to review the web page.

Not satisfied with the result? See re-editing a page

making the test page into a live page

When satisfied with the test page, select the destination and click install test file...

If you wish, delete all your test files with the delete [user] test files button on the main screen

caution You are changing the live site, so check, double check and triple check your destination selections. If you use the wrong file name, an existing page will be overwritten.

pages/update_test.txt updated 08:29 Dec 24 2010

  scroll to top   home

Web page names

Text typed into the page name box must correspond to the physical filename. This is often the page title, but before updating a page check the filename, which is found in the address bar following the ? for the page you wish to update. Alternatively, view the file public_menu for the corresponding area of the site.

Once you have edited content, click install, then review the page in a separate window (use the link in the Update Utility confirmation screen). If further editing is needed, click back once from the confirmation screen to restore the update screen and make further edits, then repeat the process.

Installing test pages

Pages given a test name are saved in the administration area, filename starting with _test_. If you subsequently wish to install a test page, open it (edit existing) with its filename, amend the content if necessary and install it in the normal way.

A test page _test_page_ can be opened for experimentation. You cannot save a page with this name.

Special files

• public_menu main menu (on left)
• public_sub quick menu (top and bottom)
• public_quotes boiler plate text, included in web pages with [quote '[reference]' not found]
• public_credits credits for image files

Inspect these files the same way you inspect web pages and with the right authority, you can update them.

pages/update_hints.txt updated 08:29 Dec 24 2010

  scroll to top   home

The first time you amend a web page, it's better to use safe testing

web page changes - live

• use the web page content form; do not check the test box
• to amend a live public page, check main site (details may vary), enter a filename, eg home in existing page and then click web page content
• to find a filename either inspect the menu file public_menu or use the name following the ? in the address bar on the website
• make changes in the resulting screen, save and inspect the result
• if not satisfied with the result, see re-editing a page

caution You are changing the live site, so check, double check and triple check your entries at each step. For example, to keep uploaded documents private, make sure you have checked the adminstration area button. If another one gets selected, files can be uploaded to the public site. See also danger

document/image upload

• use file upload form
• click the buttons for the settings you want, eg next to document and the adminstration area to upload a file to the password protected area
• browse for and select the file you wish to upload
• enter the destination formatted file name in the with filename box
• click upload and wait until the confirmation messages appear - uploading takes a few minutes on a dial-up line

The destination document filename is important - see self-indexing. You don't need to change the source file names on your PC, just type the required formatted name during upload.

danger

• following a page delete, make sure that the delete button is not still checked
• when starting to edit a different web page, check the correct filename is in the output filename box

If you make a mistake, it is usually easy to recover, except after an erroneous delete. If you make a serious mistake, it may be possible to recover a previous version by clicking 'back' either in the Update Utility window or in the Review window. In the latter case you may have to copy the content and recreate the web page. If you need more help, contact mike.hall@onepoyle.net.

pages/update_live.txt updated 08:29 Dec 24 2010

  scroll to top   home

The first time you amend a web page, it's better to use safe testing

1) Open the Update utility

Click on website update. Enter user/pw and click update menu, taking you to the main Update Utility menu screen. The screen is divided into several simple forms, one for each type of update for which you are personally authorised.

2) Create the new page

There are many ways to create a new page and you can use any of them. An easy way is to start from an existing page, used in this example.

• choose an existing web page with layout similar to the one you wish to create
• use the web page content form
• select the section of the website which has the existing page
• type the page name in the edit existing page box
• click web page content
• type a new page name in the output page filename box
• select the section of the website which is to have the new page (this may differ from the source of the page)
• amend the page content
• click install [Note: If the page already exists, Update will not overwrite it, but will give you an error message. In that case, click 'back' and type a different name.]
• click the review button to display the new page and check that the content is correct
• if not, return to the Update Utility and click back once, edit the page and reinstall

3) Add the page to the menu

• use the web page content form
• select the same section of the website where you created the new page
• type public_menu in the edit existing page box
• click web page content
• decide where in the menu you wish the new page to appear and copy an existing line to the appropriate place
• edit the new line, eg the filename needs to be the name you chose when creating the page
• click install
• check that the menu entry is as you want it and if not edit it in the same way as for the new page

pages/update_add.txt updated 08:29 Dec 24 2010

  scroll to top   home

It is reasonably straightforward to transfer content between an Libre Office text document and a Web page in either direction, however minor editing may be needed to make the converted document acceptable. Ideally keep documents in a single format, eg print a web page rather than create a separate document for those without web access.

If conversion is needed:

From web page to Libre Office Select and copy web page content (exclude menus etc) and paste into a new Libre Office document. Heading levels and links are generally preserved.

From Libre Office to web page Save the document as html and upload with Update. This is a quick way of preparing a new web page without bothering with automatic formatting. Once installed, use the web page as the master, making further amendments with Update. Hard copies can be printed from the web page. For full details, see conversion from Libre Office to a web page

From Libre Office to PDF If the layout of an Libre Office document is important, consider Export as PDF from Libre Office and upload the PDF file. Documents which should not be changed, eg minutes, are also suitable for PDF.

pages/update_create.txt updated 12:55 Aug 18 2011

  scroll to top   home

• prospective users are offered a short (circa 30 min) demonstration/training session
• users must be authorised. Ask your webmaster for a password if you want to use the utility
• the Update Utility shows only your authorised functionality. For additional functions, contact your webmaster

configuration

• the utility is configured with the update_config file
• users are authorised by role in an authorisation file
• functionality is configured by role in the update_users file

pages/update_use.txt updated 08:29 Dec 24 2010

  scroll to top   home

The following fields configure the update utility:

• title [update utility page heading]; default Update Utility,
• description [eg description and link to documentation]; otherwise Update Utility default link
• test on; prints debug values, default off: nolog; turns off writing to log file, default on

• dmembers [members diary directory]; default no members diary update, example
  dmembers ../diary

• mcontent pages
• mdata [members data directory]; default no members data update eg:
  mdata data

• area area 1[#area 2]...; no default, descriptions of website areas for update eg:
  area main site#members#committee
• area[wwww] [area directory]; one entry for each area defined above, where [wwww] is the first four characters of the description eg:
  areamain ../pages
  areamemb ../members/pages
  areacomm pages

pages/update_con.txt updated 08:29 Dec 24 2010

  scroll to top   home

This configuration file controls what update permissions are available to each role

The configuration file is [support]/update_users.txt. It must be present and cannot be moved.

Configuration fields appear on a single line for each role with role name followed by permissions. Roles are defined in an authorisation file.
[role] [permissions]

permission options

all	all possible permissions for the site
html	can update html files [html files are not normally present, so this permission is unusual]
content	can update web page content, excluding menu and quotes files
special	menu and quotes files (content must also be present)
diary	can update diary files
transfer	permission relating to an unimplemented diary function
database	can update database files
documents	can upload images and documents
config	can edit configuration files
delete	in conjunction with other options, allows images, documents, web pages and web page content deletions
reset	user can reset a user password to the initial value
photos	if photos is present, only the upload photos structured screens will be shown
none	if present, the user will have no permissions, whatever else may be set

typical entries

default content documents
[all authorised users get the default permissions in addition to any specific permissions that may also be shown]

webmaster all
[webmaster gets all possible permissions]

admin database special default
[admin gets default permissions plus database and special]

left none
[whatever other permissions are defined, if 'none' appears, no permissions are allowed for this role]

pages/users_update.txt updated 08:29 Dec 24 2010

  scroll to top   home

Content management means being responsible for text format files controlling pages, menus, quotes, configuration and the diary (optional).

This section is the detailed documentation for preparing and maintaining content files.

Start with the introduction, for the basic information you need.

For detailed specifications see:

• pages (automatic formats)
• quotes
• menus
• configuration file
• diary (optional)

For background and help see:

• testing
• filename standards
• how it fits together
• a training outline for content management staff
• the help section

pages/content.txt updated 08:29 Dec 24 2010

  scroll to top   home

This page is the basic documentation for maintaining web page content. Refer to full documentation for additional detail.

The OnePoyle system takes care of web page layout using automatic formatting. Layout is defined once when the site is first created. Individual content pages are 'plugged in' to the predefined format.

Web page content is stored as 'text' files, created initially by almost any word processor (Libre Office recommended). Subsequent editing is done online with the Update Utility.

Here are examples of the main automatic formats:

what you put in the file	what you see on the web
text paragraph made up from several lines	text paragraph made up from several lines
new paragraph created by a blank line	new paragraph created by a blank line
newline|b+ within a paragraph	newline within a paragraph
put |i|something in italics-| etc	put something in italics etc
|m,name| email link (to your domain)	name email link (to your domain)
|l,home,home page| link to another page	home page link to another page
-list created by - at start of line -line 2 continuing -line 3 --sublist	list created by - at start of line line 2 continuing line 3 sublist
|h|heading	heading

If these formats don't do all you want, refer to automatic formatting specifications.

Other files you may occasionally need to edit:

• menus
• quotes
• configuration file

The help section includes additional reference resources, for example:

• testing
• filename standards

pages/intro.txt updated 12:49 Aug 18 2011

  scroll to top   home

Web pages created by this system have three main components, controlled independently:

• 'look and feel'
• menus
• content

Look and feel

The colour scheme and overall layout are controlled by:

• the configuration file public_config.txt
• css files (cascading style sheets) for screen and print
• the website driver

Menus

Menus are controlled by the files public_menu.txt and public_sub.txt

Content

Content is stored in individual text files, one for each web page.

Certain fixed information is in the configuration and quotes files public_config.txt and public_quotes.txt

pages/independent.txt updated 08:29 Dec 24 2010

  scroll to top   home

contents

• basics
• control characters
• commands
• formats
• headings
• tables
• embedded html

Basics

scroll to top

The content of each web page is stored as a text file [filename].txt, called the content file in this documentation to distinguish it from the web page, meaning the visible page delivered by the website driver. If edited externally, they must remain in UTF-8 format. Notepad++ and Jedit are two excellent free editors which can be set to do this automatically. Do not use Notepad supplied with Windows. Filenames of content files must be lower case. The screen and print format of web pages created by the website server depends on: automatic formatting of content files embedded html (if present) configuration files style sheets This web page covers automatic formatting. Automatic formatting creates web pages in html format (4.01 transitional). Automatic formatting is case insensitive (formatting commands are treated as if lower case). The title need not be included in a content file. If missing, it is take from the menu entry. Multiple spaces are treated as a single space. As is usual in HTML, a newline is displayed as a space. If the first non-blank character in a content file is <, html formatting is assumed. Otherwise automatic formatting is assumed. These assumptions can be changed with the |html and |auto commands (see commands).

Control characters, markup and tags

scroll to top

Web pages are usually in html format when they reach the browser. The layout of a web page is controlled by embedded html tags within the web page. Tags are surrounded by < and > characters. A simple example is <p>, which creates a new paragraph. html also uses & to mark character strings. The process of embedding tags is called markup. In fact html means hypertext markup language. Hypertext refers to the ability to create links, ie clickable text which jumps to a new location. You can view the html of most web page by clicking View > Source (or Page Source) in your browser. Automatic formatting creates html tags by interpreting the content file, but the format is much simpler than html, making it much easier to read and maintain, for example a blank line creates a new paragraph. Automatic formatting uses the characters | - and + to trigger the processing. Control characters <, >, &, | - and + within a content page not recognised by automatic formatting or by html are displayed normally, as in this paragraph. Very rarely, a character intended to be displayed normally may be interpreted as a control character. To make the character display correctly, replace the character with the corresponding html character string. The ones you might need are: < &lt; > &gt; & &amp; | &#124; - &#045; + &#043; [space] &nbsp;

Commands

scroll to top

Commands must be on lines by themselves. The opening | must be the first non-blank character. These commands are recognised: |auto change to automatic formatting |html change to HTML formatting |line,width line width [width], default 100% the line used is defined in the configuration file |rule[,width] horizontal rule, width [width], default 100% see also tables

Formats

scroll to top

Automatic formatting is strictly line by line. If formats need to extend across lines, repeat the formatting commands. variables have a grey background are in bold italics optional variables are shown surrounded by [braces] The following formatting commands are defined. They can be nested. |s,class|text-| text with class the -| is optional if the attribute spans to the end of the line standard classes are b (bold), i (italic) and u (underline) for other classes, see the style sheet standard classes can be simplified to |b|text-|, |i|text-| and |u|text-| use underline sparingly if at all - easily confused with a link |b+ line break |s+ non-breaking space |i,URL,image alt text[,width]| image for images, URL must include the directory name |l,URL[,link text]| link for local links to another page, URL may be just the page name |w,URL[,link text]| link (opens new window) for local links to another page, URL may be just the page name |m,email[,link text]| email link for local adressees, email can be name (the text prior to the @ in the address) |a,anchor| anchor (in-page link name) |quote,quote| include text with name quote for details see standard text

Headings, Paragraphs and Lists

scroll to top

Headings are applied to single complete lines. These lines may also include Formats. Paragraphs and list entries can continue over a series of lines, closed by any heading, paragraph, list, command or blank line. Headings, paragraphs and lists are created with one of the following at the start of a line: |h|text default h3 |hn[,class]|text Heading[n] with optional [class] |p,class|text Paragraph with [class] - list item A blank line not followed by one of the above creates a new paragraph.

tables

scroll to top

Basic table automatic formatting is available. Documentation to follow.

embedded html

scroll to top

html can create a larger variety of web page layout than automatic formatting. However, in practice the vast majority of content files need no embedded html. html can be freely included in content pages. Automatic formatting does not change it. html setting the format of text can be freely mixed with automatic formatting. Text format html tags include <span>, <font> and <i>. html setting the stucture of a web page can interfere with automatic formatting and vice versa. To avoid interference, use the |html command before the embedded html and the |auto command afterwards. Structural html tags include <p>, <h1> <li> and <table>. All the html tags mentioned have automatic formatting equivalents which are easier to use and easier to read.

pages/pages.txt updated 08:36 Jan 19 2013

  scroll to top   home

Standard text, often called boiler plate, is stored in the quotes file, public_quotes.txt. The file should be present, even if it is not used.

Stored quotes appear on a single line. The first word is the name of the quote. The rest of the line is the quote, which can include spaces. A common example is contact information, set up once and included on every page to ensure consistency, as at the foot of this page.

Quotes may be:

• a complete line, in which case all automatic formatting commands are available
• a phrase, in which case Commands and Headings must not be included

The format to include a quote is:

• |quote,quote|
  insert text with name quote

Missing quotes appear as [quote 'missing' not found] where missing is the name of the quote not found.

The line that results from including a quote must have a valid format. Applying formatting to a quote which already has a Command or Heading is therefore not valid and the line will not display as intended.

To remove a quote without removing the quote strings from individual pages, leave the quote name in the configuration file followed by |b+ or   (non-breaking space character).  

pages/quotes.txt updated 08:29 Dec 24 2010

  scroll to top   home

Menus are independently controlled by word-processed files saved as 'text' files kept in the /pages directory

• main menu (left) controlled by contents of public_menu.txt
• subsiduary menu (top and bottom) controlled by contents of public_sub.txt

Each menu entry is on a single line in the file. Put a line in and a new menu item appears. Remove a line and a menu item disappears. Blank lines are ignored.

main menu - typical menu lines:

what you put in the file level=0 filename=home level=1 filename=intro title=Introduction

what it does main menu entry (level 0) linking to page 'home', note all lower case main menu entry in the preceeding level 0 group linking to page 'intro' with displayed title text 'Introduction', title may include upper case

subsiduary menu - typical menu lines:

what you put in the file filename=home filename=intro title=introduction

what it does subsiduary menu entry linking to page 'home' subsiduary menu entry linking to page 'intro' with displayed title text 'introduction'

For full details, see menu specifications

pages/menus.txt updated 08:29 Dec 24 2010

  scroll to top   home

There is a main menu on the left of the page and a subsiduary menu at the top and bottom. These menus are controlled, respectively, by the contents of text files public_menu.txt and public_sub.txt

Each line represents a menu entry. Blank lines are ignored.

The line consists of a number of fields, separated by spaces.

Each field has the format
[fieldname]=[contents]

Fields must not contain spaces. Use the _ (underline) character as a placeholder for spaces in the contents field when necessary.

Fieldnames must be all lower case. Contents can include upper case.

Fields can appear in any order on a line.

Unrecognised fieldnames are ignored (eg incorrect spelling or case).

The only obligatory field is filename

The following fields are available. All are valid for the main menu. Those valid for the subsiduary menu are shown with an *.

filename=	filename	a page filename or a full url, obligatory field - page filenames are all lower case. filename is the default displayed page title if there is no title field. Upper case is allowed in filename; the page will be forced to lower case but the title displayed on the page will include any upper case characters.	*
level=	0 | 1 | 2 | 3	the single digit menu level of the item, 0 being the top level
title=	title	the title given to the page, defaults to filename	*
long=	description	the text displayed on mouse rollover	*
menutitle=	menu title	the title given on the screen, defaults to title	*
site=	only	suppresses menu entry (site map only)
sitebreak=	yes	causes a line break in the site map before the item
start=	dd/mm/yyyy	a numeric date before which the item will not appear	*
stop=	dd/mm/yyyy	a numeric date after which the item will not appear	*
format=	htm	treat the filename as a url rather than a page	*
target=	blank	link opens the page in a new window
meta=	meta,string	list of comma separated words to be added to the meta tags for this page
link=	anchor	adds an anchor string to the link, for diary use only
type=	diary	creates a diary pages link	*

pages/menufull.txt updated 08:29 Dec 24 2010

  scroll to top   home

The configuration file sets the look-and-feel of the website. Once created, it rarely need editing.

The configuration file is support/public_config.txt. It must be present and cannot be moved.

Configuration fields appear on a single line. The first word in a line is the name of the field. The rest of the line is the field, which can include spaces. A field cannot include automatic formatting. It can inclde html.

The following fields are in use:

• sitename [name of site] for the title tag
• sitetitle [an html string giving the layout of the main heading on each page
• sitetitlewidth [width of the site title, usually 90%]
• logo [address of site logo image] optional
• logoalt [alt text for the logo]
• home [filename of the home page]
• home_menu yes [yes if the home page is to have the menus]
• stylescreen [address of screen css sheet]
• styleprint [address of print css sheet]
• menutop yes [yes if the subsiduary menu is to appear at the top of each page]
• menubottom yes [yes if the subsiduary menu is to appear at the bottom of each page]
• width [width of page, normally 100%]
• public [address of diary file]
• visibility public [a diary switch]
• copyright [copyright notice]
• webmaster [webmaster email address]
• publisher [publisher email address]
• mail [default email domain name]
• search [domain name for search]
• support [html string indicating where to go for support]
• line [address of image used as separator]
• linewidth [the width of the line in pixels, usually 3]
• keywords [base keywords for the site]
• quotes [directory in which quotes file is stored]
• pages [directory in which content files are stored]
• menus [directory in which menus files are stored]
• test [description of the test] an optional field used during testing. Puts the field text at the top of each page and also hides all pages from robots.

pages/config.txt updated 08:29 Dec 24 2010

  scroll to top   home

Self-indexing uses document filenames to maintain a download web page, a significant reduction in work. Any directory can be made self-indexing. The update utility is one way of creating appropriate filenames.

Documents of specified types which have not expired are included in the download page. The list is structured for those documents conforming to the naming format, eg Writer downloads [new window]

The specified types of documents is configurable, defaulting to common word processor and image types.

Filename format: group_nameyyyy[mm[dd]][description][_rr]

where

• group_name documents with the same group name are listed together, name must end with an alpha character or underline
• yyyy[mm[dd]] numeric date of document, use 0000 when date is irrelevant, mm and dd are optional
• [description] optional description, must begin with an alpha character
• [_rr] rr is numeric retention period in months, _00 for permanent documents (default retention period is configurable)
• _ characters in group_name and description are shown as spaces in lists
• do not include [] in filenames, these brackets indicate optional fields
• filenames are all lower case
• documents with filenames not conforming to the self-indexing standard are listed as 'other documents'

Filename examples

• agm_agenda200506_48
• minutes20040713directors_meeting_00

pages/index.txt updated 17:50 Nov 14 2011

  scroll to top   home

documentation in preparation (facilities fully operational)

Random and Selected Images

... to be advised

pages/random.txt updated 18:14 Nov 14 2011

  scroll to top   home

The documentation option allows web pages to be combined for review or printing. Additional options allow selection of pages depending on the date pages were last updated.

Basic format: document[n]
Full format: document[date][0][n][_[a|b][[[dd]mm]yyyy]]

• document is the special page name to combine pages
• [] show optional fields and | shows alternatives - do not type these characters
• n is the numeric menu group, default all groups, eg here home is 1, background is 2 etc
• date suppresses page content (update summary) and also shows page ownership
• 0 includes all pages in the site map, default pages shown only in site map are ignored
• _ causes the command to be date sensitive
• a|b for after or before the date specified, default a, that is web pages last updated after or before the date specified are shown
• dd is day, must be two numeric characters, default 01
• mm is month, must be two numeric characters, default 01
• yyyy is year, must be four numeric characters, default current year
• dates are all counted from midnight

Example: to combine this menu section, the link is document4 [www.onepoyle.net/doc/main.pl?document4]

Menus are unaffected, ie suppressed pages appear in the menu.

pages/documenter.txt updated 08:37 Jan 19 2013

  scroll to top   home

The optional Owner line in a web page specifies responsibility and can also control who can update a page. To activate ownership, add an owner line anywhere in the page (at the bottom recommended).

format:

• [role] is the owner's role in the organisation, as displayed in the Update Utility
• [protect|fixed] is an optional field
  protect prevents anyone other than the owner from updating or deleting the page
  fixed prevents anyone from changing or deleting the page with the Update Utility (except that embedded quotes are updated)

• fixed takes precedence over protect if both are present
• if role is not present protect is ignored, but fixed works

a fixed page can be changed by file upload, normally available only to the webmaster

Ownership is not shown when a web page is displayed, but it is shown with the update summary

pages/management.txt updated 23:37 Jan 11 2010

  scroll to top   home

The diary is an optional part of the system controlled by corresponding configuration files. Diary application code is incorporated into the two servers, main.pl and text.pl.

Diary page names and characteristics are configured in public_diary_config.txt.

The diary files folder is defined in public_config.txt. Diary events are held in one or more text files. Events are assembled into a simple database which can be sorted and processed according to configuration settings.

Each event selected for display appears according to the template incorporated into the servers. Display format is influenced by both configuration settings and event data.

These pages supply some reference documentation, but in practice the easiest way to learn about editing diary files is to work from existing examples and to refer here only when unfamiliar or more advanced formatting is needed.

The diary has been used on the Guildford Choral website [new window] since 1995.

diarytest page

The diarytest page shows some possible formats. This page is also useful for showing what fields are available for each event.

Conventions used on the diary test page

• [field] placeholder for fields where only one value can be used
• [field0-9] placeholder for fields where more than one value can be used
• /comment/ a comment giving further information

pages/d_start.txt updated 08:38 Jan 19 2013

  scroll to top   home

Diary event

An event is defined by a several lines starting with 'event=[date]' and ending with '|'.

Between these markers, other fields, one per line all of which are optional, can appear in any order. The order and format in which they are printed is pre-determined by templates in the software. If a field does not appear in the event template, the associated text is not shown.

An event is printed only if [date] is correctly formatted: day dd mmm yyyy hh:mm

Thus, a typical event is:

event=Sat 8 March 2008 19:30
[other lines]
|

Diary files basic format

Field format is stem[any alpha characters][d]=data

where:
stem is four alpha characters defining the field name
[any alpha characters] are present for readabilty, but are always ignored
d is an optional single digit in the range 0-9. If omitted, 0 is used, thus field= field0= and fiel= are identical.
data is generally free-format

If a field   [field][n]=[text]   appears more than once, the last one is used. If the last appearance of a field is blank, the software acts as if the field has not been provided, even if there are previous non-blank instances in the event or the default.

It is possible to include some html within data, for example to insert a line break.

Many of the content management formats are also supported by the diary, including continutation lines.

Most fields can have multiple entries. The singleton exceptions are:

• boxoffice
• email
• emphasis
• ends
• image
• leaflet
• location
• price
• programme
• random
• type

If a singleton appears, the 0 digit is always assumed, irrespective of which appears in the diary file. If a singleton appears more than once within a event with different digits, there will be an error message.

Fields

Main keys

There are two kinds of records, the (normal) event and the default record:

event=default
[arbitrary default data]
...
...
|

event=[date]
[arbitrary event data]
...
...
|

The default record is used to record data common to several events, thus reducing the amount of data and making diary files easier to read. When the software encounters a default record, it clears previous defaults and memorises the new default data. Thus, an empty default record can be used to clear all defaults. When an event is read in, it is initialised with current default values. Default values can be overridden if desired by event data with the same key.

The order of events in the file is immaterial, except in so far as the default record in the file immediately preceding an event determines which default data is used. The order of data within an event record is also immaterial, except that if a field is mistakenly repeated, the last one is used. This also allows the default data to be temporarily over-ridden if required.

Links

Most fields may be converted into a link with ^ followed by the link eg

tenor=Luciano Pavarotti^main.pl?pavarotti

The above method makes the complete field into a link.

Most automatic formatting conventions can also be used, thus

note=The tenor is |l,pavarotti,Luciano Pavarotti| who sings with us for the first time

creates a link on part of the field.

Special fields

image=[filename]  random=[random image stem]

Either of the above will cause an image to be printed on the LHS. In addition, with image, use

credit=[name] to supply the image credit

Random images with the correct filename format are automatically credited.

emphasis=[h1;h2;h3;h4] controls size of text for the complete event (except for notes and descriptions)

summary=[text] not visible on normal diary page, but sets heading on summary page

pages/d_specs.txt updated 08:29 Dec 24 2010

  scroll to top   home

[this section is incomplete]

event=date | default
where date is www dd MMM yyyy hh:mm

• www is the day of the week [alpha]
• dd is the day of the month [digits]
• MMM is the month [alpha]
• yyyy is the year
• hh:mm is the time the event starts

If default appears, the record is a default record.

ends=date
the date the event ends, date in same format as for event

emphasis=h1 | h2 | h3 etc
defines the html heading level of the event. It is generally only applied to main events.

| must appear on a line by itself to end each event.

pages/d_fields.txt updated 08:29 Dec 24 2010

  scroll to top   home

This page is relevant only if you edit website pages or data offline

OnePoyle servers have been converted to unicode UTF-8. This applies to CGI PERL scripts, configuration, web and data files.

In general ANSI/ASCII files (the old standard format for text files) are forward compatible with UTF-8 files providing they contain no special characters. If a file does contain special characters (€ and ü are examples), conversion is necessary.

You will know a file needs conversion if strange characters appear, or if a web page is blank.

Although there are other options, Jedit is strongly recommended as the editor of choice for UTF-8 files. Notepad is best avoided as it can and does cause problems

Using Jedit with UTF-8 files

Jedit is an open source application, generally considered to be one of the best editors available.

There is a learning curve, but after half a day you may begin to find that editing is much easier than with Notepad.

In Windows Explorer views, you will often see additional files with almost the same name as the ones you are using, but ending with ~. Jedit uses these files for its own administration. Do not confuse the two.

Installation

Get the latest version (4.3pre16 at time of writing). You also need to have Java installed.

If necessary, get Java from Java download. For Windows click the Windows XP/... online link and download a small file. Run the downloaded file, which will download and run the full installer. At the start of installation clear the check box about installing the Yahoo toolbar, which is generally a bad idea - the Google toolbar is much better.

Download Jedit from Jedit download and for Windows click the Windows Installer under option 1.

Jedit settings for UTF-8

These settings need to be made once to prepare Jedit for working with UTF-8 files

Start Jedit.

Do Utilities > Global options > Encodings and select UTF-8 in the drop down list at the top. You can also check the Auto-Detect box, but in practice the encoding of text files cannot always be detected.

Do Utilities > Global options > View and check the first two boxes (Show full path and Always show search bar). The other boxes can be left as they are (whether checked or not)

Do Plugins > Plugin Options > Manage > Download Options (near bottom) > Jedit > Plugin Manager. Click 'Update mirror list' and wait until the list updates. (If the Plugin Manager option is not visible, double-click Jedit in the box on the left). Then click on one of the entries to select a Preferred Download Mirror. The Dublin one seems to work well for the UK. Click OK. Do not close the next dialogue.

Click the Install tab and check the Character Map box. (You may wish to choose additional plugins at this point.) Click 'Install' at the bottom of the dialogue box and wait for installation to complete.

Exit the dialogue box and close Jedit.

Restart Jedit. Do Utilities > Global options > Docking and for Character Map (on the right) select 'right' in the drop-down list for docking options. Click OK.

The Character Map should now be docked on the RHS of the Jedit window. Click 'Character Map' (vertical text) to open/close the plugin window.

Open any file or do File > New.

You can type most characters normally. For special characters, use the Character Map. Open the Character Map window as described above. Select the encoding with the special characters you need (oddly, this is not UTF-8. For Czech characters, for example, ISO8859-2 is the one you want). Click on a character to insert it at the cursor position. You can choose any Character Map encoding and change it as often as you wish. Characters you insert will be typed in UTF-8 format in the file you are editing.

Conversion

Converting from ASCII/ANSI to UTF-8 with Jedit is simply a matter of Copy from the ANSI file and Paste into a new UTF-8 file.

Here is the complete procedure:

• do File > Open, locate the ANSI text file to be converted and click open. Click OK to the I/O error dialogue. (If there is no I/O error dialogue, the file does not need conversion and you can work with it immediately in Jedit, including typing special and accented characters.)
• do File > Reload with Encoding and select Cp1252
• Ctrl+A Ctrl+C Ctrl+N Ctrl+V Ctrl+S (Select all, copy, new file, paste, save) and in the list of files, click the one being converted, which will be underlined
• click Save and in warning dialogue, click Yes

Search and replace basics

Search and replace is very easy with Jedit, much more powerful than with Notepad.

If you have followed the setup instructions above, you will see a 'Search for' box just below the toolbar. Type anything in this box to find the next example of those characters in the file. Press return (with the cursor in the 'Search for' box) to find the next instance. Search text turns red if the string does not exist.

For Search and Replace, click Ctrl+F. In the resulting dialogue box, type the 'Search for' and 'Replace with' text. You can replace all instances (Replace All) or just one (Replace and Find) by clicking the appropriate command.

Later, you may wish to learn how to search and replace from this dialogue box in all files, particularly useful if you are looking for something and don't remember which file it is in.

pages/ansi_utf8.txt updated 08:29 Dec 24 2010

  scroll to top   home

A substantial image gallery capability is included in the main.pl website driver, initally developed to support a local photographic group.

The software works for any images, but it was designed to work with structured filenames. If images are uploaded with the [application_unavailable_to_unauthorised_browsers] application, structured filenames are created by default.

Documentation here includes:

• searching - ie how to select the images you want
• structured filenames
• gallery navigation
• creating slideshows

pages/gall.txt updated 18:12 Nov 14 2011

  scroll to top   home

The images selected for display depend on

• the text typed in the 'match' box in Gallery Settings
• the filenames of images present in the selected gallery

The case of the match text is ignored, ie FREDA, Freda and freda all mean the same thing.

At the simplest level, the match text will find all images with that text in the filename:

• your name eg Freda Bloggs
• a subject eg Christmas
• the date of a photo, eg 20121225 for photos taken on Christmas day 2012

Technically, the match text is a Regular Expression (wiki) [new window], facilitating very powerful searches by what is called "pattern matching". The pattern, which is what you type in the 'match' box can include ordinary text plus 'modifiers' and characters which have a special meaning, which allow matching with alternative patterns.

Basic Modifiers etc

• . means any character
• .* means any number of characters, including none
• .+ means at least one character
• .? means 0 or 1 characters
• a* means any number of a's
• a+ means at least 1 a
• a? means 0 or 1 a's
• [ab] means a or b
• (apple|pear) means apple or pear
• a{0,3} means 0, 1, 2 or 3 a's
• \w means an alphabetic character, including _
• \d means a digit
• [0-9] also means a digit
• 20110115 means photos taken on 15/01/2011
• 201112\d\d means all filenames including dates in December 2011
• ^201112~ in the members gallery means pix submitted for the December 2011 gallery

 

Examples

search text	finds images with filenames containing
joh+n joh*n	john johhn johhhn... jon john johhn johhhn...
jo[a-z]n jo.{0,1}n	joan jobn jocn jodn... jozn jon joan jobn jocn jodn... jozn jo!n jo£n jo-n jo_n jo~n
(john|joan) jo[ah]n	john joan [both options give the same result]
200901\d\d \d{4,4}(01|02)\d\d	photos taken in January 2009 photos taken in January or February (any year)

 

Structured filenames

For more advanced searches it is helpful to understand the format of image filenames, since this is what is being matched.

The structured filename format is:

YYYYMM~

yyyymmdd~

title_of_photo

~location_or_subject

`photographer

~ABC123

.jpg (not always visible)

• YYYYMM is the numeric month the photo was put into the gallery
• yyyymmdd is the numeric date the photo was taken
• ABC123 is a reference of any length starting with a letter and ending with a number
  the original camera filename is the usual reference

Filename examples
20130119~Castle_Grounds`Freda_Bloggs~IMG1234
20130119~Guildford~Castle_Grounds`Freda_Bloggs~IMG1234
201304~20130119~Guildford~Castle_Grounds`Freda_Bloggs~IMG1234

So, for all Freda's photos in an image gallery taken in 2013 one possible match term is:
2013\d\d\d\d.*freda
ie all photos with a 2013 date (2013\d\d\d\d) followed by any number of characters (.*) followed by freda
Order is important, thus freda.*2013\d\d\d\d wouldn't work.

2013\d\d\d\d.*castle.*freda
for all Freda's Castle photos from 2013

2013\d\d\d\d.*castle
for everyone's Castle photos from 2013

Restrictions

In the image gallery for technical and security reasons the characters <>=#:;&$%@'"/\ are not accepted in the search term.

Characters ?|+*,^{}()[] are accepted only if used correctly as part of regular expression patterns.

If unaccepted characters or incorrect patterns are detected, the search term is replaced by .+ (everything).

More on Regular Expressions

• Regular Expressions (wiki) [http://en.wikipedia.org/wiki/Regular_expression] [new window]
• basic guide to Regular Expressions [www.regular-expressions.info/quickstart.html] [new window]
• google search: regular expressions [new window]

pages/search.txt updated 08:01 Mar 13 2013

  scroll to top   home

After copying files from camera to computer the first step in many 'digital workflows' is to rename files to something more descriptive than the short filenames created by digital cameras.

The gallery software extends this idea to use structured filenames to make selection of images by date, title or photographer an easy task.

Filename guidelines

Filename format is a personal choice reflecting what works for you, but the following notes may help to inform your decision.

Date

Date is probably the most important element. All-numeric dates in the format yyyymmdd (or yyyy-mm-dd etc) at the beginning of a filename are best because that helps to sort photos into chronological order. Alphabetic month names may look nicer, but they won't sort correctly.

Description

There are plenty of options, but location and subject is a simple choice that generally works well.

Photographer

If more than one person in your household uses a camera and you wish to distinguish the photos, or if you are sending photos to non-family destinations, include the photographer in the filename.

Original filename

It's often convenient to leave the original name (oldname) in place, since this is usually an easy way to make filenames unique.

Guideline

yyyymmdd~location~subject`photographer~oldname.jpg

• embelish yyyymmdd if 8 digits are too hard to read
• use a separator that won't appear in any of the other fields. ~ is almost certainly the best choice
• if used, a different separator for photographer is helpful in case location or subject is missing. ` (back tick usually on top left of keyboard) works well
• oldname must end with a number followed by at most one alphabetic character

If filenames follow this guideline, photos can be uploaded to the Gallery without typing the information again.

Members Gallery/Presentation filename format

YYYYMM~yyyymmdd~location~subject`photographer~oldname[P].jpg

The upload application ([application_unavailable_to_unauthorised_browsers]) imposes this format, as per guideline plus:

• YYYYMM defines the meeting (gallery year and month) in which the photo was included
• for a presentation, replace YYYYMM with a 6 digit sequence number to set the order of the images
• yyyymmdd is the date the photo was taken
• P at the end indicates portrait orientation (braces [] aren't added, they just denote that P is optional)
• if oldname isn't detected, pic01, pic02... are used

pages/filenames.txt updated 12:36 Nov 14 2011

  scroll to top   home

To improve focus on the images and to provide more space, the main menu and some other elements are not shown. To reach other website pages, click the site name at the top to go to the home page or the next page and submenu links at the bottom of each gallery page.

You can view images one per page at gallery or (usually) six per page at gallery multiple. To switch between views, click any gallery image. Search and sorting options are fully preserved when switching views, even for a random sort order.

Navigation buttons and access keys*

?	Help	show help
|◄◄	First	go to first page
◄	Back	go to previous page
►	Next	go to next page select display time and click next to start slide show click any button to stop slide show
►►|	Last	go to last page
►►#	Goto	go to page number typed in the box
display	Display	new selection of images based on choices in the boxes to the right for members gallery, type search text in first box for current month, clear the box for all photos, search for 'd' more search details [new window] select sort order and direction in the next two boxes select gallery to display in final box (if there is only one option, this box is not shown)
any gallery image	Jump	click to toggle between 6 per page and 1 per page

Access keys enable navigation using the keyboard
To use access keys in the gallery (replace K with a highlighted key letter as shown above)

• Alt+Shift+K in Firefox
• Alt+K in Internet Explorer, Safari and Chrome (from V3)
• In Opera Shift+Esc displays available keys, release, K to select then Enter
• for other browsers, see Access key [Access in different Browsers] [new window]

pages/gall_nav.txt updated 13:46 Nov 14 2011

  scroll to top   home

Slide shows are managed by a command on a single line which

• gets images
• prints slide show and search commands (optional)
• sets up the linking environment (optional)

Format

|SLIDESHOW,(directory|#CHOOSE#directory stem pattern#directory default#),[(image stem pattern|#SELECT#selection pattern#selection default#)]|,[sort order],[no of images on current page],[linked page name#no of images on linked page]|

The easiest way to create new gallery pages is to modify pre-existing pages. Multiple examples of galleries can be seen on the Guildford U3A Photo Group and these files are freely available on request.

pages/slideshow.txt updated 18:13 Nov 14 2011

  scroll to top   home

Implementation is straightforward and needs to be done only once, but for those who do not wish to bother with the intricacies, it may be better to ask for help from someone with the necessary experience.

We can provide implementation resource if required.

Resources set up by the implementor and not usually subject to change include:

• domain name and CGI enabled website space with PERL installed (in the UK we recommend 1&1, also operating in other countries)
• website structure on the website server
• OnePoyle PERL driver software copied to the server. No configuration is needed and PERL skills are not required.
• style sheets - for simplicity amend the ones used here rather than start from scratch
• configuration files controlling structure and look and feel
• images

The implementor will also set up or assist with initial versions of content files. Maintenance of the website thereafter can be carried out by adminstrative staff with basic PC and word-processing skills.

pages/structure.txt updated 08:29 Dec 24 2010

  scroll to top   home

Although the implementor will make suggestions, the client needs to decide and sign off on:

Style sheets

• color schemes
• type size
• font preferences (CSS defaults recommended)

Other

• images
• search words
• email addresses

pages/design.txt updated 08:29 Dec 24 2010

  scroll to top   home

By convention, web pages differ from other documents. Here are a few pointers to good web style:

• if a web page is not visible on a single 17" screen, it's often best to split the page
• never underline, easily confused with links
• don't use CAPITALS (considered rude - 'shouting') - use a heading or bold instead
• the majority of text in standard format (no embellishment or colour)
• emphasise rarely and where absolutely necessary using bold
• keep text short, no need for full English grammar
• use lists, easy to read
• include relevant links
• don't put full-stops in acronyms (AGM not A.G.M., eg not e.g.)

local standards

For consistency, additional standards are desirable. These are the ones adopted by GCS

• capitalise only first letters in titles and headings
• subsiduary headings usually h3 (the default)
• telephone numbers: (01483) 304234
• 24 hour clock for times: 19:30
• works:   Composer Name of Work

pages/style.txt updated 08:29 Dec 24 2010

  scroll to top   home

The software suite includes a flexible questionnaire q.pl and a corresponding analysis application qa.pl.

Set up a questionnaire by editing a couple of configuration files and creating a questions file using the update application.

For more see:

• questions
• questionnaire configuration
• questionnaire analysis

pages/questionnaire.txt updated 08:29 Dec 24 2010

  scroll to top   home

Text (headings, instructions etc) and questions are set up in the 'questions' configuration file questions_[qqq].txt
[qqq] is a three character alphabetic reference for the questionnaire

General format

Each line is part of a block of lines which may be either textual description or one of the question types Checkbox, Radio, Selection, Box and Line. Blocks can appear in any order as many times as needed.

Lines starting with # or | are ignored (comments).

Lines can be continued to the following line by typing =_ at the end of the line.

Control lines have the format
[type]_[subtype] text to appear on screen

• [type] has one of the options des|che|rad|sel|box|lin (for Description, Checkbox, Radio, Selection, Box, Line)
• [subtype] is descriptive of the control and valid values are described below

Unrecognised types and subtypes result in an error message.

Text

[type]_title [any text]
[type]_heading [any text]
[type]_e_heading [shorthand] (shorthand heading used in the analysis application, ignored by the questionnaire)
[type]_subheading [any text]
[type]_text [any text]
[type]_signature [any text]

The control subtype (title, heading...) sets the format for the text which appears on the page. There is no limit to the order or number of these lines.

[type]_separator (no text - draws a horizontal line)

Question lists

In Checkbox, Radio and Select blocks, the list of questions is set up as follows:

[type]_questions
text of first question [subsid]
text of second question [subsid]
...
text of last question [subsid]
[type]_end

[subsid] (optional) is either specify or select as follows:
##SPECIFY,[width],[text]##
##SELECT,[text],option 1|option 2|...|option n##

• [type] is one of che|rad|sel
• [width] is the width of the box
• [text] is a description of the field

Question types

Checkbox and Radio Questions

Checkbox and radio questions are almost identical, the only difference is that checkboxes allow multiple answers, whereas radio questions can have only one answer.

che_heading [any text] (optional)
... other text lines as needed
che_instructions [any text] (optional)
che_questions
... see above
che_end

For a radio question block, replace che_ with rad_

Select Questions

Select questions form a two-dimensional matrix on screen with each question having a set of alternatives in columns down the page.

sel_heading [any text] (optional)
... other text lines as needed
sel_instructions [any text] (optional)
sel_[column] option 1|option 2|...|option n
sel_questions
... see above
sel_end

[column] is radio|checkbox and the line sets column headings eg:
sel_radio crucial|significant|neutral|unimportant|irrelevant
sel_checkbox Guildford Cathedral|Guildford Civic Hall|Festival Hall|Albert Hall

Box and Line Questions

Free text answers, Box for multiple line answers, Line for short single line answers.

box_instructions [any text] (optional)
... other text lines as needed
box_heading [question text]
box_size [lines],[width]
box_end

[lines] and [width] are numbers, other characters are ignored.

For a line question, replace box_ with lin_
line size has only one parameter, [width]

What to avoid

It is self-evidently better not to alter the questions file once a questionnaire period has started. This constraint applies until the data is no longer needed because the questionnaire analysis application also uses the questions file.

If changes are essential, descriptive text can be altered.

Additional options and questions can be added, but these must be at the end, ie an extra column on the right, an extra option following existing ones and further questions at the end.

Because the numbering used to identify answers is automatic, changes altering the order of columns, options or questions, including insertions which are not at the end will associate previous answers with the wrong questions. An administrator could correct these errors manually. Although not complex, the process is very error prone and requires a full understanding of the numbering system. Make a backup of the files to be changed before starting. Use an advanced text editor like Jedit to work on all relevant files concurrently, working backwards through the numbering, editing old references into new ones.

pages/questions.txt updated 08:29 Dec 24 2010

  scroll to top   home

documentation in preparation

Questionnaire reference

Choose a three alphabetic character reference for the new questionnaire

Default questionnaire

Edit questionnaire_config.txt in the adminstration area, changing the reference line near the top.

This file includes other settings which generally do not need editing.

Questionnaire configuration

In the administration area, create questionnaire_config_[qqq].txt from a previous questionnaire or from the template.
[qqq] is the three alphabetic character reference for the questionnaire

Set the dates during which the questionnaire is to be available and, if necessary, edit other details.

Questionnaire analysis configuration

To restrict access to the analysis for a questionnaire, in the administration area, create qa_config_[qqq].txt from a previous questionnaire or from the template. and set the details accordingly.
[qqq] is the three alphabetic character reference for the questionnaire

pages/q_config.txt updated 08:29 Dec 24 2010

  scroll to top   home

The qa.pl application automatically analyses questionnaire data in real time. It can be run as often as desired, thus allowing the build-up of answers to be followed.

Once a questionnaire has been developed no additional setup is required for the analysis, which uses the same configuration files.

The analysis application has the following main options:

Numerical analysis

The 'analysis' option is displayed by default. It counts the choices for each selection question, displaying both the count and a normalised percentage. Percentage values are highlighted with colour to draw the eye to the more important results.

Textual analysis

This collates answers to each textual question, with options to show the names of respondents with links to individual questionnaires.

Respondents

Lists of names and emails of respondents and non-respondents, with optional links to individual questionnaires.

Individual questionnaires

Links from the textual analysis or respondents display individual responses.

Results table

A table of all data intended for copying for external analysis.

Specify and select results

A table of all specify and select data to allow easier assessment of this component. Data can also be copied for external analysis.

Personalised reports

Tables of detailed responses including any selection of keys and data items can be prepared. Reports can be saved for personal or public re-use.

The objective of these reports is to focus on specific sub-sets of data and optionally copy them for external analysis.

External analysis

We have had good experience analysing extracted data with the pivot table functionality of Libre Office Calc.

Firefox with the 'Table to Clipboard' addon is strongly recommended for copying data.

See also data field keys and values

pages/q_analysis.txt updated 12:49 Aug 18 2011

  scroll to top   home

preliminary documentation

Keys

Questions are numbered from 1.

Corresponding main keys are q_1, q_2,... q_n

Lower levels are added for the subquestions, down up to two further levels, eg q_1_2_3 is the key for the answer to the third column of the second row of the first question (in this example thus question 1 is a checkbox selection).

In addition, _sp for specify may appear at the end of a key.

Values

No answer is always displayed as a blank field and these keys are not stored in data files.

Textual answers are as the respondent typed them.

Other answers have 1 for the first option with 2,... being used when multiple choices are available for one question. Thus select box answers will always be blank or 1, whereas radio or multiple selections will also have higher values.

Refer back to the questions file to interpret the answers in tables against the original questions.

pages/q_keys.txt updated 22:24 Jan 16 2011

  scroll to top   home

This section includes aspects that have caused difficulty for individuals in the past and additional background.

The links to relevant resources on the web include webmail and administration for the recommended domain host.

pages/help.txt updated 08:29 Dec 24 2010

  scroll to top   home

All files are in plain text format. Filenames must not contain spaces and must be all lower case. You can specify upper case filenames in menus, as these also control the titles, but the filename the system uses will still be all lower case.

The main configuration file is in the support/ folder.

Folders for pages, quotes and menu files are set in the configuration file, however pages/ is a common choice.

The folder for css files (cascading style sheets) is also set in the configuration file, however support/ is a common choice.

The location of images is set individually.

Automatic formatting and style sheets

In this implementation, style sheet attributes are all in lower case. The software forces all class attributes to lower case.

pages/standards.txt updated 08:29 Dec 24 2010

  scroll to top   home

Visitors are impatient. For most pages, a single screen is enough (i.e. what fits on a 17in screen without the need to page down).

Make it easy for visitors to focus. Put text of most interest to them first.

A reasonable approach is to develop content in the usual way, then cut out as many words as possible without losing the essence of the message. If there is too much text for a single screen, consider splitting it.

pages/screen.txt updated 08:29 Dec 24 2010

  scroll to top   home

It is often convenient to convert an Libre Office Writer document for the web. This page explains how to do that quickly and easily with the Update Utility. Use Libre Office in preference to another word processor (see advantages).

Update always makes minimal changes for compatibility with the web site, but to conform to the standard 'look and feel' of the website, use the following hints:

Initial preparation

Open the Styles and Formatting pane (click F11), apply Heading 1 at the top of the document and other headings through the document as necessary rather than formatting headings by hand. Although they look identical, they don't work the same way.

Minimise formatting. Bold and italic are fine, but never use underline to avoid confusion with links.

Hyperlinks to web pages are converted correctly. (Select some text and click Insert > Hyperlink. It's best to get the Hyperlink right the first time as amendments are a bit of an art.)

Images in the document will need to be uploaded. Update will tell you what to do.

Avoid headers and footers, eg don't start from a letter template. The web site already has the equivalent.

Web page creation

• Create or open the document you wish to convert
• Remove newlines at the end of lines which are logically part of the same paragraph
• Remove empty paragraphs (blank lines)
• Do File > Save as; select HTML document as Save as type; Type a filename.
• Click Save and close the file
• With the Update Utility, working down the upload web page form, first browse for the file
• Next select an area to save the file, eg test
• Type a web page filename
  If you selected the test area, the web page will be saved as _test_[filename] where [filename] is the name you typed
• Set convert file to yes and click upload web page
• After install, review the page in a different window - the Update Utility provides the necessary link
• To edit the page, click Back from the Update Utility confirmation screen, type the filename, check the box corresponding to the area the page was saved; click web page content and then edit the file
• For further edits, click Back from the Update Utility confirmation screen

What if something doesn't work?

If the resulting page is not what you expect and you can't immediately see what is wrong, install the page again, but with convert file set to no. If this works, the page may be useable, though formatting (especially fonts) will differ from the rest of the site. In any event, send the troublesome file to the webmaster for investigation.

---

Advantages The html code Writer creates is simpler that Word's, leading to less troublesome conversion. Libre Office Writer is better than Word for many users. For more details, see Libre Office.

pages/update_convert.txt updated 12:54 Aug 18 2011

  scroll to top   home

To make PERL applications (PERL 8) work as servers to create web pages dynamically in UTF-8 mode, the following notes may help.

Good advice can be found on the net. These are my notes on what was needed in my scripts.

The lines shown are to replace or be in addition to existing lines:

First step, convert perl scripts from ASCII/ASCI to UTF-8 (use Jedit for preference)
Open file with original encoding. Then Ctrl+A,Ctrl+C,close file,Ctrl+N,Ctrl+V,Ctrl+S and save with original name

#!/usr/bin/perl -CSDA

use open ':encoding(utf8)';
use utf8;
binmode STDOUT, ":utf8";
use Encode;

print "<meta http-equiv='Content-Type' content='text/html; charset=UTF-8'>\n";

Possibly optional, but probably worth doing, remove use Filehandle and use open(...) instead:
This example is for reading a file. Adjust < to > or >> as necessary
my $open;my $fdi;my $file=dir/name.txt
open($fdi,"<:utf8",$file) or $open="Warning: $file file did not open $!";

It seems better not to use utf-8 in place of utf8 because the former is too strict for files with no utf8 characters.

If characters behave oddly you may be using the wrong encoding at open eg standard windows files are likely to have the CP1252 coding
open($fdi,"<:encoding(cp1252)","$mailbox")

To avoid the CGI script crashing if it encounters a cp1252 file I include the test:
if (utf8::valid($line)) {
...normal processing
}
else {$line ='##### non-utf8 character in line - wrong file encoding - please correct #####'}

For text files read in, apply the following to the first line to remove the byte order mark 0x200B [zero width space] that some editors include a the start of UTF-8 files

my $zwsp="(\x{FEFF}|\x{200B})+";#some possible BOMs
my $il;
if (!$il && $_) {$_=~s/^$zwsp//;}#get rid of byte order mark on first line
$il++;

OR

my $zwsp="(\x{FEFF}|\x{200B})+";#some possible BOMs
$lines[0]=~s/^$zwsp//;#get rid of byte order mark on first line

CGI parameters - create a parameters hash:
foreach my $name ( param() ) {@query{$name} = Encode::decode_utf8(param ($name));}#read CGI variables into hash

For preference, use Jedit as main editor for text files.
Set Jedit to use UTF8 as default:
Utilities>Global Options>Encodings and select UTF-8

Install the Character Map plugin, dock it and select the encoding which shows the characters you wish to insert, eg ISO8859_2 includes Czech characters, ISO8859_1 has Western European (eg French, German, Spanish) characters. Oddly, selecting UTF-8 does not work.

Alternatively, use a Word Processor to edit the files (eg Libre Office Writer) and, for example, take advantage of being able to type with a local keyboard mapping, in which case a safe way is to keep the master document in the native .odt format and when editing is complete 'Save as' as 'Text encoded' and select UTF-8 encoding. Opening the .txt text file, editing it, and doing File > Save destroys the content (the file is saved as ASCII/ANSI). Some characters will be saved scrambled and it is difficult to recover.

Convert existing text files (configuration, data...) to UTF8. (File > Reload with encoding and select endoding (usually CP1252), Ctrl+A, Ctrl+C, Ctrl+W, Ctrl+N, Ctrl+V, Ctrl+S and select the same filename).

You don't need to convert all files. Those without special characters are backward compatible. Those with (eg £ and €) need conversion.

Notepad is best avoided. If you are careful to save with the right encoding, everything may be fine, but it is easy to create a CP1252 encoded file from ASCII by typing a (first) special character. Notepad also writes non-standard headers, which can cause problems.

pages/convert_to_utf8.txt updated 12:49 Aug 18 2011

  scroll to top   home

Careful testing is essential. It is easy to overlook something.

• spell check and proof read pages carefully
• use an online test area to review changes before making them live
• ask someone else to check the pages

pages/testing.txt updated 08:29 Dec 24 2010

  scroll to top   home

Content and structure files used are all text format files. Usually they are edited online with the Update Utility.

If you choose to work offline, the files can be created and edited using virtually any word processor or text file editor.

Here is a selection:

NotePad

The simplest, and normally the editor linked with text format files. Not recommended for UTF-8 files.

WordPad

Slightly more capable that NotePad, also handling larger files. Not recommended for UTF-8 files. Select 'all documents' when opening and 'text' when saving.

Jedit

Outstanding open source editor and the one I recommend. download jedit [www.jedit.org/index.php?page=download] (choose the development version)

Libre Office

Recommended for creating new pages.

Not ideal as a text file editor. If you wish to use its advanced search and replace and spell-checking, make sure to turn off 'Replace "standard" quotes with "custom" quotes' in Tools>Autocorrect>Options

Word

Not ideal as a text editor. For pitfalls, see How do I use Word as a text editor?

pages/editor.txt updated 12:48 Aug 18 2011

  scroll to top   home

background

• writing for the web [www.useit.com/papers/webwriting/]

accessibility

• The Web - Access and Inclusion for Disabled People [www.drc-gb.org/publicationsandreports/2.pdf]
• Bobby [http://bobby.watchfire.com/bobby/html/en/index.jsp] check on accessibility
• Betsie [www.bbc.co.uk/education/betsie/index.html] BBC text filter (principles copied in the text only code)

testing

• testing [www.onepoyle.net/doc/main.pl?testing] key points
• html validator [http://validator.w3.org/]
• css validator [http://jigsaw.w3.org/css-validator/validator-uri.html]

webmail and adminstration

• 1&1 webmail [http://webmail.oneandone.co.uk]
• 1&1 webmail FAQs [http://faq.oneandone.co.uk/e_mail/webmail/index.html]
• 1&1 website adminstration [http://admin.1and1.co.uk]
• for website usage statistics on 1&1, use the address 'www.[your domain name]/logs'

regulations

• Electronic Commerce Regulations (SME) [http://www2.dti.gov.uk/industries/ecommunications/electronic_commerce_SME_guide.pdf]

reference

• HTML 3.2 reference [www.htmlhelp.com/reference/wilbur/]
• Google's Web Useability directory [http://directory.google.com/Top/Computers/Internet/Web_Design_and_Development/Web_Usability/] the full works
• For those interested in Google, look at Page Rank Explained [www.iprcom.com/papers/pagerank/] Ian Rogers Anatomy of a Large-Scale Hypertextual Web Search Engine [http://www-db.stanford.edu/%7Ebackrub/google.html] original paper by Google founders Sergey Brin and Lawrence Page
• html character set [www.natural-innovations.com/wa/doc-charset.html]

pages/links.txt updated 08:29 Dec 24 2010

  scroll to top   home

To support a normal website, including email users, the following skills are needed:

• website content maintenance including support for other users
• website administration (website and email passwords; email addresses and redirection)
• website images maintenance
• email user support
• application user support (database access applications, update and questionnaires)
• website backup and logfile analysis
• offline database support
• administration of 'e' documentation and policies
• user training

For more information please call Mike Hall on +44 (0) 1483 304234
or email mike.hall

pages/training.txt updated 08:29 Dec 24 2010

  scroll to top   home

This page gives an outline of the training suggested for those who will be supporting content. The two training sessions are probably best separated by a couple of weeks.

Prior activity

• Become familiar with your current website
• Decide on responsibilities (who will maintain content, who will manage email settings and the domain, who will manage online space, who will deputise)
• Decide where to store website source files (local server or individual PC?) and set up the parent directory, with a suitable name
• Read the introduction and, if there is time, dip into other documentation

Training Session 1

• Review prior activity
• Automatic formatting of content pages (introduction)
• Filename standards
• How it all fits together (introduction)
• Menus (introduction)
• How to use the online documentation
• Managing email mailboxes and redirection (1&1 Control Panel)
• Domain management (1&1 Control Panel)
• Questions

Practice between sessions

• Refer to online documentation
• Amend a page
• Create a new page
• Add corresponding menu entry
• Use the Control Panel
• Use Webmail

Training Session 2

• Review practice activity
• Automatic formatting of content pages (in depth)
• How it all fits together (review)
• Menus and configuration files (in depth)
• Safe testing
• Managing online webspace - ftp (file transfer) application
• Handover of content management responsibility; Software update policy
• Website statistics (log files)
• Questions and how to get help

I'm interested in learning more. What should I do?

Choose from among the following:

• Practice and extend skills already learned
• Study this documentation in more depth and experiment with what you learn
• Install Libre Office
• Learn basic HTML (for example complex page layout may need html)
• Learn about CSS (cascading style sheets)
• For the really adventurous, learn PERL

pages/tr_schedule.txt updated 12:52 Aug 18 2011

  scroll to top   home

Maintaining website content is much more than accepting contributions and uploading them. To maintain overall quality of the site:

• expect spelling, punctuation, layout and English deficiencies on pretty well 100% of contributions
• ensure conformance to the site style guide
• challenge content to test whether its organisation is right
• check whether other web pages are affected or additional ones needed
• change the format of content to better fit web page context
• assume that images need editing to improve white balance and to reduce their size for the web
• regularly check content and menus edited by others, including the diary and repertoire if used, in the same ways

For more information please call Mike Hall on +44 (0) 1483 304234
or email mike.hall

pages/tr_content.txt updated 08:29 Dec 24 2010

  scroll to top   home

The OnePoyle website system is designed for organisations wishing to maintain their own websites with minimal effort.

You benefit from exceptionally easy content maintenance, yet the resulting web site automatically retains a consistent, professional look and feel.

Reference sites [new windows]

• Guildford Choral [www.guildfordchoral.org/main.pl] The original development site
• U3A Guildford Photo Group [www.onepoyle.co.uk/u3a_photo/main.pl] A recent site showing many photographs

Background

Out of date web pages are of little use. The key design objective behind the OnePoyle website system has been to make it easy to keep a web site up-to-date.

Implementation is straightforward. The system can readily be applied to enhance existing websites or to launch new ones.

Implementation of a website may involve a new domain name, and if so, corresponding email addresses are available.

These pages give an overview. For more details, please see the full documentation

For more information please call Mike Hall on +44 (0) 1483 304234
or email mike.hall

pages/tr_website.txt updated 08:29 Dec 24 2010

  scroll to top   home

.. in preparation

For more information please call Mike Hall on +44 (0) 1483 304234
or email mike.hall

pages/tr_email.txt updated 18:28 Nov 14 2011

  scroll to top   home

The test pages illustrate various levels of complexity.

• The simple page has no markup
• The typical page has common but straighforward markup
• The test page has markup from the simplest to very complex
• There is also a missing page, showing what happens

pages/test.txt updated 08:29 Dec 24 2010

  scroll to top   home

a simple page needs no explicit markup

• with
• a
• list

a new paragraph continues on the next several lines

and another paragraph

pages/simple.txt updated 08:29 Dec 24 2010

  scroll to top   home

a typical page with straighforward markup and control commands

with several paragraphs as long as you like

• with
• a
• list too

and perhaps a link home to another page

possibly with a subheading

another paragraph with something emphasised in italics to
liven it up
before continuing on the next several lines

and another paragraph, prior to a standard footer

pages/typical.txt updated 08:29 Dec 24 2010

  scroll to top   home

For various reasons the standard logfile analysis reports provided by the ISP do not do the business. logan.pl has been developed to fill the gap. It is designed to give information useful to the webmaster and others developing content for a website, particularly for a CGI driven site.

Logfile analysis is a heavy resource user, therefore the analysis is done in a number of stages. Once the first two stages are complete, displaying results is rapid.

Stage one: Copy

Checks that the most recent logfiles have been copied across, and if not, copies across the oldest.

At present, newly copied logfiles cannot be analysed until they have been manually decompressed. It may be possible to make this step automatic later on.

Stage two: Analyse

Reads each logfile and creates a results file with counts of each relevant activity. This stage is a very heavy resource user and a maximum of 5 logfiles are handled in each pass. In some cases, with very large logfiles, it may be necessary to limit the number handled even further or even, for websites with very heavy traffic, to do this part of the analysis offline. Once complete, the analysis does not normally need to be repeated.

If the option to reanalyse is chosen, it will take several passes to repeat stage two. This option is needed only after enhancements to the analysis routines.

Stage three: Accumulate

Read the results files for the period chosen and accumulate results.

Display logfile dates, total counts, weekly average and, optionally, weekly totals

Interpreting the results

...to follow...

pages/logfile.txt updated 08:29 Dec 24 2010