NAME
    Apache::RandomLocation - Perl extension for mod_perl to handle
    random locations.

SYNOPSIS
      You can use this in your Apache *.conf files to activate this module.

      <Location /scripts/random-image>
      SetHandler perl-script
      PerlSetVar BaseURL /images/
      PerlSetVar ConfigFile /usr/local/apache/etc/sponsors
      PerlHandler Apache::RandomLocation
      </Location>

DESCRIPTION
    Given a list of locations in ConfigFile, this module will
    instruct the browser to redirect to one of them given the
    BaseURL.

    For example, you could use it to implement a banner in an HTML
    page: <IMG SRC=/scripts/random-image>

    BaseURL is where all your image files are located. BaseURL can
    be a full or partial URL. It almost always terminates in a slash
    ("/"). BaseURL is optional.

    ConfigFile is where the list of all the images you want to
    display are located. Images should be listed one per line. The
    parser stops reading after a space is located in the line. Lines
    begining with # are ignored.

    This module is not really random. It goes through the entries in
    ConfigFile in order. Because usual multiple copies of httpd
    running, continually clicking on the URL that generates the
    random location will most likely not lead to seeing the images
    in order.

    Note: because the counters are global on a per httpd process
    basis, make sure your don't set your MaxRequestsPerChild too
    low, otherwise you'll keep seeing the same images.

    The module will re-read the ConfigFile after either

            a) each time a new httpd process starts.

            b) it has reached the end of the list of locations.

BUGS
    When starting, the random image program always starts at the
    start of the list. It should start at a random location in the
    list.

    URLs should be urlencoded before sending them to the browser.

    There has been no testing done to see if you can use multiple
    Apache::RandomLocation modules in one server (it probably
    doesn't work very well because they use the same namespace).

AUTHOR
    Matthew Darwin, matthew@davin.ottawa.on.ca

SEE ALSO
    perl(1), Apache(3), mod_perl(3)