Creating Templates
Prev   Next

Creating Templates

SportPage templates are implemented in the Jakarta Velocity template system; before you read this section, you should read the Velocity User Guide to better understand the terminology and the Velocity VTL syntax.

SportPage uses Velocity variables to define page components common to most webpage design. By defining an overall layout and the placement of the header, menu, content page and sidebars within it, the website achieves the necessary consistency for good design while preserving and conserving (expensive) designer effort. As will be explained later, SportPage allows the designer to swap in different components depending on the context of the request, for example to give different topic areas context-specific menus, sidebars or content page layout.

The first important question about templates is “where do I put them?” The factual answer is “SportPage doesn't care.” When templates are requested, Velocity is told to search the comma-delimited paths listed in the templates.home configuration variable. In practice, it is a good idea to keep templates outside of the webserver DOCUMENT_ROOT tree, but designers may choose to keep them here so their testing of pages will function correctly loading the templates as static webpages in their HTML editor.

[Important]Rule #1: Software Should Serve People

It is important that software serve the people who use it, not the other way around. It is more important to satisfy the process requirements of the website designers than to satisfy server or security ideals and it is best to consider the entire gestalt of the software ecology. Engineering is about solving problems, not imposing new ones.

If your normal Apache webpages will be at /sites/cbc.ca/docs/olympics, there's a trade-off here as to whether or not you want anyone (developers included) to be able to view the raw templates outside of the servlet. One argument goes that you don't want these pages inside /sites/cbc.ca/docs because robots might accidentally index them; I don't think it matters much.

[Caution]Caution

If you put the templates outside of the server document tree (e.g. in /sites/cbc.ca/templates/olympics) the Tomcat and Apache servers won't be able to access them. The problem for designers will be that the templates and the images they use will be in different places because the images must be accessible to either tomcat or apache.

[Note]Servlets, Apache and Static Content

By default, and this varies from platform to platform, Apache will not allow servlets to serve static HTML content, specifically URI requests ending in .html. This is a problem if your templates or your default content (extra path information) ends with that suffix: This is one very strong technical reason why all internal links should never include these extensions. Unfortunately, the Apache server does not impose this same rule on static images: To accommodate this, SportPage is equipped to handle *.gif and *.jpg files found relative to the servlet home

      #include ("bio/header.html")

would mean the template at /sites/cbc.ca/olympics/bio/header.vm whereas

      <a href="bio/bio.html"><img src="bio/bio.gif"></a>

expects to find the servlet-home relative file path /sites/cbc.ca/site/webapps/template/bio/bio.gif but will create a link that will return the Apache DOCUMENT_ROOT relative file /sites/cbc.ca/site/docs/bio/bio.html

What works for me is keeping images and templates in different places. Instead of an image url like /olympics/gfx, I'd use /gfx/olympics so the tomcat is only asked to deliver templates when people ask for http://cbc.ca/olympics; all images are specified as /gfx/... and no images are specified as /olympics/.... This avoids a raft of problems, and distributes the load so Apache (or khttpd) handles static content while tomcat does its tomcat stuff.

Second, I would keep the templates outside of the servlet home directory because that lets us upgrade the Olympics software in the easiest and least dangerous way: we just delete it, wiping it clean, and unpack the new kit.

This may be counter-intuitive to those accustomed to using static pages, but I find that it only makes sense to bundle pages with the software when the software and the pages are both done by the same people. It reinforces the division “this is logic, and that is presentation”

Thus, I'd probably ask to put my templates under directories like /sites/cbc.ca/templates/olympics/bio and encourage others to use paths like /sites/cbc.ca/templates/sports/hockey.

It's largely a personal choice of what is most convenient for everyone involved; SportPage doesn't care. You could, if you want, insist that upgrading software is done by unpacking the new software over top of any previous install (manually running jar xf olympics.jar) and keep all your templates under the one and only application root path /sites/cbc.ca/docs/olympics so everything is in one place.

In the CBC sites, we copy the same basic webpage component design you see everywhere: Header at the top, menu down the left side, main content covering the rest though sometimes losing it's right margin to a sidebar.

In SportPage, these appear in the configuration file as the first of the default.* dot-variables. Dot-variables are so important, they have been badly named; more about them later, but for now, you'll see that the configuration file (WEB-INF/sportpage.conf) lists these components as assigned to filename paths such as /default/layout.vm.

[Note]Note

All page component filenames and directory paths are completely arbitrary. There is no reason why you couldn't assign these layout components to file paths divided by developer (default.layout=/jones/crusher.vm) or any other structure; all that matters is that the default set define template filenames, and that those files exist and are readable by the server before the SportPage system is started.

Also note that only the default.layout variable name is required All the other page component names can be anything you wish, in any language (supported by the file-system) providing the variable names match the names used in the default layout file. For example, you could define default.centerstage=/sponsor/molsons.html and then place #parse( $centerstage ) into the center of your main content area.

SportPage uses a customized VelocityEngineTemplate which allows SportPage to co-exist on servers running other Velocity-based applications. As such, SportPage maintains its own velocity template library; the path to this library is specified in the vtl.macro.lib parameter in the WEB-INF/sportpage.conf configuration file.

[Warning]Warning

Velocity macros are not reloaded when the template pages change (they can be, but it's too expensive to be practical). Do not include in-line or library macros until you are certain they work; changes to these macros will require a servlet container restart.

Prev Up Next
Installing SportPage Home Topics, Contexts and Template Dot-vars