TaglibHelper(3)
NAME
TaglibHelper - module to make it easier to write a taglib
SYNOPSIS
package My::Taglib;
use Apache::AxKit::Language::XSP::TaglibHelper;
@ISA = qw( Apache::AxKit::Language::XSP::TaglibHelper );
## Edit $NS to be the namespace URI you want
$NS = 'http://apache.org/xsp/testtaglib/v1';
## Edit @EXPORT_TAGLIB as needed
@EXPORT_TAGLIB = (
'func1($arg1)',
'func2($arg1,$arg2)',
'func3($arg1,$arg2;$optarg)',
'func4($arg1,*treearg)',
'func4($arg1,*treearg):listtag=mylist:itemtag=item',
);
use strict;
sub func1 {
my ( $arg1 ) = @_ ;
...
return $scalar_or_reference;
}
...
1;
the functions with the same names as listed in @EXPORT_TAGLIB.
DESCRIPTION
The TaglibHelper module is intended to make it much easier to build a
taglib module than had previously existed. When you create a library
that uses TaglibHelper, you need only to write "regular" functions that
take string arguments (optional arguments are supported) and return
standard Perl data structures like strings and hashrefs.
FUNCTION SPECIFICATIONS
The @EXPORT_TAGLIB global variable is where you list your exported
functions. It is of the format:
funcname(arguments)[:options]
The "<arguments"> section contains arguments of the form:
$argument
An argument that is expected to be a plain string
*argument
An argument that can take a XML tree in hashref form
@argument
An argument that is expected to be an array of plain strings or an
array of hashrefs if the subtag has attributes
These arguments are separated by commas, and optional args are
separated from required ones by a semicolon. For example,
"$field1,$field2;$field3,$field4" has required parameters "field1" and
"field2", and optional parameters "field3" and "field4".
The options are colon-separated and give extra hints to TaglibHelper in
places where the default behavior isn't quite what you want. All
options are key/value pairs, formatted as key1=value1:key2=value2, etc.
Currently recognized options are:
listtag
For functions that return arrays, use the indicated wrapper tag for
the list instead of <funcname>-list
itemtag
For functions that return arrays of strings, use the indicated
wrapper tag for the list items instead of <funcname>-item
forcearray
For functions that always return an array, you should generally set
this option to "1". the reason is that if your array-returning
function only returns one value in its array, the result won't be
treated as an array otherwise.
conditional
The function's return value will not be printed, and instead will
be used to conditionally execute child tags. NOTE that arguments to
the function cannot be brought in via child tags, but instead must
come in via attributes.
isreally
This function specification is actually an alias for a perl func-
tion of a different name. For example, a specification of "per-
son($name):isreally=get_person" allows you to have a tag <ns:person
name="Joe"/> that will resolve to Perl code "get_person('Joe')".
as_xml
Set this to true and return a well-balanced chunk of XML, and it
will be parsed and added to the output.
array_uses_hash
Set this to true to use the preceding hash key as the prefix to
array tag names. In the situation where complex data structures of
hashes pointing to arrays are returned, then this makes the xml
output more meaningful. Otherwise the default of the itemtag or
<funcname>-item is used.
EXAMPLE
if you had these two functions:
sub hello ($) {
my ($name) = @_;
return "Hello, $name!";
}
sub get_person ($) {
my ($name) = @_;
return {
person => {
name => $name,
age => 25,
height => 200,
}
}
}
...and you called them with this xsp fragment:
<test:hello>
<test:name>Joe</test:name>
</test:hello>
<test:get-person name="Bob"/>
...you would get this XML result:
Hello, Joe!
<person>
<height>200</height>
<age>25</age>
<name>Bob</name></person>
If your function returned deeper result trees, with hashes containing
hashrefs or something similar, that would be handled fine. There are
some limitations with arrays, however, described in the BUGS AND LIMI-
TATIONS section.
STRUCTURED INPUT EXAMPLE
If you wish to send structured data (i.e. not just a scalar) to a
taglib function, use "*" instead of "$" for a variable. The input to a
taglib function specified as "insert_person($pid,*extra)" might be:
<test:insert-person pid="123">
<test:extra>
<weight>123</weight>
<friends>
<pid>3</pid>
<pid>5</pid>
<pid>13</pid>
</friends>
</test:extra>
</test:insert-person>
The function call would be the same as:
insert_function("123", {
weight => 123,
friends => [ 3, 5, 13 ]
}
);
The <friends> container holds repeating tags, notice, and TaglibHelper
figured out automatically that it needs to use an arrayref instead of
hashref for the values. But you'll get unexpected results if you mix
repeating tags and nonrepeating ones:
<test:extra>
<weight>123</weight>
<friend>3</friend>
<friend>5</friend>
<friend>13</friend>
</test:extra>
Just wrap your singular repeated tags with a plural-form tag, in this
case <friends>.
ARRAY INPUT EXAMPLE
If you wish to send an arbitrary number of values to a taglib func-
tion's parameter, use "@" instead of "$" for the variable in the
EXPORT_TAGLIB header array (but still declare it with "$" in the func-
tion declaration). The parameter will end up turning into an arrayref.
For example, you might have a TaglibHelper header:
listbox($name;$pretty_name,@option,$default,$multiple,$size,$required)
and a Perl declaration:
sub listbox ($$$$$$$) {
my ($name, $pretty_name, $options, $default, $multiple, $size, $required) = @_;
...
}
and an XSP file that calls it:
<test:listbox name="country" pretty_name="Pick a Country" default="" required="1">
<test:option name="Please choose a country" value=""/>
<test:option name="United States" value="US"/>
<test:option name="Canada" value="CA"/>
</test:listbox>
It would turn into this function call:
listbox("country", "Pick a Country", [
{ name => "Please choose a country", value => "" },
{ name => "United States", value => "" },
{ name => "Canada", value => "CA" },
], "", undef, undef, 1);
Hopefully the example is clear enough.
BUGS AND LIMITATIONS
Arrays and arrayrefs are generally difficult to work with because the
items within the array have no keys other than the index value. As a
result, if you want items within an array to be identified correctly,
you must currently make all array items point to a hashref that con-
tains the item's key or you must use the optional arguments to give
TaglibHelper enough "hints" to be able to represent the XML tree the
way you want.
AUTHOR
Steve Willer, steve@willer.cc
SEE ALSO
AxKit.
perl v5.8.0 Apache::AxKit::Language::XSP::TaglibHelper(3)
Man(1) output converted with
man2html