Index Previous: TAGS

# User-defined Tags

MiniVend 3.04 allows the definition of user tags when using the new parsed HTML syntax (a [new] tag is on the page). They will not work with the old syntax. 3.06 adds the tags on a server-wide basis, defined in `minivend.cfg`.

To define a tag that is catalog-specific, place UserTag directives in your catalog.cfg file. For server-wide tags, define them in minivend.cfg. Catalog-specific tags take precedence if both are defined -- in fact, you can override the base MiniVend tag set with them. The directive takes the form:

       UserTag  tagname  property  value

where `tagname` is the name of the tag, `property` is the attribute (described below), and value is the value of the property for that tagname.

The user tags can either be based on Perl subroutines or just be aliases for existing tags. Some quick examples are below.

An alias:

        UserTag product_name Alias     data products title

This will change [product_name 99-102] into [data products title 99-102], which will output the `title` database field for product code `99-102`. Don't use this with `[item-data ...]` and `[item-field ...]`, as they are parsed separately. You can do `[product-name [item-code]]`, though.

A simple subroutine:

        UserTag company_name Routine   sub { "Your company name" }

When you place a [company-name] tag in a MiniVend page, the text `Your company name` will be substituted.

A subroutine with a passed text as an argument:

        UserTag caps   Routine   sub { return "\U@_" }
        UserTag caps   HasEndTag

The tag [caps]This text should be all upper case[/caps] will become `THIS TEXT SHOULD BE ALL UPPER CASE`.

Here is a useful one you might wish to use:

        UserTag quick_table HasEndTag
        UserTag quick_table Interpolate
        UserTag quick_table Order   border
        UserTag quick_table Routine <<EOF
        sub {
            my ($border,$input) = @_;
            $border = " BORDER=$border" if $border;
            my $out = "<TABLE ALIGN=LEFT$border>";
            my @rows = split /\n+/, $input;
            my ($left, $right);
            for(@rows) {
                $out .= '<TR><TD ALIGN=RIGHT VALIGN=TOP>';
                ($left, $right) = split /\s*:\s*/, $_, 2;
                $out .= '<B>' unless $left =~ /</;
                $out .= $left;
                $out .= '</B>' unless $left =~ /</;
                $out .= '</TD><TD VALIGN=TOP>';
                $out .= $right;
                $out .= '</TD></TR>';
                $out .= "\n";
            }
            $out .= '</TABLE>';
        }
        EOF

Called with:

        [quick-table border=2]
        Name: [value name]
        City: [value city][if value state], [value state][/if] [value country]
        [/quick_table]

The properties for UserTag are are:

Alias

  An alias for an existing (or other user-defined) tag. It takes the form:

          UserTag tagname Alias    tag to insert

  An Alias is the only property that does not require a Routine to process the tag.

attrAlias

  An alias for an existing attribute for defined tag. It takes the form:

          UserTag tagname attrAlias   alias attr

  As an example, the standard MiniVend value tag takes a named attribute of name for the variable name, meaning that `[value name=var]` will display the value of form field `var`. If you put this line in catalog.cfg:

          UserTag value attrAlias   identifier name

  then `[value identifier=var]` will be an equivalent tag.

CanNest

  Notifies MiniVend that this tag must be checked for nesting. Only applies to tags that have HasEndTag defined, of course. NOTE: Your routine must handle the subtleties of nesting, so don't use this unless you are quite conversant with parsing routines. See the routines `tag_loop_list` and `tag_if` in lib/Vend/Interpolate.pm for an example of a nesting tag.

          UserTag tagname CanNest

HasEndTag

  Defines an ending [/tag] to encapsulate your text -- the text in between the beginning `[tagname]` and ending `[/tagname]` will be the last argument sent to the defined subroutine.

          UserTag tagname HasEndTag

Implicit

  This defines a tag as implicit, meaning it can just be an `attribute` instead of an `attribute=value` pair. It must be a recognized attribute in the tag definition, or there will be big problems. Use this with caution!

          UserTag tagname Implicit attribute value

  If you want to set a standard include file to a fixed value by default, but don't want to have to specify `[include file="/long/path/to/file"]` every time, you can just put:

          UserTag include Implicit file file=/long/path/to/file

  and `[include file]` will be the equivalent. You can still specify another value with C[include file=``/another/path/to/file'']

