Index

Introduction to Latemp

Top

Latemp is a content management system (CMS) for static HTML pages, based on Website Meta Language (http://thewml.org/). If you are not already familiar with Website Meta Language (from now on - WML), please familiarize yourself with it.

There are two ways to start working with Latemp. The first is to start an entirely new site. That's what the command latemp-setup is for. Just type latemp-setup -man and follow the instructions. The second is to convert an existing WML-based site to Latemp. This is a matter of integrating the relevant code snippets, makefile excerpets and build logic from an existing Latemp project.

This document provides a reference to all the Latemp directives.

Overview of a Standard Latemp Workspace

Top

This section will provide an overview of a standard latemp workspace. To understand what is going here, invoke the following command:

    latemp-setup --theme=better-scm --dir=my-project \
        --remote-path=/tmp/my-project-dest

This will create a sample, mostly empty but still functional, Latemp project in the my-project sub-directory of the current directory. You can build it by cding to this directory and invoking the following commands:

    ./gen-helpers.pl
    make

Now, let's overview the files there:

gen-helpers.pl

This file searches for source files that should be used to generate the site's contents, and the files include.mak and rules.mak that will be included in the makefile. It uses the auxiliary module HTML::Latemp::GenMakeHelpers by default, but can be modified to have a different logic, but with common results.

The most important modification that one can do to it is to add another host, or rename an existing ones. To do that, just manipulate the following line:

    (qw(common mysite))

And add or remove hosts. Note that you should always keep the common meta-host.

This file should be run whenever files or directories are added or removed from the working copy.

Makefile

This file contains the makefile used to build the project. It can be modified as long as it includes include.mak and rules.mak and calls their latemp_target template.

lib/MyNavData.pm

This file contains the definition for the navigation menu and site-flow. Latemp makes use of HTML::Widgets::NavMenu for this, and this module serves as an input to it. Read the online documentation of HTML::Widgets::NavMenu for more information how to edit this file.

This is a module that is used to generate the HTML navigation links ("Previous", "Up" and "Next"). It can be customized by the user to create more sophisticated rendering of them. It should be noted that generating navigation links in the <head> tag is not dependent on this.

unchanged

This is an empty file that is used to control the creation of directories inside the destination folder.

template.wml

This is the Web Meta Language template that is used to control the site-wide preferences. It includes the header "latemp/latemp-main.wml" which brings in the Latemp logic.

Before and after it one can write other WML directives to control the page generation.

src/common

This sub-directory contains files that are common to all the hosts on which your site is spread. Generally, it should contain CSS stylesheets, images that serve as backgrounds, buttons, logos, and so forth.

src/mysite

This sub-directory contains files that are generated for the host "mysite". If the file ends with the .html.wml extension it will be pre-processed using the wml WML processor. Else, it will be copied verbatim.

Overview of Latemp-Related Directives

Top

This section provides an overview of the Latemp-related directives that the Latemp-deployer can make use of.

Latemp mp4h tags.

<latemp_lang "en-US" />

This tag specifies the language as present in the <html> tag lang and xml:lang attributes.

<latemp_encoding "utf-8" />

This tag controls the encoding of the page.

<latemp_subject "My Subject" />

This directive sets the subject of the page. Generally the subject appears within the <title> tag within the HTML <head> and possibly also the first <h1> tag.

<latemp_common_keywords "Keyword 1, other keyword" />

This directive sets site-wide keywords to be mentioned in the <meta name="keywords" /> tag of the HTML head tag.

<latemp_more_keywords "Foo, Bar" />

This sets additional (usually page specific keywords).

<latemp_version_control_id "$Id" />

This sets a version control ID (such as CVS' or Subversion's $Id$ string) to be used to identify the timestamp of the page.

<latemp_author "Jonh Smith" />

This sets the name of the author within the head tag.

<latemp_webmaster>...</latemp_webmaster>

This sets an HTML portion to identify the webmaster of the site. Note that this directive captures what comes between its start and end tags.

<latemp_license>...</latemp_license>

A License information for the page.

<latemp_affiliations_buttons>...</latemp_affiliations_buttons>

This sets out HTML code for various affiliations links that the site maintainer would like to see in the side-bar.

<latemp_top_left_corner_logo>...<latemp_top_left_corner_logo>

An HTML for a Logo to come at the side bar, right before the navigation menu.

<latemp_meta_desc "My description" />

A description to put inside the appropriate <meta /> tag.

<latemp_extra_head_elements>...</latemp_extra_head_elements>

More HTML to put between the opening and closing <head> tags.

<latemp_foot_image>.../<latemp_foot_image>

This sets the HTML for the image in the footer, which is typically the last thing displayed on the page. Use it to define a bottom "Back to my Homepage" or "Hosted at MyHosting" footer.

<latemp_news_get_news_box_contents />

This retrieves the HTML of a news box. The news box contains one HTML <li> tag for each news item, with summaries and links. See "News Management" below.

<latemp_news_get_news_page_entries />

This retrieves the HTML of the entries for display in the news page. See "News Management below".

Variables with special meaning

<set-var latemp_theme="better-scm" />

This variable specifies the theme to be used by Latemp. If it isn't specified the theme defaults to the value of the $(LATEMP_THEME) pre-processor macro.

<set-var latemp_filename="docs/index.html" />

This variable specifies the path of the file relative to the server's root. If it is not specified, it defaults to $(LATEMP_FILENAME).

<set-var latemp_server="myhost" />

This variable specifies the server of the current file for input to HTML::Widgets::NavMenu. If not specified, it defaults to $(LATEMP_SERVER).

<set-var latemp_with_favicon="1" />

The latemp_with_favicon controls whether a link tag to a favicon should be placed in the HTML head tag.

<set-var latemp_with_breadcrumbs_trail="1" />

This variable controls whether a breadcrumbs trail (e.g: "Home -> Software -> Games -> Freecell") should be displayed at the top of the page.

<set-var latemp_with_head_meta_tags="1" />

This variable controls whether the "author", "description" and "keywords" <meta /> tags should be inserted into the HTML head.

<set-var latemp_nav_links_allowed_places="top-left bottom-left" />

This should give a whitespace-separated list of places to render the HTML visual navigation links in. Currently available positions are:

top-left
Right below the logo and above the navigation menu (in the side bar).
bottom-left
In the bottom of the side bar.

<set-var latemp_with_timestamp="1" />

This specifies that the timestamp for the page should be rendered.

<set-var latemp_supress_default_h1="1" />

This directive causes the default <h1> tag with the contents of the subject not to be displayed.

<set-var latemp_screen_stylesheet_url="http://www.myhost.foo/style.css" />

If set, overrides the standard stylesheet URL as placed in the HTML head tag.

<set-var latemp_print_stylesheet_url="http://www.myhost.foo/print.css" />

If set, overrides the URL of the print stylesheet.

<set-var latemp_with_xml_declaration="1" />

If set, includes an XML declaration:

    <?xml version="1.0" encoding="utf-8" ?>

at the beginning of the document.

<set-var latemp_html_standard="xhtml11" />

Sets the default HTML standard to be declared in the DOCTYPE. Valid options are: "xhtml1.0-trans", "xhtml1.0-strict" and "xhtml1.1". The DOCTYPE defaults to XHTML 1.1 Transitional if this variable is not specified.

<set-var latemp_navmenu_object_class="My::NavMenu" />

Sets the class and module for the navigation menu. Defaults to the standard "HTML::Widgets::NavMenu".

<set-var latemp_gen_plain_page="1" />

If set, will generate a page with only the body of the page, and not with a sidebar, footer, breadcrumbs trail, etc. Useful for generating a version for printing.

Tags to be defined by the user:

<define-tag latemp_timestamp_wrapper endtag="required">...</define-tag>

%body contains the version control ID as passed from <latemp_version_control_id /> and this wraps it in a display for the user.

IPP Preprocessor Macros

$(LATEMP_THEME)

This specifies the default theme to be used if the latemp_theme variable is not specified.

$(LATEMP_FILENAME)

This specifies the default filename of the file relative to the root directory of the host to be used if the latemp_filename variable is not specified.

$(LATEMP_SERVER)

This specifies the default server to be used if the latemp_server variable is not set.

$(ROOT)

This variable gives a path to the root directory of the current server. It can be used to construct relative links.

News Management

Top

To manage news one populates the @news_items array in the file lib/MyManageNews.pm in your distribution. Generall the fields 'author' and 'category' will be common to all the items. (If not - specify them explicitly in every item). Other items are specified in the HTML::Latemp::News man page. An example news item is brought here:

        {
            'title' => "Changes of 18-April-2005",
            'id' => "changes-2005-04-18",
            'description' => q{Around 18 April, 2005, Jane's Site has seen a 
                lot of changes. Click the link for details on them.},
            'date' => "2005-04-18",
            'author' => "Jane Smith",
            'category' => "Jane's Site",
        },

This will propogate the news into the navigation menu, etc. See the news-related tags above for embedding news related content into your pages.

If you want to build an RSS feed, you should add the news_feeds target to the dummy-invoked targets in the makefile.