<%doc>
This component generates a URL-dependant "URL-trail" -- a list of paths
leading up the current document. 

For example, the URL /foo/bar/baz.html yields the following "Where am I"
string (this is indented and spaced for clarity):

      <a href="/">Home</a>
 &gt; <a href="/foo/">Foo</a>
 &gt; <a href="/foo/bar/">Bar</a>
 &gt; <a href="/foo/bar/baz.html">Baz</a>

which looks (kind of) like (imagine the hyperlinks):

 Home > Foo > Bar > Baz

A functional example can be found at, e.g., http://dir.yahoo.com/Business_and_Economy/Shopping_and_Services/Communication_and_Information_Management/Internet_and_World_Wide_Web/Portals/Personalized/.

Many sites generate these by hand, which gets tedious.

Since it is URL dependent, using informative URL names helps. Some work is
done to make the display string cleaner: the trailing '.html', if any, is
stripped out; underscores are translated to spaces; and it is run through
ucfirst.

TODO: 
 * Make the individual parts nameable from a configuration file or data
   structure, rather than using the URL.
</%doc>
<%once>
    %HTML::Mason::Commands::WhereAmICache = ();
</%once>
<%perl>
    # Configuration stuff
    # name_of_home is the label for the top level link
    my $name_of_home      = 'Home';
    # joining_character is what gets put between the different items in
    # the string, e.g., Home > News or Home --> News or Home :> News
    my $joining_character = ' > ';

    # Caching stuff...
    my $uri = $r->uri;
    defined($HTML::Mason::Commands::WhereAmICache{$uri}) &&
        return $HTML::Mason::Commands::WhereAmICache{$uri};

    # Lexicals...
    my $whereami = '';
    my @urlparts = ();
    my $urlpath  = '/';

    my @uri      = split '/', $uri;
    while (@uri) {
        my $original = shift @uri;
        my $display = $original;
        $display =~ s:\.html$::;
        $display =~ s:index$::;
        $display =~ s:/::;
        $display =~ tr/_/ /;
   
        push @urlparts, { 
             display  => ucfirst($display),
             original => $original };
    }
    @urlparts = grep { $_->{original} ne '' && $_->{display} ne '' } @urlparts;

    @uri = map {
               $urlpath = sprintf("%s%s",$urlpath,$_->{original});
               $urlpath .= '/' unless $_->{original} =~ m:html$:;
               sprintf(qq{<a href="%s">%s</a>},$urlpath,$_->{display});
           } @urlparts;
    $whereami = join $joining_character,qq{<a href="/">$name_of_home</a>},@uri;
    $HTML::Mason::Commands::WhereAmICache{$uri} = $whereami;
    return $whereami; 
</%perl>
