UD Web Modules
Design Concepts and Usage Jeffrey Frey, NSS
Often when designing a web site the additional resources needed by pages are stored in sub-directories named according to resource type. Consider the following directory listing
[frey@copland]$ ls -l total 8 drwxr-xr-x 2 frey staff 68B Sep 17 23:32 css drwxr-xr-x 2 frey staff 68B Sep 17 23:32 images -rw-r--r-- 1 frey staff 174B Sep 17 23:31 index.html drwxr-xr-x 2 frey staff 68B Sep 17 23:32 js drwxr-xr-x 2 frey staff 68B Sep 17 23:32 xml
This directory contains the ubiquitous images directory for all JPEG, GIF, PNG, et al. graphic resources used by index.html. The other directories group the following resource types:
  • css: cascading-style sheets
  • js: Javascript code
  • xml: XML documents (e.g. for AJAX applications)
The drawback to this organizational method is that as more pages are added to this directory, more files get added to the resource directories. There are several issues associated with the communal directory approach:
  1. Dependencies are difficult to isolate. With all graphics in the images directory, which page(s) or parts of page(s) make use of them?
  2. Files can be more-easily accidentally overwritten. A new page added to the directory may also use a graphic named header.png which, when uploaded, yields an unwanted (and unforeseen) alteration to other pages which used the previous header.png.
The UD Web Modules project seeks to apply the same taxonomical structuring of resources, but at the level of individual components of web pages.
The Anatomy of a Module
Let's examine a representative Web Module:
[frey@copland]$ cd /www/htdocs/modules/blueheader-930px [frey@copland]$ ls -l total 8 drwxrwsr-x 2 db 0798 512 Sep 3 09:28 css drwxrwsr-x 2 db 0798 512 Sep 9 16:55 html drwxrwsr-x 2 db 0798 512 Sep 4 13:45 images lrwxrwxrwx 1 db 0798 18 Sep 4 09:51 js -> ../header-930px/js [frey@copland]$ $ ls -l css total 8 -rw-rw-r-- 1 db 0798 3105 Sep 8 10:08 header.css
Modules live in the /www/htdocs/modules directory available to UD users with accounts on copland; module resources are visible on the web at URIs starting with /modules. For example, the single CSS resource in the blueheader-930px module would have the URI:
/modules/header-930px/css/header.css
which a web developer would reference on a web page using a <link> element in the page's <head> section:
<link rel="stylesheet" type="text/css" href="/modules/header-930px/css/header.css" />
HTML Resources
The contents of html resource directories are meant to be included on web pages by means of the Apache server-side include mechanism. Specially-written HTML comments (an SSI directive) inserted in a web page cause the web server to replace the comment with the contents of another file in /www/htdocs.
For example, the 930-pixel header includes a fragment of HTML in /www/htdocs/modules/blueheader-930px/html/header.html that must be added at the top of the <body> element of a page. The SSI directive is
<!--#include virtual="/modules/blueheader-930px/html/header.html" -->
The directive tells the web server to remove this comment when it sends the document to a web browser and replace it with the contents of the file it finds at the path specified in the virtual attribute. Note that the virtual attribute does not take a URL — the value is not /modules/header-930px/html/header.html.
When looking at the modules available in /www/htdocs/modules, make note of the items in html subdirectories; they should be inserted at specific locations in pages using SSI directives. See the per-module documentation for in-depth descriptions of the html components of the modules and where they should be inserted in an HTML page.
The HTML templates being made available by OCM/IT make use of UD Web Modules and have been constructed with the appropriate SSI directives to insert the appropriate header, content, and footer html components. Web designers are encouraged to consult these templates for examples of appropriate SSI directives.
It is equally important to note that many of the html components are made available in a form which will allow them to be easily internationalized in the future. An internationalized resource is named with suffixes like .en, .fr, .de for specific language codes; a default resource for unmatched languages is named with a double-extension like .html.html.