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 embedding 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 mirrors.cgi and mirrors.html are "extra" documents, i.e. have no links from anywhere in the site. So we explain how to process additional files.

• 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.html 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.)

Note that the special tokens (e.g. [if-any http] [for http]) need to be encompassed by xml comments.

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.html 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/main/webapp/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.