XSLT 2.0 Web Development: Elements of a Web Site
River and bridge and street and square
Lay mine, as much at my beck and call,
Through the live translucent bath of air,
As the sights in a magic crystal ball.
Robert Browning, Old Pictures in Florence
This chapter is a practical complement for Chapter 2, "The source definition." Having discussed the ins and outs of building a comprehensive and useful source definition, we'll now look at how these rules can be applied to real-world source XML documents of a typical web site.
I cannot claim to cover everything: Your web site may well contain unique elements that won't fit common schemes. Here, only the most general and frequently used constructs are covered, and the approaches described in this chapter may not be optimal for all situations. Many examples are given, but rather than copy them over, try to use the reasoning behind these examples to analyze your own constraints and requirements.
The first part of the chapter deals with markup constructs commonly used in page documents, including headings, paragraphs and paragraph-like elements, links, images and other non-XML objects, tables, and forms. Then we will analyze the master document (3.9) to find out what data it needs to store and what is the best XML representation for this data. The last section (3.10) presents complete summary examples of a page document, a master document, and a Schematron schema to validate them.
3.1 Page documents: top-level structures
In this and subsequent sections, we look at the informational core of a web page, stored in its own source document (page document). Peripheral components such as navigation, parameters of the site environment, and metadata are stored in the master document, the subject of 3.9.
3.1.1 Page metadata
Every XML document has a root element, and since we're talking about page documents here, there's no reason not to call this element page. Its attributes and children are the natural place to store the page's metadata.
In addition to its primary content, each page document includes certain metadata. Some of it may end up as a visible part of the web page, some may be hidden in HTML metadata constructs (keywords and descriptions in meta elements), some may be used during transformation but not included in the resulting HTML code, and some may not be used at all except for reference or source annotation purposes. Common examples of metadata include page creation date, change log, author(s) and editor(s), copyright and licensing information, and the language of the page.
Note that only information specific to this particular page must be stored in it; if some metadata bits are shared by more than one page, their proper place is in the master document (3.9) and not in any of the page documents.
Page ID. The most important piece of metadata is the page's unique
identifier used to resolve internal links (3.5.3). However, we cannot store
this identifier in the page itself, or we'll have a catch-22 situation:
We can get from the id to the page location, but to obtain
the id we must access the page - that is, we must already know
its location. Because of this, the proper place for the ids
of all pages is in the site's master document.
Page coordinates.The same applies to the information on the position occupied by this page in the site's hierarchy. As we'll see later (18.104.22.168), the branch of the site's tree that this page is a leaf of is most naturally deduced from the site directory in the master document. Duplicating this information in the page document itself is unnecessary and prone to errors.
Everything else.Any other page metadata is normally stored in the page document. Simple values can be stored in attributes of the page's root element. More complex constructs that require their own elements can be placed either directly under the root or inside an umbrella parent element (e.g., metadata) that is a child of the root element.
Existing vocabularies. RDF (
3.1.2 Sections and blocks
You'll likely need some intermediate structural layers between the root element, page, and text markup constructs such as paragraphs and headings.
Sections or blocks? The traditional document hierarchy - sections, subsections, subsubsections, and so on - is not often seen on the Web. Instead, information is more commonly broken into relatively small blocks with few or no hierarchical relations between them. Different sites may call these blocks "stories," "blurbs," "columns," "modules," "writeups," and myriad other names.
Among these names, one which appears to be the most intuitive is the one you should use for your block construct's element type name. Contentwise, a block is a unit with mostly fixed structure that may include both obligatory (e.g., heading and body) and optional (e.g., icon, heading links, author byline) components in both parallel and sequential (2.3.7) arrangements. Here's an example:
<block id="unique" icon="block_icon" type="story"> <head link="address">Block heading</head> <subhead>Optional block subheading</subhead> <p>And here goes a paragraph of text.</p> <p>Possibly one more paragraph.</p> <author>An optional author byline</author> </block>
Block types. It is likely that you will have more than one type of block construct - for example, front page news blocks, subpage body blocks, and ad blocks. In the simplest case, everything on the page can be treated as one big block, so the page's root element can be considered the root element of a block.
Different types of blocks will likely have many common structural features - in part because they all belong to one site with its common information architecture and visual design. Only if different types of blocks have clearly distinct structures can you use different element types for them; otherwise it is best to use the same generic element type (e.g., block) with different values of the type attribute. This provides two major benefits:
Your validation code will be simpler to write and maintain.
Management of orthogonal content (22.214.171.124) will be much easier to implement - for example, you may be able to reuse blocks from regular pages as orthogonals on other pages, or turn documents storing orthogonal content into regular pages.
In general, analogous but different structures should only differ by a minimum number of obvious features; avoid random, meaningless differences.