Queen S Library Project Implementation Guide

Queen’s Library Project Implementation Guide

Kevin Goodridge
7 July, 2003
ecentricarts Inc.

317 Adelaide Street West, suite 309

Toronto (ON) M5V 1P9

t: 416.644.5000 x 231 f: 416.644.1004

Version / Date / Author / Description
2 / 17/09/03 / Kevin Goodridge,
Gordon Lemon / Third version.

[ Document has been slightly amended by Liz, to accurately reflect final Queen’s setup ]

Table of Contents

1 Implementation Guide 2

1.1 Purpose and scope of this document 2

1.2 Site Structure 2

1.2.1 Underlying technology 2

1.2.2 File formats 2

1.2.3 Directory Structure 3

1.2.4 Naming Conventions 4

1.3 Site configuration 5

1.3.1 Main Library Page (index.htm) 6

1.3.2 Landing Page (landingpage.htm, or Type 0) 6

1.3.3 Layout Type 1 (type1.htm) 6

1.3.4 Layout Type 2 (type2.htm) 6

1.3.5 Layout Type 3 variation 1 (type3-1.htm) 7

1.3.6 Layout Type 3 variation 2 (type3-2.htm) 7

1.3.7 Cascading Style Sheets 7

1.3.8 W3C considerations 8

1.4 Accessing the live and development Queen’s Library sites 8

1.4.1 Editing the Development site 8

1.4.2 Updating the Live site 9

Queen’s Library Project Implementation Guide 9
© 2003 ecentricarts Inc. - CONFIDENTIAL

1 Implementation Guide

1.1 Purpose and scope of this document

This document describes the structure and configuration of the prepared templates for the Queen’s Library (QL) site. This includes the following: the home page (index.htm), landing page (landing.htm), content type 1 (type1.htm), content type 2 (type2.htm), content type 3 (type3.htm). There are additional variations of type 3, named type3-1.htm and type3-2.htm.

Armed with this document, editorial and production staff will be able to mark up static html content for use in the QL site.

Below, the structure of the static portions of this web site is described, with emphasis on re-use of delivered code for the addition of new content. Graphical content preparation for navigation use is covered in a separate section.

1.2 Site Structure

This site makes extensive use of server-side include (SSI) technology, to facilitate code reuse. This allows for the existence of a single footer file, which is dynamically inserted into a document when a user requests a web page. SSIs are used primarily for navigation items, headers and footers.

1.2.1 Underlying technology

Much of the code on the QL site is standard XHTML and CSS. A minimal amount of client-side JavaScript is used for graphical rollover effects in the navigation and form validation. Cookies are used in the language toggle bar to allow users to switch between French and English.

A key feature of the site is its “future-forward” W3C compliant XHTML and CSS. The code was written to conform to W3C standards for XHTML 1.0, CSS 2, and the W3C Accessibility guidelines. By coding to these standards, the site should render properly in current browsers as well as future W3C compliant browsers.

Any code that is added to the site should conform to these standards. Some excellent resources for learning to code to W3C standards include:

http://www.nypl.org/styleguide/

http://www.webstandards.org/learn/faq/

http://www.webstandards.org/learn/resources/

This code should be run through a validation service. We recommend the following:

HTML: http://validator.w3.org/

CSS: http://jigsaw.w3.org/css-validator/validator-uri.html

1.2.2 File formats

The web site is built with several kinds of files, which together compose the site.

· Graphics (.jpg or .gif)

· External CSS style sheets (.css)

· External JavaScript files (.js)

· Include files (.htm)

1.2.3 Directory Structure

Most web pages reside at the web root, but some are contained in a folder which has a specific use, as outlined below. CSS documents, include files for headers etc., images, and so on have their own subdirectories.

1.2.3.1 table: relevant directory structure

Directory / Use / Notes
/ / web root / Contains all pages visited by clients
/css / CSS external style sheets
[1 folder, in main web account => governs entire site] / CSS governs colour, size, alignment, font attributes etc. displayed by modern web browsers. This folder contains global layout and presentation style sheets.
/images / graphics files / Global graphical elements, such as the top nav, and banner images.
/includes / include files for site-wide common elements (i.e. banner [except photos], button bar & footer) / Global reusable elements, such as header, footer, and global navigation files. Generally these will not be edited.
/js / JavaScript include files
[1 folder, in main web account only => governs entire site] / Standard client-side script for dynamic rollover effects on hyperlinked menu graphics, etc.
/circ
/inforef
/law
[ /webart ]
/webcoll
/webdoc
/webedu
/webeng
/webmed
/webmus
/websrs
/webtrc / Individual unit / library folders / Content, Images, Downloads for each individual library will reside in these folders.
Each unit/library account will contain its own sub directory structure, containing (but not limited to):
/images -- for photos
/includes -- for left nav bars
/templates -- to copy from

