WWPWeb

From Digital Scholarship Group
Jump to navigation Jump to search

Updating

To update the website from the Subversion server:

  1. Log in to the test or production machine via the commandline.
  2. Change the current directory to the target directory (/var/www/html/WWP/ for the whole website) using the cd command. E.g., cd /var/www/html/WWP/outreach/seminars/.
  3. Issue sudo chgrp -R wwp ..
  4. Issue sudo chmod -R g+w ..
  5. Issue svn up to update the entire directory OR issue svn up filename1 filename2 to update only those two files

The WWP web site

The WWP web site was thoroughly redesigned during 2010, with the new version of the site going live in early 2011. This redesign included a major overhaul of the directory structure underneath the site as well as a completely new interface. It also involves a significant increase in our reliance on dynamic content and scripting (PHP and JavaScript) to deliver information, visualizations, and interaction.

Structure

The WWP site is divided into four major structural sections, in terms of the presentation of content:

  • About: contains information about the people (staff and students) who work at the WWP, the ongoing programs and projects we're involved in, upcoming events, and the project's history
  • Outreach & Education:' information about our workshops and seminars, Women in the Archives, consulting activities, internship program, and resources and further information about text encoding/digital humanities
  • Research & Publications: information about specific projects we're involved in, publications we've jointly or individually authored (including encoding documentation and guides), and major collaborative work that has resulted in published output
  • Women Writers Online: information about subscribing to WWO, list of texts we've published and are planning to publish (including tracking of forthcoming texts), teaching and learning section (including syllabi and how-tos for class projects), and "WWO Labs" (what we're now calling our sandbox for experimental interfaces and tools)


Interface

The new WWP site has been designed to provide a consistent interface across the WWP's entire Web universe. That means a persistent top-level menu available from every page, and a predictable layout and set of options that signal where on the site a user finds herself. There are three "levels" to the site (independent of actual position in the directory structure):

  • top-level or index pages:' entry pages for the WWP, WWO, and Exhibits portions of the site, these are essentially custom pages with specialized layouts but that nonetheless use the same header, footer, and navigation as the rest of the site
  • overview pages: these are entry pages for a specific section of the site, such as About or Outreach & Education; they provide a grid layout containing short "chunks" of descriptive content that lead to pages with more detailed information
  • reading pages: these are lower-level pages that contain the meat of the site --- documentation, project descriptions, information about subscribing, detailed information about our workshops, etc.

Each of these three types of page have a single layout they share with all other pages of the same type. All of these types of page have the same site navigation, header, and footer.

Note: There are a handful of custom page styles (for instance, the "gallery view" pages in the Teaching & Learning section of the site), but even these share their overall look and feel with other pages at the same level in the site hierarchy. In these cases, the page follows one of the three types above, and its custom layout/features are added by calling additional scripts or stylesheets.

DOCTYPEs, File types, and XML declarations

DOCTYPE

The default DOCTYPE for all WWP pages should be XHTML 1.0 strict: 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

The only exception should be pages that incorporate aspects of the W3C's "XHTML with RDFa" recommendation (i.e. pages that have embedded RDFa, like any page that uses the "gallery" function to display thumbnails in the right-hand margin). In those cases, the DOCTYPE should be declared as follows: 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">

This DOCTYPE should be used ONLY on pages that need to use embedded RDFa; for all other pages, use the standard XHTML 1.0 DOCTYPE.

File types

Most pages on our site are valid XHTML 1.0, and therefore could be identified with a ".xhtml" file extension. As a matter of course, however, we use ".html" for all pages that were created manually (or at least edited by a human) and reserve ".xhtml" for automatically generated pages (e.g. workshop slides produced with yaps).

Problems with XML declarations

Most modern browsers have no issue with the standard XML declaration in an XHTML document: 

<?xml version="1.0"?>

