area

Returns a URI for an Interchange page or form action, including the Interchange session ID and supplied arguments, as appropriate.

Summary

[area href arg]

Parameter	Description	Default
href	Path to Interchange page or action.	None
arg	Interchange argument to page or action	None
add_dot_html	Add ".html" to the end of the path component of the generated URI.	No
add_source	Add a "mv_source" parameter to the URI.	No
alias
form	Encode arguments into the resulting URI.	None
link_relative	The href path is relative to the current directory.	No
match_security	Set secure true if the current page is secure.	No
no_count	Don't encode a "mv_pc" argument into the generated URI.	No
no_session	Never encode a session ID or "mv_pc" arguments into the generated URI.	No
no_session_id	Don't encode a session ID argument into the generated URI.	No
once
scan	Create an Interchange search URI instead of an ordinary href.	No
search	See the scan parameter.	No
secure	to create a "secure" internal URI using VendURL.	No

Examples

Tag expansion example

[area href="dir/foo" arg="bar"]

http://www.example.com/cgi-bin/mywebsite/dir/foo.html?id=abc123&mv_arg=bar

Perl example

$Tag->area({
href => 'dir/foo',
arg => 'bar',
});

or similarly with positional parameters:

$Tag->area($href, $arg, $attribute_hash_reference);

Description

The area tag produces the URI to call an Interchange page, but it does not supply the surrounding <a href="..."> notation. The tag was named [area] because it was originally intended for use with client-side image maps.

The [area] tag has an alias called [href], so following three links are identical in operation:

<a href="[area index]">Website's home page</a>
<a href="[href index]">Website's home page</a>
[page index]Website's home page</a>

Note

Use of the [page] and [href] tags is discouraged; You are advised to use this [area] tag instead.

Parameters

href

The Interchange page name you would like to create a URI for, relative to the "pages" directory. See the PageDir local (catalog.cfg) configuration directive.

If the form parameter is used then the href will default to "process" (see ProcessPage), if not specified otherwise.

Special href values

"http://..." external link (requires that the form parameter is also set. If your href starts with two or more alphanumeric characters followed by a ":" then it will be returned as-is, with the form parameters added, as specified. The following parameters will be overridden in this mode:
- add_dot_html will be set false.
- no_count will be set true.
- no_session will be set true.
- secure will be set false.
"scan" links to a search (using search arguments in arg).

arg

Providing an arg value is a convenient way to pass an argument value to the target page, without using the form parameter, below. The target page will be able to retrieve the argument using either of the following tags:

[data session arg]
[cgi mv_arg]

For instance, if you add the following link to a page:

Visit the <a href="[area href='test' arg='foo']">test</a> page.

then you can capture the argument, on the test.html target page like this:

[if session arg]
The page's mv_arg argument is: [data session arg]
[else]
You did not pass an mv_arg argument to this page
[/else]
[/if]

add_dot_html

If set true then add ".html" to the end of the path component of the generated URI.

If this parameter is not specified then the value of the mv_add_dot_html scratchpad variable will be used.

The default is to not add ".html" to the end of the page name, although this default can be overridden by setting the "mv_add_dot_hmtl" scratchpad variable true.

add_source

If set true then add a "mv_source" parameter to the URI, along with the current "mv_source" value.

The default is to not add a "mv_source" parameter to the URI, although this default can be overridden by setting the "mv_add_source" scratchpad variable true.

alias

form

This parameter allows you to encode arguments into the resulting URI. For example:

<a href="[area href=order form=|
mv_order_item=os28044
mv_order_size=15oz
mv_order_quantity=1
mv_separate_items=1
|]">Order 15oz Framing Hammer</a>

The above would generate a URI that, when followed, would order one of item number "os28044", with a size of "15oz". As mv_separate_items is true, the item would appear on a separate line in the shopping cart. No href was specified, so "process" (see ProcessPage) would be used as the link target. No mv_orderpage was specified, so Interchange would use the website's default shopping cart page. If "mv_orderpage=somepage" was specified then the next page shown, after the order submission, would be "somepage". The mv_session_id and mv_arg form values will be automatically added, whenever Interchange deems it appropriate to do so.

