view release on metacpan or  search on metacpan

lib/AxKit2/XSP/TaglibHelper.pm  view on Meta::CPAN

This function specification is actually an alias for a perl function of
a different name. For example, a specification of
C<"person($name):isreally=get_person"> allows you to have a tag <ns:person
name="Joe"/> that will resolve to Perl code "get_person('Joe')".

=item as_xml

Set this to true and return a well-balanced chunk of XML, and it will be 
parsed and added to the output.

=item 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.

=back

=head1 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 LIMITATIONS
section.

=head1 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>.

=head1 ARRAY INPUT EXAMPLE

If you wish to send an arbitrary number of values to a taglib function's
parameter, use "@" instead of "$" for the variable in the EXPORT_TAGLIB
header array (but still declare it with "$" in the function 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.

=head1 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 contains
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.

=head1 AUTHOR

Steve Willer, steve@willer.cc

=head1 SEE ALSO

AxKit.

=cut