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:
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.
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.
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
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
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'']
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.
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.
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
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.
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
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.
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>
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-)