Generate an ASF mirrors page using interactive web form

• Any Apache project that uses Forrest to generate their website will need to have a mirrors page.
• Also anyone interested in the use of ihtml to embed html form elements into a generated Forrest page.

All Apache projects use dynamically generated download pages which determine the closest mirror and provide an interactive list of the current alternative mirrors. This HowTo describes the procedure to generate the template page that is utilised by the mirrors.cgi script. The processed page includes html "form" elements that are not included in the xdocs DTDs.

This process has many exciting applications, beyond the scope of this document.

• Followed the documentation about Making your downloads mirrorable and Apache Mirroring Information .
• Established your ASF distribution space as described.
• Already building your project website with Forrest.

Add the mirrors.cgi as a raw file

As explained in the mirrors document, there will be a two-line CGI wrapper script at the top-level of your website called mirrors.cgi

Utilising the Forrest concept of raw un-processed content, add the file as src/documentation/mirrors.cgi (copy the Forrest project's mirrors.cgi)

Add the mirrors.ihtml to xdocs directory

This file contains the html content of your mirror page, including the html form elements which drive the mirror selection. It also contains the specific tokens that are interpreted by the mirrors.cgi script to add the list of mirrors and select the closest.

Add the file as src/documentation/xdocs/mirrors.html (Use the Forrest project's mirrors.html as a template and edit it to suit.)

Add a menu entry for Download

Add an entry to your site.xml navigation. For example ...

 <about label="About">
  <index label="Index" href="index.html"/>
  <license label="License" href="license.html"/>
  <download label="Download" href="http://forrest.apache.org/mirrors.cgi"/>
  <download_html href="mirrors.html"/><!-- so the page is part of a tab -->
  ...

Cause the mirrors.ithml to be processed as an extra file

Forrest gathers the links that are to be crawled, by reading site.xml and by finding any other internal links in the actual documents. There is no link to mirrors.html because it is an extra file that needs to be generated and skinned, but not linked in any way.

The Cocoon command-line interface (CLI) to the rescue. Add an entry to your project's cli.xconf by copying the default one from $FORREST_HOME/context/WEB-INF/cli.xconf to your src/documentation/conf/ directory (or wherever ${forrest.conf-dir} points). Add the following entry ...

<uris name="mirrors" follow-links="false">
  <uri type="append" src="mirrors.html"/>
</uris>

Run 'forrest' to build your site

That is all that you need to do, Forrest will take care of it from there. Run the 'forrest' command. The mirrors.html page will be generated with the skin applied.

Explanation of the process

Forrest automatically reads ihtml files and transforms the html source to the forrest xdocs intermediate format. It mainly detects heading elements (h1, h2, etc.) and converts them to "sections". The remainder of the html elements are copied over as-is. With this technique the html form elements are copied over to the output.