Hypermail Documentation

# Customizing Hypermail Pages

Contents:

- Hypermail Pages

- Definitions

- Choosing the Default Look of Your Pages
  - Standard Page HTML
    - Index Page Headers
    - Message Pages
    - Page Footer
  - Table Menu Display

- Using Template Files to Customize Your Pages
  - Substitution Cookies
  - Specifying template file locations
    - Using Environment Variables
    - Using Configuration File Entries
    - Examples
  - Message Pages

- Including Reference Links
- In-lining Images
- Changing The HTML File Suffix

## Hypermail Pages

You can customize hypermail generated pages to suit your local web site needs as well as the needs of the list. Hypermail generates three types of files:

- HTML index pages,
- HTML message pages,
- MIME enclosure attactment files.

The attachment files are a copy of the attachment the user included and are not altered.

This version of hypermail allows you to customize both index and message pages separately as described below.

## Definitions

In the examples below, the following terms are used.

label - the label passed in via the command line or specified in the list configuration file.

indextype - depends on the type of index being presented. It could be By Author, By Date, By Subject, or By Thread.

mailto-address - the MAILTO value compiled into hypermail, specified in the environment with the HM_MAILTO variable, or specified in the hm_mailto variable in the list specific configuration file.

subject-of-message - the contents of the message's RFC 2822 Subject: header.

HMURL - Used to contain a link to the Hypermail Development Center. Defined in hypermail.h.

PROGNAME - contains the name of the executable. Defined in hypermail.h.

VERSION - contains the version of the software that generated the page this appears on. Defined in src/hypermail.h.

## Choosing the Default Look of Your Pages

There is no need to customize hypermail pages unless you have a specific need. There are two different default page layouts provided with hypermail, the Table Menu Display and the Standard Display.

### Standard Page HTML

If you are not using the HTML template files described below then Hypermail generates headers and footers that look similar to the following. Note that you can substitute a <BODY> statement by either defining BODY in options.h or by using the hm_body variable in a list specific configuration file.

#### Index Page Headers

The default Index page headers used in hypermail look like:

> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
> <HTML>
> <HEAD>
> <TITLE>label: indextype</TITLE>
> <LINK REV="made" HREF="mailto:mailto-address">
> <HEAD>
> <BODY BGCOLOR="#ffffff" TEXT="#000000">
> <H1 ALIGN=CENTER>label<BR>By indextype</H1>
> <HR WIDTH=400>

#### Message Pages

The default Message page headers used in hypermail look like:

> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
> <HTML>
> <HEAD>
> <TITLE>label: subject-of-message</TITLE>
> <LINK REV="made" HREF="mailto:mailto-address">
> <HEAD>
> <BODY BGCOLOR="#ffffff" TEXT="#000000"> <H1 ALIGN=CENTER>subject</H1>
> <HR>

#### Page Footer

The default page footer shown below is used in hypermail on both the index and the message pages look like:

> <HR>
> <P>
> <SMALL>
> <EM>
> This archive was generated by <A HREF="HMURL">PROGNAME VERSION</A> on DATE and TIME
> </EM>
> </SMALL>
> </BODY>
> </HTML>

### Table Menu Display

The table menu display generates pages that have a menu bar at the top and the bottom of the page that looks something like the following. If you have enabled the "About" and "Other Archives" links are displayed if you have enabled them in options.h, the environment variables or in the list configuration file. A example page:

# TITLE HERE

New Message | Reply | About this list | Date view | Thread view | Subject view | Author view
--- | --- | --- | --- | --- | --- | ---

Kent Landfield (kent@landfield.com)
Wed, 17 Jun 1998 22:28:29 -0500 (CDT)

- Next message: Kent Landfield: "Re: Getting started"
- Previous message: Crispen, Bob: "RE: Ideas"
- Next in thread: Andrew Kuchling: "Re: Getting started"

BODY OF MESSAGE HERE

- Next message: Kent Landfield: "Ideas"
- Next in thread: Guido van Rossum: "Re: Getting started"

New Message | Reply | About this list | Date view | Thread view | Subject view | Author view
--- | --- | --- | --- | --- | --- | ---

This archive was generated by hypermail 2.0x on Thu Jun 04 1998 - 10:05:34 CDT

If you do not want to use the table display then make sure that USETABLE is not defined in options.h and the hm_usetable is not enabled in the list configuration file. When you do so you will get the standard look and feel of the hypermail you have grown acustomed to.

Also note that New Message allows you to provide a means for someone to post a message to the list. This feature is currently only availabe on the Table Menu Display. It can be enabled or disabled by defining HMAIL in options.h or by setting the hm_hmail variable in the list specific configuration file.

## Using Template Files to Customize Your Pages

You can customize your page headers and footers by specifying HTML template files. Hypermail reads template files and uses those in generating the header and footer sections of the index and message pages. Template files contain the actual HTML that you want used when generating the pages. Template files may also contain "Substitution Cookies".

### Substitution Cookies

You can insert "substitution cookies" in the header and footer template files so the appropriate information is filled in at runtime.

