Name

area — produce a hypertext link URL

ATTRIBUTES

Attribute Pos. Req. Default Description
href Yes Yes   Name of page or action to link to
alias
once
search
form CGI parameters.
add_dot_html No No No Add HTML page suffix to page name?
secure 0 whether to use SecureURL or VendURL
match_security 0
no_session_id 0 suppress session identifier (id) if set
no_count 0 suppress page counter (mv_pc) if set
no_session 0 same as no_session_id and no_count combined
interpolate     0 interpolate output?
hide     0 Hide the tag return value?

DESCRIPTION

The [area] tag expands to a proper hypertext URL link which preserves Interchange session information and arguments passed onto the targeted page or form action. The target page argument you supply is treated relatively to the pages/ directory inside your catalog root directory (CATROOT).

The enclosing <a href=""></a> HTML tag is not included, only the pure link is output. This makes [area] suitable for use in custom <a> links, Javascript constructs, imagemaps and elsewhere.

The reason this tag was named area in the first place is because it was planned to be used in client side Imagemaps.

The [area] and [page] tags are similar; the following two constructs are identical:

[page href="dir/page" arg="mv_arg"]Target Name</a>
<a href="[area href='dir/page' arg='mv_arg']">Target Name</a>

Besides just producing hypertext links to specific pages, you can also "embed" complete HTML forms in the target link (for say, one-click ordering or searches); see the section called “EXAMPLES”.

BEHAVIOR

This tag does not appear to be affected by, or affect, the rest of Interchange.

EXAMPLES

Example: Produce the basic hypertext link

Add the following to an Interchange page:

Please visit our <a href="[area index]">Welcome</a> page.

Example: Implementing searches using search= option

The search attribute is a shorthand for the href / arg scheme. When search is used, href will be set to scan and arg to the value of search .

<a href="[area search="
    se=Impressionists
    sf=category"]
">Search for Impressionist Paintings</a>

Example: Embedding HTML forms in the area tag

<a href="[area form="
  mv_order_item=99-102
  mv_order_size=L
  mv_order_quantity=1
  mv_separate_items=1
  mv_todo=refresh"
]">Order T-shirt in Large size</a>

Or another example:

<a href="[area form="
  mv_todo=refresh
  mv_order_item=000101
  mv_order_fly=description=An on-the-fly item|price=100.01
"]">Order item 000101</a>

Which is equivalent to the usual HTML form:

<form action="[area process]" method="post">
  <input type='hidden' name='mv_todo' value="refresh">
  <input type='hidden' name='mv_order_item' value="000101">
  Qty: <input size='2' name='mv_order_quantity' value="1">
  <input type='hidden' name='mv_order_fly' value="description=An on-the-fly item|price=100.00">
  <input type='submit' value="Order button">
</form>

Example: Simple item ordering using the area tag

Order a <a href="[area order TK112]" target='newframe'>Toaster</a> today.

Example: Pass arguments onto the target page

Add the following link to an Interchange page:

Visit the <a href="[area href='test' arg='arg1=value1/arg2=value2']">test</a> page.

The relevant part of your test.html page could then look like this:

<p>This is a test page.</p>

[if session arg]
<p>You have passed an argument onto this page:</p>
<p>[data session arg]</p>
[else]
You did not pass any arguments to this page.
[/else]
[/if]

<p>Have a nice day!</p>


Example: Implementing searches using href=/arg= options

<a href="[area scan
    se=Impressionists
    sf=category]
">Search for Impressionist Paintings</a>

Or the equivalent, using named parameters and more understandable quoting:

<a href="[area href=scan
    arg="se=Impressionists
         sf=category"]
">Search for Impressionist Paintings</a>

If the arg parameter is set, it will be available within the search display page as [value mv_arg].


NOTES

The [area] tag examples use some advanced argument-quoting concepts. To minimize confusion, please see the proper and complete quoting explanation in the ITL glossary entry.

AVAILABILITY

area is available in Interchange versions:

4.6.0-5.9.0 (git-head)

SOURCE

Interchange 5.9.0:

Source: code/SystemTag/area.coretag
Lines: 17


# Copyright 2002-2007 Interchange Development Group and others
# 
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.  See the LICENSE file for details.
# 
# $Id: area.coretag,v 1.6 2007-09-21 16:15:48 kwalsh Exp $