InsertHTML

  This attribute makes HTML tag output be inserted into the containing tag, in effect adding an attribute=value pair (or pairs).

          UserTag tagname InsertHTML   htmltag  mvtag|mvtag2|mvtagN

  In MiniVend's standard tags, among others, the <OPTION ...> tag has the [selected ..] and [checked ...] tags included with them, so that you can do:

         <INPUT TYPE=checkbox
              MV="checked mvshipmode upsg" NAME=mv_shipmode> UPS Ground shipping

  to expand to this:

         <INPUT TYPE=checkbox CHECKED NAME=mv_shipmode> UPS Ground shipping

  Providing, of course, that `mv_shipmode` is equal to `upsg`. If you want to turn off this behavior on a per-tag basis, add the attribute mv.noinsert=1 to the tag on your page.

InsideHTML

  To make a container tag be placed after the containing HTML tag, use the InsideHTML setting.

          UserTag tagname InsideHTML   htmltag  mvtag|mvtag2|mvtagN

  In MiniVend's standard tags, the only InsideHTML tag is the < SELECT> tag when used with loop, which causes this:

         <SELECT MV="loop upsg upsb upsr" NAME=mv_shipmode>
         <OPTION VALUE="[loop-code]"> [shipping-desc [loop-code]]
         </SELECT>

  to expand to this:

         <SELECT NAME=mv_shipmode>
         [loop upsg upsb upsr]
         <OPTION VALUE="[loop-code]"> [shipping-desc [loop-code]]
         [/loop]
         </SELECT>

  Without the InsideHTML setting, the [loop ...] would have been outside of the select -- not what you want. If you want to turn off this behavior on a per-tag basis, add the attribute mv.noinside=1 to the tag on your page.

Interpolate

  The behavior for this attribute depends on whether the tag is a container (i.e. HasEndTag is defined). If it is not a container, the Interpolate attribute causes the the resulting HTML from the `UserTag` will be re-parsed for more MiniVend tags. If it is a container, Interpolate causes the contents of the tag to be parsed before the tag routine is run.

          UserTag tagname Interpolate

InvalidateCache

  If this is defined, the presence of the tag on a page will prevent search cache, page cache, and static builds from operating on the page.

          UserTag tagname InvalidateCache

  It does not override [tag flag build][/tag], though.

Order

  The optional arguments that can be sent to the tag. This defines not only the order in which they will be passed to Routine, but the name of the tags. If encapsulated text is appropriate (HasEndTag is set), it will be the last argument.

          UserTag tagname Order param1 param2

PosRoutine

  Identical to the Routine argument -- a subroutine that will be called when the new syntax is not used for the call, i.e. `[usertag argument]` instead of `[usertag ARG=argument]`. If not defined, Routine is used, and MiniVend will usually do the right thing.

ReplaceAttr

  Works in concert with InsertHTML, defining a single attribute which will be replaced in the insertion operation..

        UserTag tagname ReplaceAttr  htmltag attr

  An example is the standard HTML < A HREF=...> tag. If you want to use the MiniVend tag `[area pagename]` inside of it, then you would normally want to replace the HREF attribute. So the equivalent to the following is defined within MiniVend:

        UserTag  area  ReplaceAttr  a  href

  Causing this

          <A MV="area pagename" HREF="a_test_page.html">

  to become

          <A HREF="http://yourserver/cgi/simple/pagename?X8sl2lly;;44">

      when intepreted.

      =item ReplaceHTML

  For HTML-style tag use only. Causes the tag containing the MiniVend tag to be stripped and the result of the tag to be inserted, for certain tags. For example:

        UserTag company_name Routine sub { my $l = shift; return "$l: XYZ Company" }
        UserTag company_name HasEndTag
        UserTag company_name ReplaceHTML  b    company_name

  <BR> is the HTML tag, and ``company_name'' is the MiniVend tag. At that point, the usage:

          <B MV="company-name"> Company </B>  --->>  Company: XYZ Company

  Tags not in the list will not be stripped:

          <I MV="company-name"> Company </I> --->>  <I>Company: XYZ Company</I>

Routine

  An inline subroutine that will be used to process the arguments of the tag. It must not be named, and will be allowed to access unsafe elements only if the `minivend.cfg` parameter AllowGlobal is set for the catalog.

          UserTag tagname Routine  sub { "your perl code here!" }

  The routine may use a ``here'' document for readability:

          UserTag tagname Routine <<EOF
          sub {
              my ($param1, $param2, $text) = @_;
              return "Parameter 1 is $param1, Parameter 2 is $param2";
          }
          EOF

  The usual here documents caveats apply.

  Parameters defined with the Order property will be sent to the routine first, followed by any encapsulated text (HasEndTag is set).

Note that the UserTag facility, combined with AllowGlobal, allows the user to define tags just as powerful as the standard MiniVend tags. This is not recommended for the novice, though -- keep it simple. 8-)

Index Previous: TAGS