However, some versions of Internet Explorer choke or behave inconsistently when presented with an XML declaration, so it is probably a good idea to *omit the XML declaration from all pages intended for public viewing* on our site. (Yes, I know, XHTML documents are XML, and so we should be able to declare them as such... But since > 35% of our visitors still use IE, we don't really have much choice about it. Fortunately, the newly-released IE9 should make matters much, much better.)

Includes

To ensure consistency of major site features across all pages, we're using Server-Side Includes (SSI) to inject fixed pieces of content into a given page before it is delivered to the user's Web browser. All of our SSI files are stored in the utils/includes/ directory. Specific includes are listed below, with a brief description of their function:

  • banner.ssi: includes the WWP header (logo and title) and the top-level site navigation
  • header.ssi: like banner.ssi, but only includes the header (logo and title) -- not the top-level navigation; this is used currently for schedules and other materials related to WWP workshops and seminars
  • footer.ssi: includes the WWP footer, which includes our contact information as well as links to important pages, the CDS site, and the Brown University site
  • scripts.ssi: this includes references to JavaScript files that need to be available from every page on the site --- for instance, the main wwp.js script that controls behaviors such as the drop-down menus for the top-level navigation and the JQuery library file that it relies on; this file should NOT be used to include specialized scripts that are used on just a few pages, since this will load extra scripts unnecessarily, resulting in slower load times and degraded performance
  • styles.ssi: includes the main WWP stylesheet plus a handful of conditional statements that pull in other stylesheets for specific versions of Internet Explorer
  • area_navigation.ssi: inserts a new HTML <div> element into selected reading pages; this is empty, but gets filled in via an AJAX call to a separate PHP script that delivers a navigation pane with links to other pages in the same section of the site

Any page-specific stylesheets or JavaScript files should be called AFTER the scripts.ssi and styles.ssi are included.

JavaScript

The new site makes use of JavaScript for navigation and interaction; it also uses JavaScript extensively for selected visualizations that appear on some pages (such as the "featured" element on the main WWP entry page, the "gallery" feature used to assign thumbnail images to specific passages of text on some pages, etc.).

The JavaScript files that are needed to make global navigation and interactions work are inserted into each page using the banner.ssi server-side include (see above). At the moment, these include the following JavaScript files (located in utils/bin/javascript/):

  • jquery.1_4_2.min.js: minified version of the JQuery framework, used to simplify interaction, interface features, etc. This file is required for most other WWP scripts to work, so it's probably best to make sure it's always the first script listed in the include file
  • wwp.js: contains functions that all (or almost all) pages are likely to use

If new functions are developed that need to be available on ALL pages, they should probably be added to wwp.js; functions that are needed for specialized purposes on specific pages should be added to a separate .js file and added only to the pages to which they apply.

Specialized JavaScript files are also used for certain functions. At present, that includes:

  • upcoming.js: contains functions that grab upcoming events from the events.xml file
  • gallery.js: called from any page that makes use of the "gallery" function for displaying thumbnail images in the right-hand margin of a page; at present, this is used only the WWO "Orientations" page but may also be used in future in WWO Exhibits or other locations.
  • assorted jQuery plugins*: these are all located in the plugins/ directory (utils/bin/javascript/jquery/plugins/) and at present include
    • fancybox: a plugin for displaying modal popup windows, used primarily for displaying images (see http://fancybox.net/ for details; we're using version 1.3.1)
    • jQuery File Tree: used to generate the area navigation menu that appears in the left margin of reading pages (see http://abeautifulsite.net/blog/2008/03/jquery-file-tree/ for details)
    • TableSorter: used to create sortable tables for displaying things like lists of texts, syllabi browsing lists, etc. (see http://tablesorter.com/docs/; we're using version 2.0.3). TableSorter also includes some add-ons for extra functionality, specifically jquery.tablesorter.metadata.js and jquery.tablesorter.pager.js
    • jQuery UI: a set of user interface add-ons and enhancements for jQuery (see http://jqueryui.com/); used only for selected WWO Lab items at present
    • jQuery Tools: another user interface library for jQuery (see http://flowplayer.org/tools/index.html); not presently used but may be for some WWO Lab items

Within the utils/bin/javascript/ directory, there are also several folders containing JavaScript frameworks that we use for visualizations, interaction, etc. They include:

  • flot: contains the scripts for the JQuery Flot plugin, used for drawing graphs
  • jit: contains the scripts for the JavaScript InfoViz Toolkit; see here for details
  • jquery: contains the JQuery framework
  • protovis: contains the Protovis visualization framework; see here for details

PHP

We also use PHP for several small things, -primarily parsing simple XML files with the SimpleXML module and quickly generating JSON structures for use in some visualizations-. Because SimpleXML is not included in our installed PHP on papa (DOH!), we're foregoing its use for the time being. Syd has rewritten all of the PHP scripts that called SimpleXML and is instead using system calls to a XSLT processor to generate the necessary page content. The overhead for repeated system calls is quite high in some cases, but for the time being the system works. However, once we're fully migrated to teller/penn, we should probably re-write these scripts to use SimpleXML. We also use PHP to generate the area navigation displayed on reading pages. All PHP files are stored in utils/bin/php.

  • wwo_forthcoming.php: reads a simple xml file utils/xml/wwo.xml containing basic information about our progress on texts that are currently being encoded, as well as information on when new texts were published, and displays a sortable list of titles
  • wwo_recent.php: reads the same wwo.xml file and generates a list of texts added to WWO within the past year
  • jQueryFileTree.php: a connector script for the jQuery FileTree add-on (see JavaScript section above), used to translate the directory structure of a particular part of the site into a usable navigation menu; the script has been customized somewhat to exclude things like .svn directories, and to take the WWP's specialized <meta> tags into account
  • area-navigation.php: generates a simple list for navigation on reading pages; currently, it recursively reads the directory structure from the point of the page currently being viewed and excludes certain types of files; directories that should be excluded from the contents list output need to be added to the exclusion list manually [deprecated --- not currently in use, replaced by jQueryFileTree (see above)]

XML

Parts of the new WWP site --- for instance, the lists of new and forthcoming texts, as well as all of the WWP syllabi --- are constructed directly from XML files, -generally parsed with the PHP SimpleXML module- currently via PHP system calls to a XSLT processor that generates the appropriate page content/fragment. The following XML files live in utils/xml/:

  • quotography.xml: a list of short quotations from the WWO textbase, suitable for display as featured quotations on the main WWP page
  • syllabi.xml: a single file containing all the current WWP syllabi
  • wwo_forthcoming.xml: a single file containing a list of published and in-progress texts, used for generating lists of new and forthcoming texts
  • events.xml: a list of WWP events, in chronological order (this is important: newer events should appear at the end of the file)

CSS

All aspects of the layout and design are controlled via CSS. (One exception to this rule: some older versions of Internet Explorer require a few JavaScript tweaks to fix layout problems.) There is a single master CSS file, utils/stylesheets/wwp.css that contains most of the styles for the site. Where necessary, specific styles can be overridden for individual pages, and it is likely there will be separate stylesheets that introduce additional styles for Exhibits and WWO pages. For the time being, however, any styles that affect more than a single page should be added to the primary wwp.css file.

There is also a separate CSS file used in conjunction with the jquery Fancybox plugin (see above); it should only be linked to from pages that also include the Fancybox script --- in other words, pages that require modal popup functionality.

Special pages

Galleries

We currently use what we call a "gallery" to create pages that synchronize text with specific images (see this page for an example). When set up properly, the images will appear to the right of the passage of text that refers to them, or that they help illustrate or explain. When the user hovers over the image thumbnail with the cursor, the relevant passage in the text is highlighted. Clicking on an image will display a modal overlay with an enlarged version of the image and an optional caption.

To create a gallery page, use the "HTML with RDFa" DOCTYPE (see the section on DOCTYPEs above). You should also make sure to define the Dublin Core namespace and include a version, like so: 

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/terms/" version="XHTML+RDFa 1.0">

Include the following code just before the end of the HTML <head> element: 

<script type="text/javascript" src="../../../utils/bin/javascript/gallery.js"></script>
<script type="text/javascript" src="../../../utils/bin/javascript/jquery/plugins/fancybox/jquery.fancybox-1.3.1.js"></script>
<link rel="stylesheet" type="text/css" href="../../../utils/stylesheets/jquery.fancybox-1.3.1.css" />

To link a span of text to a particular image, enclose it in a <span> element that includes @property and @content attributes: 

<span property="dc:references" content="#image1">

The value of @property should be "dc:references" (the Dublin Core "references" term, used here because the span of text references the image, albeit indirectly). The value of @content is the identifier for the image thumbnal.

To add the gallery images, insert the following into the <div class="related"> element near the end of the main page content: 

<div class="gallery">
  <div id="image1" class="gallery-item">
    <a href="LOCATION OF FULL-SIZED IMAGE" title="THE CAPTION YOU WANT TO APPEAR WHEN THE IMAGE IS VIEWED">
	<img src="LOCATION OF THUMBNAIL IMAGE" alt="ALTERNATIVE TEXT IN CASE IMAGE FILE IS MISSING" />
    </a>
  </div>
  ...
</div>

Add as any <div class="gallery-item"> elements as you want---one for each image referenced from the main text. An id is required or the gallery will not function properly. Fill in capitalized text with the information relevant to your gallery page.

Known problems

  • Absence of SimpleXML on papa makes it harder to do very basic XML-related tasks (like generating lists of upcoming events); Syd has created workarounds for this, but we should revise/revisit them once we have our new penn/teller server environment
  • The Windows Phone 7 version of Internet Explorer doesn't handle content inserted via AJAX requests (usually it will just display a blank page). There may be workarounds to this problem, but I haven't spent much time looking at them yet. 
  • Visualizations in the WWO Lab section do not work in Internet Explorer (either mobile or desktop versions); at present, we work around this by displaying a warning message to users telling them their browser isn't supported. All of the visualizations should work properly in IE9, but because some of the visualization frameworks haven't been updated to let IE9 pass browser detection tests, they fail unnecessarily. Once the visualization frameworks are updated, we should revise the Lab section to allow IE9 users to view everything.

Mobile

In general, recent smartphone browsers handle the site quite well (setting aside some very minor layout/rendering issues that don't really hinder usability). So-called "gallery" pages are one exception to this: the main page content is fine, but the gallery images either don't appear in the right margin, or they appear but are not selectable by the user (so you can't view them at a larger size); neither is really a huge problem.

I haven't done extensive testing of smartphone browser quirks. I do know that the mobile Safari included in iOS 3 appears to work reasonably well. IE for Windows Phone 7 (pre-"NoDo" update) works fine, with the exception of a gallery image display bug and the inability to display AJAX-included content at all). However, further testing is in order before we advertise mobile browser compatability.


The old WWP web site (prior to Fall 2010)

The WWP web site is the HTML portion of the WWP online presence, including all of the information about the project, the textbase, licensing, activities, and so forth, but not including the textbase itself.

The WWP web site is published from papa.services.brown.edu, and a development version of the site is maintained on golf.services.brown.edu. Both are under subversion control. Under normal circumstances the two are kept synchronized.

The WWP site is divided into three areas, represented by three main directories:

1. Texts: This area contains information about the texts themselves, including text lists, information about the textbase and how to license it, information about textbase development, etc.

2. About: This area contains information about the WWP, including its staff, current projects, history, etc.

3. Encoding: This area contains information about the WWP's encoding activities, including documentation, workshops and seminars, the WWP Guide, and related materials.

Retrieved from "https://dsg.northeastern.edu/wiki/index.php?title=WWPWeb&oldid=2652"