UserTag href Alias        area

UserTag area Order        href arg
UserTag area addAttr
UserTag area Implicit     secure secure
UserTag area PosNumber    2
UserTag area Version      $Revision: 1.6 $
UserTag area MapRoutine   Vend::Interpolate::tag_area

Source: lib/Vend/Interpolate.pm
Lines: 2746

sub tag_area {
  ($page, $arg, $opt) = @_;

$page = '' if ! defined $page;

if( $page and $opt->{alias}) {
  my $aloc = $opt->{once} ? 'one_time_path_alias' : 'path_alias';
  $Vend::Session->{$aloc}{$page} = {}
    if not defined $Vend::Session->{path_alias}{$page};
  $Vend::Session->{$aloc}{$page} = $opt->{alias};
}

my ($r, $subname);

if ($opt->{search}) {
  $page = escape_scan($opt->{search});
}
elsif ($page =~ /^[a-z][a-z]+:/) {
  ### Javascript or absolute link
  return $page unless $opt->{form};
  $page =~ s{(\w+://[^/]+)/}{}
    or return $page;
  my $intro = $1;
  my @pieces = split m{/}, $page, 9999;
  $page = pop(@pieces);
  if(! length($page)) {
    $page = pop(@pieces);
    if(! length($page)) {
      $r = $intro;
      $r =~ s{/([^/]+)}{};
      $page = "$1/";
    }
    else {
      $page .= "/";
    }
  }
  $r = join "/", $intro, @pieces unless $r;
  $opt->{add_dot_html} = 0;
  $opt->{no_session} = 1;
  $opt->{secure} = 0;
  $opt->{no_count} = 1;
}
elsif ($page eq 'scan') {
  $page = escape_scan($arg);
  undef $arg;
}

elsif ($subname = $Vend::Cfg->{SpecialSub}{areapage}) {
          my $sub = $Vend::Cfg->{Sub}{$subname} || $Global::GlobalSub->{$subname};
          my $newpage = $sub->($page, $opt);
          $page = $newpage if defined $newpage;
          $arg = $opt->{arg};
      }

$urlroutine = $opt->{secure} ? \&secure_vendUrl : \&vendUrl;

return $urlroutine->($page, $arg, undef, $opt);
}

Source: lib/Vend/Interpolate.pm
Lines: 2746

sub tag_area {
  ($page, $arg, $opt) = @_;

$page = '' if ! defined $page;

if( $page and $opt->{alias}) {
  my $aloc = $opt->{once} ? 'one_time_path_alias' : 'path_alias';
  $Vend::Session->{$aloc}{$page} = {}
    if not defined $Vend::Session->{path_alias}{$page};
  $Vend::Session->{$aloc}{$page} = $opt->{alias};
}

my ($r, $subname);

if ($opt->{search}) {
  $page = escape_scan($opt->{search});
}
elsif ($page =~ /^[a-z][a-z]+:/) {
  ### Javascript or absolute link
  return $page unless $opt->{form};
  $page =~ s{(\w+://[^/]+)/}{}
    or return $page;
  my $intro = $1;
  my @pieces = split m{/}, $page, 9999;
  $page = pop(@pieces);
  if(! length($page)) {
    $page = pop(@pieces);
    if(! length($page)) {
      $r = $intro;
      $r =~ s{/([^/]+)}{};
      $page = "$1/";
    }
    else {
      $page .= "/";
    }
  }
  $r = join "/", $intro, @pieces unless $r;
  $opt->{add_dot_html} = 0;
  $opt->{no_session} = 1;
  $opt->{secure} = 0;
  $opt->{no_count} = 1;
}
elsif ($page eq 'scan') {
  $page = escape_scan($arg);
  undef $arg;
}

elsif ($subname = $Vend::Cfg->{SpecialSub}{areapage}) {
          my $sub = $Vend::Cfg->{Sub}{$subname} || $Global::GlobalSub->{$subname};
          my $newpage = $sub->($page, $opt);
          $page = $newpage if defined $newpage;
          $arg = $opt->{arg};
      }

$urlroutine = $opt->{secure} ? \&secure_vendUrl : \&vendUrl;

return $urlroutine->($page, $arg, undef, $opt);
}

AUTHORS

Interchange Development Group

SEE ALSO

page(7ic), order(7ic)

DocBook! Interchange!