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.
• Anyone interested in the use of embedding html form elements into a generated Forrest page.
• Anyone needing to add extra documents to the processing.

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.

See the example for the Apache Forrest website. The following files are involved:

$FORREST_HOME/site-author/content/xdocs/site.xml (search for "mirrors")
$FORREST_HOME/site-author/content/xdocs/mirrors.html
$FORREST_HOME/site-author/content/mirrors.cgi
$FORREST_HOME/site-author/conf/cli.xconf (search for "mirrors")
$FORREST_HOME/site-author/forrest.properties (search for "project.configfile")

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 the following entry to your project's cli.xconf file. See the FAQ about adding and configuring a project-based cli.xconf

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

This example comes from $FORREST_HOME/site-author/conf/cli.xconf file. The path is relative to $FORREST_HOME/main/webapp/ directory. A full pathname should also work.

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

Exclude mirrors CGI token URIs from processing

The mirrors.html has special URIs which are processed by the mirrors CGI script. These URIs need to be excluded from processing by Cocoon. Add the following entries to your conf/cli.xconf ...

<!-- Exclude tokens used in URLs to ASF mirrors (interpreted by a CGI) -->
<exclude pattern="[preferred]/**"/>
<exclude pattern="[location]"/>
      

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 site' command, or forrestbot. The mirrors.html page will be generated with the skin applied.