IapetosBase Tags
The Base Tags provide a series of generally useful, server-expanded tags that greatly cleanup the process of writing web pages. By using the base family of tags the page author gets certain specific benefits:
- Significant readability improvement in the final HTML.
- Insulation from change in the underlying html standards.
- Automatic inclusion of window frame and decorations.
- Certain browser compensations.
- Integration with build-time tools.
Conventions
The Iapetos/cms system has some expectations about how the file system that holds the pages of the website is organized. In general the expectation is that the tool is used to build large sites, or sites where the author expects the site to become large over time. In order to manage that complexity the site is broken down into various logical parts, and there is a direct mapping from the file system to the menu structure. Banner tabs and left menus are thus mapping to specific levels in the file system structure.
Each article in the website is a collection of files that are located in a directory and the primary article content is placed in a file named index.html. Any other parts for the article, as well as contributions for the surrounding page, are placed in other files in the same directory. This convention works well with the Apache system which automatically displays index.html files when a directory is accessed.
Build Tools
There are a series of tools which scan the website when it is deployed to the web server. These tools can run either in the build environment or on the server depending on how the build environment is set up. These tools provide site-wide information, such as the next-previous links, index to scripture references, the indexes used for website search and so on. Some of the base: tags provide access to the values that are generated by these tools.
Current Tools:
- all.py generates an exhaustive list of all of the index.html files in a given website. This provides the list of articles that are candidates for the other tools.
- np.py generates the next and previous links for each page on the site. These links form a complete circle, and are designed to provide the read-through order for the website for a visitor who wants to read the site as a book.
- isr.py generates the index to scripture references.
- indexer.py uses Lucene to create a searchable index for all articles on the website.
- bible_convert.py takes .ibf formatted bibles and generates loadable python modules that are used in bible quotes.
- yuicompressor takes .js and .css files and generates compressed versions of the same. The tool is a wrapper around the Yahoo tool by the same name.
General Layout
Before diving into specific tags it helps to think about the general layout of an Iapetos/cms web page. In general a few simple tags at the top and bottom of a web page replace potentially hundreds of raw html tags. Most pages written with Iapetos/cms thus have a consistent structure. The following example shows off that structure.
<base:html> <base:svn id="$Id: index.html 7986 2009-05-03 17:45:26Z phil $"/> <base:head/> <base:body> <h1>Hello World</h1> <p>Hello World!</p> <base:byline nick="phil"/> </base:body> </base:html>
The <base:html> tag replaces the raw <html> tag for the page. It will expand to the raw html tag and provide the standard boiler plate that goes with the html.
The <base:head> tag replaces the raw <head> tag and also generates all the typical content that goes inside the head tag. The <base:head> tag has 2 forms and can be used to supply additional head tag content when needed.
The <base:body> tag replaces the raw <body> tag. Not only does it generate the standard <body> tag, it also searches for and includes any additional files that make up the menus and borders around the outside of a typical page. It also provides browser compensations for minimum page size on IE browsers.
The content of the page is supplied inside the <base:body> and generally is made up of HTML that will be sent to the browser. There are additional base: tags that are available for specific purposes that can be used inside the body of the page.
Comments
Since Iapetos/cms is built using mod_python and python server pages, the standard commenting structure for these pages is available. To provide a comment that is stripped in the server, use <%-- and --%> to surround the comment.
Because of the way header processing works, comments should come after the opening <base:html> tag.
<base:html> <%-- This comment will be stripped in the server before the page is sent to the browser. This is a typical way to include hidden comments, such as license text, which should not be included when the page has been rendered for display in the browser. --%> <base:svn id="$Id: "/> <base:head/> <base:body> <h1>Hello World</h1> <p>Hello World!</p> <base:byline nick="phil"/> </base:body> </base:html>
Standard Tags
What follows is an alphabetical list of the available <base: tag set.
There is also a <bible: tag set for displaying various types of Bible quotes.
<base:body> and </base:body>
This tag provides a replacement for the standard <body> tags. The Iapetos/cms form provides considerable additional support in terms of merging together the various files that make up the page decorations that surround the content of the page.
The opening form of the tag includes top.html for the top banner(s), left.html for left banner(s), and header.html for page header(s).
The closing form of the tag includes footer.html for any standard page footer, right.html for any right banner(s), and finally bottom.html for any bottom banner.
Each of these files is merged in a cascade down the path to and including the directory where the current article is found.
Typical Use:
<base:html> <base:svn id="$Id: index.html 7986 2009-05-03 17:45:26Z phil $"/> <base:head/> <base:body> <h1>Hello World</h1> <p>Hello World!</p> <base:byline nick="phil"/> </base:body> </base:html>
<base:date/>
This tag prints the revision date for this page.
This tag can be used anywhere in the body of the page.
<base:home/>
Generally when using Iapetos/cms there is no article at the root of the directory tree. The path to the article provides the triggers for menu selection and the root location has no such clues.
When a visitor to the site enters the URL for the site alone, with no path, there is a stub index.html file that will service that request as though it were the home page which is typically the first page in the next-previous link system.
That stub page contains one tag: <base:home/>
The tag itself finds the first page in the next-previous link system, internally pretends the path is the path of that page, and then displays the content of that page at the root of the website, with correct menu activation.
<base:home/>
<base:html> and </base:html>
This pair of tags surrounds the content of the page.
The opening form of the tag generates the DOCTYPE tag as well as an expanded form of the html opening tag.
Typical Use:
<base:html> <base:svn id="$Id: index.html 7986 2009-05-03 17:45:26Z phil $"/> <base:head/> <base:body> <h1>Hello World</h1> <p>Hello World!</p> <base:byline nick="phil"/> </base:body> </base:html>
<base:svn/>
The base:svn tag provides information from the page source into the running Iapetos/cms system. The parameters are typically substituted from values supplied by the svn version control system. A <base:cvs/> tag is for use in cvs systems.
The location of the tag is important, it is typically placed between the <base:html> tag and the <base:head/> tag. This allows values from this tag to show up later on the page.
There are a variety of parameters, but the most common is id. This parm is passed the standard $Id: index.html 7986 2009-05-03 17:45:26Z phil $ value as substituted by svn. When the id parameter is used no other parameters are needed, as the values are compactly provided there.
- id is the svn id string for this page.
- revision is the revision number for the page.
- date is the revision date for the page.
- license is the license for the page.
Typical Use:
<base:html> <base:svn id="$Id: index.html 7986 2009-05-03 17:45:26Z phil $"/> <base:head/> <base:body> <h1>Hello World</h1> <p>Hello World!</p> <base:byline nick="phil"/> </base:body> </base:html>
<base:revision/>
The revision tag displays the revision value passed in on the <base:svn/> tag.
It can be used anywhere in the body of the page.
<base:img/>
This tag wraps the standard html <img/>> tag and provides expansion for the src="" attribute. In general static content like images is served up through a separate static domain. To keep the html clean, the library provides that expansion.
<base:a/>
This tag wraps the standard html <a/> and provides a set of expansions for the standard tag.
site="" is added and can be the project name of an affiliated website. This allows link checking in the build tools for cross-site links to the supplied site without having to test the site with a url fetch.
This attribute also causes live links on a test version of the site to link to test versions of the linked site.
This value can also optionally be the word "static" for items linking to the static site. This is used for downloads, where the payload is coming from the static domain.
port="" is the port number for the link. This value, if supplied at all, is added to the domain of the site indicated in the link. It is supplied separately because many combinations of href="" values are dynamically constructed and when that happens this parameter supplies the port if needed.
formdata="" is an attribute that is formatted like the keyword parameters on a url. An example would be formdata="a=1&b=2". The keys in these key=value pairs are first checked against the running page form values and if found those values are used on the href="" form. If not, then the value supplied on the value side of the key=value pair is used as a default. When this tag is processed in the server these pairs are added to the end of the href="" parameter for transmission to the browser.
Values that should not pass through this processing should be supplied statically in the href="" parameter itself.
href="" parm is the standard href="" parm for the <a> tag. There are several modifications that the base:a tag will apply in processing.
If there is no domain, which is marked by the http:// prefix, then the site="" attribute if supplied will be used to infer the complete domain. In this form the site supplied by site="" may be a production site when on production servers, or a local development site when in debug mode.
If there is no site="" and no http:// at the front then the path is assumed to be local to the current site and it must start with a '/'. Build time link checking is performed on all paths in the href="" parm when it is not off-site. Build time checking of off-site links for stale links is possible, but slows the build process.
For internal links, links to pages on the local website or to sites known to the sites="" parameter, the base:a tag will also apply any url titles that are needed to fully expand the href's path. This allows pages to have search friendly links while at the same time not requiring hard to handle file names. See the <base:url/> tag for details.
All other attributes supplied to the <base:a tag are passed through to the browser unchanged.
<base:url/>
This tag is supplied in the header to a page and provides modifiers to the page for handling by the build and runtime tools.
title="" is an attribute that provides a url title for the page. This title is appended to the page for all links in menus and through <base:a> tags.
These titles are considered part of the page path when referenced externally to the website, but are not part of the file system path used to locate the file. These titles should be long and descriptive in typical blog style so that search engines can find the page easily.
<base:was/>
This tag is usually supplied in the header of the page and identifies locations where this page was located previously. It is read by the build tools which uses the supplied parameters to generate entries in the mapping tables.
site="" is provided when the location was on a different site. It must be one of the known affiliated project's sites in order to generate a proper remap. When not supplied the current site is assumed.
path="" is the path where the page was in the past. When not supplied the current path to the page is assumed.
title="" is the url title where the page was in the past. When not supplied no title is assumed.
This tag can occur many times and each occurrence identifies a single location where the page was previously located. Each occurrence supplies a single remap to the remap tables.
These parameters provide a powerful and simple set of tools for handling page movement. By placing the data on the page the complexity is significantly reduced.