NAME

NAME
HTML::ActiveLink - dynamically activate HTML links based on URL

SYNOPSIS
use HTML::ActiveLink;

my $al = new HTML::ActiveLink;

print $al->activelink(@html_doc);

DESCRIPTION
I don't know about you, but one of the main problems I have with HTML
content is getting images and links to "turn on" depending on the
current URL location. That is, I like authoring one set of templates,
something like this:

[ <a href="/">Home</a> | <a href="/faq/">FAQ</a>
| <a href="/about/">About Us</a> ]

And then having the appropriate link turned on, so that if I'm running
inside the /home/ directory, the above turns into this:

[ Home | <a href="/faq/">FAQ</a>
| <a href="/about/">About Us</a> ]

Without having to write a whole bunch of if's, or writing a bunch of
different sets of templates, etc.

This module handles the above process automatically. By default, it will
activate any text or images with <a href> tags around them by stripping
the link off and changing the appearance of text and names of images.
All transformations are fully customizable, allowing you to choose how
your active text should look. HTML::ActiveLink can even automatically
construct imagemaps depending on your location.

In the simplest case, all you have to do is create a new object by a
call to new(), and then call the main activelink() function which takes
care of the transformation. To customize what the output HTML looks
like, keep reading...

FUNCTIONS
new()

This is the constructor method, and it takes a number of parameters that
determine how the output HTML looks:

text - transform text links? [1]
text_prefix - prefix to add to text []
text_suffix - suffix to add to text []
text_rmlink - remove <a href=> tag? [1]

image - transform image links? [1]
image_prefix - prefix to add to image []
image_suffix - suffix to add to image [_on]
image_rmlink - remove <a href=> tag? [1]

imagemap - create URL imagemaps? [1]
imagemap_prefix - prefix for imagemaps []
imagemap_suffix - suffix for imagemaps [_on]
imagemap_joinchar - join parts with char [_]
imagemap_rootname - imagemap name for / [home]
imagemap_dirdepth - max dir levels to use [2]

The first set of args determines how to transform text links. By
default, any text links will be changed into red text when you're in the
directory or document that they point to (see below for more explicit
details). To change this, just change the prefix and suffix, for
example:

my $al = HTML::ActiveLink->new(text_prefix => '',
text_suffix => ' >');

This will make the active links bold, with a > sign after them as well.
A similar principle works for images. By default, an image link like so:

<a href="/home/"><img src="/images/home.gif"></a>

Will be transformed to:

<img src="/images/home_on.gif">

Notice that the file type suffix is preserved, and that the image suffix
is properly applied to the name of the image. Again, to change the
suffix or prefix simply change the image_ parameters.

Finally, this module will automatically construct imagemaps based on the
current URL. Unlike the two above methods, which involve parsing and
modifying existing content, the imagemap creation instead creates the
name of the imagemap dynamically. This is done since imagemaps contain
multiple links, so each one represents many areas to click on.

For example, if you are running in the directory /faq/, and you have an
imagemap that looks like this:

<img src="/images/tab.gif" usemap="#nav">

Then the image src will be rewritten as:

<img src="/images/tab_faq_on.gif" usemap="#nav">

Here, the name of the imagemap is rewritten similarly to images, only
depending on your location. The directory information is inserted in
after the name of the image that exists, along with the suffix. The
imagemap name is created by joining together the directory name(s) for
your current location, up to 2 deep by default. More examples:

/faq/ = tab_faq_on.gif
/ = tab_home_on.gif (depending on _rootname)
/name/g.html = tab_name_on.gif
/id/N/NW/NWIGER/ = tab_id_N_on.gif (note only first 2 used)

The second one depends on what you've set imagemap_rootname to, since
this is what is used to determine the name for /. In the last example,
notice that only 2 dir levels are used by default, meaning that huge dir
trees do not result in tons of different imagemap names. To change this,
set imagemap_dirdepth.

activelink()

This is the function that actually parses the document and activates all
the necessary links. It joins its arguments into a scalar representation
of the file and returns that, which can then be printed out or
manipulated further. Examples:

print $al->activelink(@doc);
print $al->activelink($part1, $part2, $part3);
$doc = $al->activelink(<STDIN>);

And so on. To change how it works, pass different values to the new()
function described above.

The activelink() function uses regular expressions to match the location
so that anything deeper than a link is activated. So, assuming this
link:

<a href="/news/today/">Today's News</a>

Then any of the following locations would cause it to be active:

/news/today/
/news/today/presidential_election_still_undecided.html
/news/today/regional/san_diego_headlines.html

But none of these would:

/news/
/news/today.html
/news/today

Just like with Apache configs, the path needs to be matched completely,
and then anything beneath that path works as well.

APPLICATIONS
One simple use of this module that I like is creating a simple script
called "header.cgi" that just looks something like this:

use HTML::ActiveLink;
my $al = HTML::ActiveLink->new(text_prefix => '',
text_suffix => '');

my $header = '/path/to/header.html';
open(HEADER, "<$header") or die $!;
print $al->activelink(<HEADER>);

Then, I can use this in my SSI documents like so:



And presto! All my SSI .shtml documents have a header which has links
that are automatically activated based on the document location. You
could, of course, beef up the "header.cgi" script so that it used the
name of a file passed as a parameter, etc, depending on what you want to
do.

VERSION
$Id: ActiveLink.pm,v 1.2 2000/11/27 23:46:29 nwiger Exp $

AUTHOR
Copyright (c) 2000 Nathan Wiger, Nateware, Inc. <[email protected]>. All
Rights Reserved.

This module is free software; you may copy this under the terms of the
GNU General Public License, or the Artistic License, copies of which
should have accompanied your Perl kit.