For more information... RTFM!
NAVIGATION
PAGES THAT LINK HERE
ACCOUNT LOGIN

You are not logged in

Powered by Interchange version 5.7.0

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 SecureURL. 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

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:
  • "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:

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 form variables will be appended to the href and returned without further modification.

The URI, in this case, will include any values supplied with the "form" or "arg" parameters, but will not include mv_session_id and mv_pc parameters even if the no_session or no_count attributes are explicitly unset to allow it.  Also the add_dot_html and secure attributes will be ignored and .html will not be appended to the path name nor will the protocol be changed to https:// or the SecureURL configuration parameter used.

For example:

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

Availability

In Interchange versions prior to 5.10.0 the path will be extracted and a new URI will be built using the website's VendUrl instead:

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

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

<a href="[area href='foo/baz']">Link text</a>

With link_relative

<a href="[area href='baz' link_relative=1]">Link text</a>

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

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

Warning

Do not 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:

  1. 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.
  2. 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.

Category:  Interchange tags
Last modified by: Peter Ajamian
Modification date: Thursday 9 February 2017 at 11:16 PM (EST)
Home  |  Legal nonsense  |  Privacy policy  |  Donations  |  Contact us