1.2.4 Naming Conventions

The naming convention for templates and graphics is more than an organizational nicety. The workflow process depends on a structured approach to naming files, so that there is little chance of files being overridden. It also provides a framework for finding the appropriate content when it is sought.

1.2.4.1 Content files

All content files, which are based on the template files, SHOULD be named in accordance with the following scheme. A content file name will be in this form: sec-ssc-pgn-cnt.htm.

Legend

sec 3 character section abbreviation (i.e. abo)

ssc 3 character subsection abbreviation (i.e. mee)

pgn 3 character page abbreviation (i.e. nat)

and so on…

Content files will be based on one of the template pages (these start with “type”), and can be named with two (i.e. sec-ssc.htm), three (i.e. sec-ssc-pgn.htm), or four 3-character abbreviations. As many abbreviations as necessary can be added to allow for more layers of nested content.

Examples:

liq-col-map.htm: Libraries at Queen’s > Libraries & Collections > Maps, Data & Government Information section page

liq-col-map-can.htm: Libraries at Queen’s > Libraries & Collections > Maps, Data & Government Information > Canada page

Or, because many of the individual libraries will have a folder at the root level, you may see files named--

map-gov-can.htm: Maps, Data & Government Information > Government Information > Canada page. All pages in this Government Information subsection would start with “map-gov” followed by the page name.

liq-ind.htm: Libraries at Queen’s landing page. This would include the links that appear in the Libraries at Queen’s navigation drop-down.

Please note that the above scheme is one suggestion. Another scheme may be implemented as long as it is documented and used strictly. Folder names need not follow the same convention.

1.2.4.2 Web graphics

A similar scheme should be loosely adhered to for naming graphic files. It follows the form of: xyz-sec-ssc-description_state.gif (or .jpg)

Legend

xyz 3 or 4 character abbreviation for the image function/placement (e.g. btn = button, lnav = left navigation, ttl=title)

sec 3 character section abbreviation (i.e. abo)

ssc 3 character subsection abbreviation (i.e. mee)

description 3 or more character image description (i.e. bio=biography)

_state See 1.2.4.3 below

Examples:

tnav-ban-lib-edu.gif: Top nav image, for the banner, library portion, for EDU library

1.2.4.3 Rollover states

Graphics used in DHTML rollover effects are always GIFs, and have suffixes as follows:

_off.gif The “off” state or normal state of the graphic.

_on.gif The “on” state, shown when the mouse cursor is over the graphic.

1.3 Site configuration

All templates make use of include files, to generate the complete page that a user sees in his or her browser. Most commonly, a file will contain at least:

1. A version of the header file

Each header file contains the queen’s logo, a library title (or the generic title), a default image that loads if no javascript is available on a user’s machine, and a javascript loaded image, that selects from one of 5 images in the /images folder. More information is located in the file itself.

2. Two files for the top navigation

OR

where sec is the selected section

The first file has the visible buttons, and the second contains all of the drop down menu elements. For the case where a user has entered a specific section (e.g. Research Tools), there is a different tnav file. This would be named inc-tnav-res.htm. The appropriate tnav file should be included for each sub page in a section.

3. The footer file

The footer is included as is for all pages in the site.

4. A version of the left nav, for content pages

More detail can be found in the type3 template files.

The content templates provided to Queen’s include 5 basic layouts, and some variations on type3:

1.3.1 Main Library Page (index.htm)

