Interchange Tags Reference: page

4.52. page

Expands to a hyperlink to an Interchange page or action, including surrounding <A HREF ...>. The URL within the link includes the Interchange session ID and supplied arguments. The optional [/page] is simply a macro for </A>.

If you do not want the <A HREF ...>, use the area tag instead -- these are equivalent:

    [page href=dir/page arg=mv_arg]TargetName</A>
    <A HREF="[area href=dir/page arg=mv_arg]">TargetName</A>

4.52.1. Summary

    [page href arg]
    [page href=dir/page arg=page_arguments other_named_attributes]

Parameters	Description	Default
href	Path to Interchange page or action Special arguments 'scan' treats arg as a search argument 'http://...' external link (requires form attribute)	process
arg	Interchange arguments to page or action	none
base	alias for arg	none

Attributes	Default
extra	none
form	none
search	No
secure	No
interpolate (reparse)	No

Other_Characteristics
Invalidates cache	No
Macro	No
Has end tag	No (`[/page]` is a macro for `</A>`)

Tag expansion example:

    [page href=dir/page.html arg="arg1=AA/arg2=BB"]

    <a href="www.here.com/cgi-bin/mycatalog/page.html?mv_session_id=6CZ2whqo&\
    mv_pc=1&mv_arg=arg1%3dAA/arg2%3dBB">

ASP-like Perl call:

    $Tag->page(  { href => "dir/page",
                   arg  => "arguments", }  );

or similarly with positional parameters,

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

Using arrayref for joined search (see also Attribute Arrays and Hashes)

    my $searchref = [ "se=hammer/fi=products/sf=description",
                      "se=plutonium/fi=products/sf=description", ];

    $Tag->page( { href   => 'scan',
                  search => $searchref, } );

4.52.1.1. See Also

area

4.52.2. Description

The page tag inserts a hyperlink to the specified Interchange page or action. For example, [page shirts] will expand into

   <a href="http://www.here.com/cgi-bin/mycatalog/shirts?mv_session_id=6CZ2whqo&mv_pc=1">

The catalog page displayed will come from "shirts.html" in the pages directory.

The additional argument will be passed to Interchange and placed in the {arg} session parameter. This allows programming of a conditional page display based on where the link came from. The argument is then available with the tag [data session arg], or the embedded Perl session variable $Session->{arg}. Spaces and some other characters will be escaped with the %NN HTTP-style notation and unescaped when the argument is read back into the session.

For better performance, Interchange can prebuild and cache pages that would otherwise be generated dynamically. If Interchange has built such a static page for the target, the page tag produces a link to the cached page whenever the user has accepted and sent back a cookie with the session ID. If the user did not accept the cookie, Interchange cannot use the cache, since the link must then include the mv_session_id argument in order to preserve session.

4.52.2.1. extra

4.52.2.2. form