Substitution cookies supported:

> %% | - '%' character
> %~ | - Storage directory
> %a | - Other Archives URL
> %b | - About Archive URL
> %e | - Email address of message Author - Not valid on index pages
> %g | - Date and time archive generated
> %h | - HMURL
> %i | - Message-id - Not valid on index pages
> %l | - Archive label
> %m | - Mailto address
> %p | - PROGNAME
> %s | - Subject of message or Index Title
> %v | - VERSION
> %u | - Expanded version link (HMURL,PROGNAME,VERSION)
> \n | - newline character
> \t | - tab character

Additional cookies generate the complete HTML lines:

> %A | - Author META HTML - Not valid on index pages
> %B | - BODY HTML statement
> %S | - Subject META HTML

### Specifying template file locations

You can specify the location of the template files either via environment variables or via entries in the list specific configuration file.

#### Using Environment Variables

If you wish to use environment variables, make sure they are exported and correctly available for hypermail to use. How to do this is dependent on the type of shell in use. See the appropriate man pages if you need more information.

- HM_IHTMLHEADERFILE - the location of the INDEX header template.
- HM_IHTMLFOOTERFILE - the location of the INDEX footer template.
- HM_MHTMLHEADERFILE - the location of the MESSAGE header template.
- HM_MHTMLFOOTERFILE - the location of the MESSAGE footer template.

#### Using Configuration File Entries

An easy way is to tell hypermail where the template files are is via a list specific configuration file. The following entries can be used.

- hm_ihtmlheaderfile - the location of the INDEX header template.
- hm_ihtmlfooterfile - the location of the INDEX footer template.
- hm_mhtmlheaderfile - the location of the MESSAGE header template.
- hm_mhtmlfooterfile - the location of the MESSAGE footer template.

#### Examples

It is acceptable to have a single configuration file listed in more than one entry. Suppose you want to have a common footer for all pages and separate headers. The following example shows that.

> hm_ihtmlheaderfile = /lists/wu-ftpd/wu-ftpd-index.hyp
> hm_mhtmlheaderfile = /lists/wu-ftpd/wu-ftpd-msg.hyp
> hm_ihtmlfooterfile = /lists/wu-ftpd/wu-ftpd-msgfooter.hyp
> hm_mhtmlfooterfile = /lists/wu-ftpd/wu-ftpd-msgfooter.hyp

If an entry is left blank and a location is not specified via an environment variable then the hypermail default headers are used.

> hm_ihtmlheaderfile = /lists/wu-ftpd/wu-ftpd-index.hyp
> hm_ihtmlfooterfile =
> hm_mhtmlheaderfile = /lists/wu-ftpd/wu-ftpd-msg.hyp
> hm_mhtmlfooterfile = /lists/wu-ftpd/wu-ftpd-msgfooter.hyp

The above example informs hypermail to use the template files listed for the Index header and the Message header and footer. The hypermail default page footer would be used on the index pages.

NOTE: While it is not necessary to provide absolute paths, it is a good idea to.

### Message Pages

Each HTML file that is generated for a message contains (where applicable):

- the subject of the article,
- the name and email address of the sender,
- the date the article was sent,
- links to the next and previous messages in the archive,
- a link to the message the article is in reply to, and
- a link to the message next in the current thread.

### Including Reference Links

Reference links such as the following

- Next message: Kent Landfield: "Re: Getting started"
- Previous message: Crispen, Bob: "RE: Ideas"
- Next in thread: Andrew Kuchling: "Re: Getting started"

are normally included on each of the message pages. If this is not what you want you can disable them by using the SHOW_MESSAGE_LINKS define in options.h or the hm_show_msg_links in the list's configuration file.

Additionally, if you want to list all replies to a message such as the following,

- In reply to: Kent Landfield: "Getting started"
- Reply: Guido van Rossum: "Re: Getting started"
- Reply: Andrew Kuchling: "Re: Getting started"
- Reply: Kent Landfield: "Re: Getting started"

you can do so by setting the SHOWREPLIES define in options.h or the hm_showreplies in the list's configuration file.

### In-lining Images

It is possible to have images that are sent in email automatically displayed when the message is presented. To do this you need to set the hm_inline_types in the list configuration file.

For example, if you listed

> hm_inline_types = image/gif image/jpeg

then both GIF files and JPEG files would be displayed as part of the message. Types that are not "in-lined" are linked as a simple attachment requiring the user to click on it to have it displayed.

### Changing The HTML File Suffix

You may wish to have the pages generated use a different HTML file suffix other than the default ".html". To do this you need to either set the default define HTMLSUFFIX in options.h, set the environment variable HM_HTMLSUFFIX or set it in the list's configuration file by using the hm_htmlsuffix variable.

Note: Do not include a "." in the suffix; If you do you will end up with filenames that look like. "..html"

## See Also

> hypermail.(1), hmrc.(4), Hypermail and Hypermail List Configuration File. and Adding a Search Engines to your Hypermail Archive

Last updated April 10, 2003