When a user requests the root of the site (e.g. http:// http://library.queensu.ca/) the server should present the index.htm file as the site main page. This property is set through IIS on the server.

The editable area(s) are between <div> tags marked with id=:

int-content

content-title

sub-title.

1.3.2 Landing Page (landingpage.htm, or Type 0)

This is a special case template. It is used only to replicate the links available to a user in the five drop-down menu items in the top nav. Each of the links in a given drop-down should be replicated in the landing page file for that section. Landing pages should be named sec-ind.htm, where sec is the site section as defined in the top nav, and ind indicates that this is the landing page for this section.

The editable area(s) are between <div> tags marked with id=:

type0-lcol

type0-rcol

1.3.3 Layout Type 1 (type1.htm)

All templates that begin with “type” are content templates, and will be the templates used the most frequently.

Type 1 is the simplest layout. It contains space for a left nav, and the remainder of the page is filled with content. This will probably be the most commonly used file.

The editable area(s) are between <div> tags marked with id=:

type1-full

1.3.4 Layout Type 2 (type2.htm)

Type 2 adds a right hand side bar to the type 1 style template. The content area is made more narrow, to accommodate the size of the sidebar.

The editable area(s) are between <div> tags marked with id=:

type2-main

type2-sidebar

1.3.5 Layout Type 3 (Type3.htm)

Type 3 is the most complex of the layouts, and the most easily customizable. It contains four text (content) areas, which can be used or deleted as suits a given need.

The editable area(s) are between <div> tags marked with id=:

type3-intro

type3-lcol

type3-rcol

type3-full

1.3.6 Layout Type 3 variation 1 (type3-1.htm)

A variation of the Type 3 layout, which does not include the type3-intro content area (at the top of the content area).

The editable area(s) are between <div> tags marked with id=:

type3-lcol

type3-rcol

type3-full

1.3.7 Layout Type 3 variation 2 (type3-2.htm)

A variation of the Type 3 layout, which does not include the type3-intro content area (at the bottom of the content area).

The editable area(s) are between <div> tags marked with id=:

type3-intro

type3-lcol

type3-rcol

1.3.8 Cascading Style Sheets

The use of CSS to separate content from formatting should be followed as it is a W3C requirement (also see W3C considerations below). Instructions on using the style sheet properties can be found in the style guide, within the templates, and within the style sheets themselves. Most section templates include the following style sheets:

css/ver4.css – Contains rules for basic text formatting in older (version 4 and below) browsers.

glb-formatting.css – Rules for text-based styles, such as titles and headers.

glb-layout-content.css – Rules for content layout.

glb-layout-hel.css – Page specific rules.

glb-layout-ind.css – Page specific rules – in use at the moment.

glb-layout-liq.css – Page specific rules.

glb-layout-lis.css – Page specific rules.

glb-layout-nav.css – Rules for all navigational elements.

glb-layout-new.css – Page specific rules.

glb-layout-res.css – Page specific rules.

print-rules.css (plus the ancillary file print.css,) – Rules that define printable areas of the page (note: supported only in IE 6+ PC, Netscape 6.2+ PC, IE 5 Mac)

1.3.9 W3C considerations

As mentioned above, the code in this site adheres to W3C standards. In order to maintain these standards during subsequent revisions, Queen’s staff should become familiar with these standards. A few common issues include:

- write all tags in lowercase i.e. <hr />, not <HR />

- quote all attribute values i.e. width=”22”, not width=22

- all tags must be closed, including empty tags. i.e. <p>content</p>, <li>content</li>, <hr />, <br />

- all image tags must include an alt attribute. If no text description is appropriate an empty alt attribute should be included. e.g.: <img src=”image.gif” alt=”my image name” width=”22” height=”22” />

- Hyperlinks that open a new browser window must warn the user before doing so. This can be achieved by adding a title attribute to anchor tags. The following method is recommended and in use throughout the site:

title="Opens a new browser window”

A complete anchor tag would take the following form:

<a href="page.htm" title="Opens a new browser window “ target="_blank">hyperlink text</a>

Note: JavaScript should not be used to open new Browser windows

1.4 Accessing the live and development Queen’s Library sites

All changes to the QL web site should first be carried out on the development site and thoroughly tested in at least IE 5.5 or 6 and Netscape 6.2. Only once you are sure the changes are rendering correctly should you upload the files to the live web site.

It is recommended that a workflow process be devised, implemented, and strictly adhered to, in order to minimize risk in overwriting already completed work.

1.4.1 Editing the Development site

It should be habit that files are downloaded from the development site, prior to making changes to a file. This helps ensure that the newest file is always utilized when changes are being made. In addition, the “live” server should NEVER contain newer data than the development server.

If local copies of files have been used to make edits, be certain to delete any remaining local copies once the files are uploaded and tested on the development server. This will again prevent the possibility of “old” files overwriting “new” files. Once a page has been edited, it should be uploaded to the dev site and tested. It is recommended that a dedicated ftp client be used such as Cute FTP or WS_FTP.