/ 
HTML-ActiveLink-1.02
River stage zero No dependents
/ HTML::ActiveLink

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:

[ <font color="red">Home</font> | <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  [<font color="red">]
text_suffix       -  suffix to add to text  [</font>]
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 => '<b>',
                               text_suffix => ' &gt;</b>');

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 => '<b>',
                               text_suffix => '</b>');

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:

<!--#include "../cgi-bin/header.cgi"-->

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. <nate@nateware.com>. 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.