All normal Interchange form caveats apply: You must have an action and you must supply a page, if you don't want to go to the default, etc.

Theoretically, you can submit any form using the method shown above, though none of the included values can have newlines or trailing whitespace. If you want to do something like that you will need to create a custom UserTag.

Once on the target page, this tag's "arg" parameter value can be retrieved using either [data session arg] or [cgi mv_arg].

If the "href" points at a URI that starts with a protocol specification (i.e. "http://..."), and no "form" parameter is provided, then the given URI will be returned verbatim, with no further Interchange processing taking place. The URI, in this case, will not include mv_session_id and mv_pc parameters. For example:

[area href="http://www.example.com/script.html"]

http://www.example.com/script.html

This is, of course, utterly pointless, and a complete waste of your valuable CPU's time.

If the "href" points at a URI that starts with a protocol specification (i.e. "http://..."), and a "form" parameter is provided, then the path will be extracted and a new URI will be built using the website's VendUrl (or SecureUrl) instead. The URI, in this case, will include mv_session_id and mv_pc parameters, as appropriate, along with any values supplied with the "form" or "arg" parameters. For example:

[area
href="http://www.random-website.com/script.html"
arg="A value"
form=|
first=1
second=2
|
]

http://www.your-website.com/script.html?id=abc123&mv_arg=A%20value&first=1&second=2

If you want to encode URI arguments into an external URI then you will have to do it yourself using something like the following:

Don't forget to urlencode your URI arguments appropriately if you use something like the above.

link_relative

If this parameter is set true then the href path will be assumed to be relative to the current directory, and the resulting URI will be generated accordingly.

For instance, if the current page is "foo/bar.html", and you want to link to the "foo/baz.html" page then you can use either of the following two methods:

Without link_relative

With link_relative

match_security

Set secure true if the current page is secure.

no_count

Don't encode a "mv_pc" argument into the generated URI.

If this parameter is not specified then the value of the mv_no_count scratchpad variable will be used.

The default is to always add a "mv_pc" argument into the generated URI, although this default can be overridden by setting the "mv_no_count" scratchpad variable true.

no_session

Never encode "mv_session_id" nor "mv_pc" parameters into the generated URI.

Warning

This parameter will also override the no_count parameter and its associated scratchpad variable value, if set.

no_session_id

Don't encode a "mv_session_id" argument into the generated URI.

This tag will always add a "mv_session_id" argument to the generated URI, unless the "mv_no_session_id" scratchpad variable is set true and a "MV_SESSION_ID" session cookie was provided with the request for the current page.

Warning

Don't confuse the similarly-named "mv_no_session" and "mv_no_session_id" scratchpad variables with one another.

Setting the "mv_no_session" variable true will force this tag to drop the "mv_session_id" argument from the URI in all cases. Setting the "mv_no_session_id" variable true will only cause the "mv_session_id" argument to be dropped from the URI if a "MV_SESSION_ID" session cookie was provided with the request for the current page.

once

scan

Interchange allows you to pass a search in a URI. There are two ways to do this:

Place the search specification in the named search attribute.
- Interchange will ignore the href parameter (the link will be set to 'scan'.
- If you give the arg parameter a value, that value will be available as [value mv_arg] within the search display page.
Set the href parameter to 'scan' and set arg to the search specification.
- Note that you can use this form positionally -- the values go into href and arg, so you do not have to name parameters.

The following three links are all identical to one another:

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

2. <a href="[area href=scan arg=|
   se=Impressionists
   sf=category
   |]">Impressionist Paintings</a>

3. <a href="[area search=|
   se=Impressionists
   sf=category
   |]">Impressionist Paintings</a>

Search variables can be treated just the same as form variables, on the page, except that they can't contain spaces, slashes (/) or quote marks. These characters can be specified using hex-encoded notation, i.e. "%20" is a space and "%2F" is a slash etc.

See the one-click searches section of the page Interchange search engine for more information.

See the search parameters page for a list of the search variables, along with the two-letter abbreviations that can be used.

search

See the scan parameter.

secure

Makes use of the website's SecureURL, instead of the VendURL, to create a "secure" internal URI.

If the href is in the AlwaysSecure list then this parameter will be always be true.