The optional form argument allows you to encode a form in the link.

        [page form="mv_order_item=os28044
                    mv_order_size=15oz
                    mv_order_quantity=1
                    mv_separate_items=1
                    mv_todo=refresh"] Order 15oz Framing Hammer</A>

The two form values mv_session_id and mv_arg are automatically added when appropriate. The form value mv_arg receives the value of the tag's arg parameter.

This would generate a form that ordered quantity one of item number os28044 with size 15oz. The item would appear on a separate line in the shopping cart, since mv_separate_items is set. Since the href is not set, you will go to the default shopping cart page -- alternatively, you could have set mv_orderpage=yourpage to go to yourpage.

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

You can theoretically submit any form with this, though none of the included values can have newlines or trailing whitespace. If you want to do something like that you will have to write a UserTag.

If the parameter href is not supplied, process is used, causing normal Interchange form processing.

If the href points to an http:// link, then no Interchange URL processing will be done, but the URL will include mv_session_id, mv_pc, and any arguments supplied with the arg attribute:

       [page  href="http://www.elsewhere.net/cgi/script"
              form="cgi_1=ONE
                    cgi_2=TWO"
               arg="Interchange argument"]External link</A>

       <A HREF="http://www.elsewhere.net/cgi/script?\
        mv_session_id=6CZ2whqo&mv_pc=1&mv_arg=Interchange%20argument&\
        cgi_1=ONE&cgi_2=TWO">External link</A>

4.52.2.3. search

Interchange allows you to pass a search in a URL. 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.

These are identical:

    [page scan
          se=Impressionists
          sf=category]
        Impressionist Paintings
    </a>

    [page href=scan
          arg="se=Impressionists
               sf=category"]
        Impressionist Paintings
    </A>

    [page search="se=Impressionists
                  sf=category"]
        Impressionist Paintings
    </a>

Here is the same thing from a non-Interchange page (e.g., a home page), assuming '/cgi-bin/mycatalog' is the CGI path to Interchange's vlink):

     <A HREF="/cgi-bin/mycatalog/scan/se=Impressionists/sf=category">
        Impressionist Paintings
     </A>

Sometimes, you will find that you need to pass characters that will not be interpreted positionally. In that case, you should quote the arguments:

    [page href=scan
          arg=|
                se="Something with spaces"
          |]

See the Search and Form Variables appendix for a listing of the form variables along with two-letter abbreviations and descriptions.

They can be treated just the same as form variables on the page, except that they can't contain spaces, '/' in a file name, or quote marks. These characters can be used in URL hex encoding, i.e. %20 is a space, %2F is a /, etc. -- &sp; or   will not be recognized. If you use one of the methods below to escape these "unsafe" characters, you won't have to worry about this.

You may specify a one-click search in three different ways. The first is as used in previous versions, with the scan URL being specified completely as the page name. The second two use the "argument" parameter to the [page ...] or [area ...]> tags to specify the search (an argument to a scan is never valid anyway).

4.52.2.4. secure

4.52.2.5. Original syntax

If you wish to do an OR search on the fields category and artist for the strings "Surreal" and "Gogh", while matching substrings, you would do:

 [page scan se=Surreal/se=Gogh/os=yes/su=yes/sf=artist/sf=category]
    Van Gogh -- compare to surrealists
 </a>

In this method of specification, to replace a / (slash) in a file name (for the sp, bd, or fi parameter) you must use the shorthand of ::, i.e. sp=results::standard. (This may not work for some browsers, so you should probably either put the page in the main pages directory or define the page in a search profile.)

4.52.2.6. Ampersand syntax

You can substitute & for / in the specification and be able to use / and quotes and spaces in the specification.

 [page scan se="Van Gogh"&sp=lists/surreal&os=yes&su=yes&sf=artist&sf=category]
    Van Gogh -- compare to surrealists
 </a>

Any "unsafe" characters will be escaped.

4.52.2.7. Multi-line syntax

You can specify parameters one to a line, as well.

    [page scan
        se="Van Gogh"
        sp=lists/surreal
        os=yes
        su=yes
        sf=artist
        sf=category
    ] Van Gogh -- compare to surrealists </a>

Any "unsafe" characters will be escaped. You may not search for trailing spaces in this method; it is allowed in the other notations.

4.52.2.8. Joined searches

You can also specify a joined search using an attribute array (see Attribute Arrays and Hashes):

    [page href=scan
      search.0="se=fragrant
                fi=products
                sf=smell"
      search.1="se=purple
                sf=color"
      search.2="se=perennial
                sf=type"]

The search routine called by the page tag automatically adds the other relevant search specification elements, including the 'co=yes' to indicate a combined search (joined searches are described in the Interchange database documentation).

4.52.2.9. [/page]

This is not an actual end tag, but simply a macro that expands to </A>. The following two lines are equivalent:

  [page shirts]Our shirt collection[/page]
  [page shirts]Our shirt collection</A>

Tip: In large pages, just use the </A> tag for a small performance improvement.