|
20060325
|
Tags
|
Usertag creation tips
|
This is an excerpt from an email Kevin Walsh sent to the userlist on March 25, 2006. It is an excellent description of how usertags can be created properly. Appended to the end of the message is a comment added by Mike in the same thread.
If you have a UserTag like this:
UserTag foobar Order foo bar baz
then you have three named arguments, which you can use like this:
[foobar foo="aaa" bar="bbb" baz="ccc"]
You can put the args in any order you like. The tag code will receive them in the order you specified in the UserTag "Order" config.
In your UserTag code, you can collect the args like this:
my ($foo,$bar,$baz) = @_;
The variable names are irrelevant, but it's useful to name them after the Order values.
If you make your UserTag into a container, like this:
UserTag foobar HasEndTag 1 UserTag foobar Order foo bar baz
then you can use your tag like this:
[foobar foo="aaa" bar="bbb" baz="ccc"] Tag body [/foobar]
Now you have an extra argument, which you collect like this:
my ($foo,$bar,$baz,$body) = @_;
If you want your tag body to be interpolated by default (no need to specify interpolate=1) then you define it like this:
UserTag foobar HasEndTag 1 UserTag foobar Interpolate 1 UserTag foobar Order foo bar baz
You can also create "on the fly" tag arguments, like this:
UserTag foobar HasEndTag 1 UserTag foobar Interpolate 1 UserTag foobar AddAttr 1 UserTag foobar Order foo bar baz
Your collection for the above should look like this:
my ($foo,$bar,$baz,$body,$opt) = @_; ## See Mikes note below.
With AddAttr, you can pass an argument that's not in your "Order" list and see it in your tag code, for instance:
[foobar foo="aaa" kevin="bbb"] Tag body [/foobar]
In the above case, $foo will be "aaa", $bar and $baz will be undef. $body will be " Tag body " and $opt->{kevin} will be "bbb". Note that $opt is a hashref.
Kevins reply was prompted by a question, and Mikes followup addendum answered a few more questions:
[foobar foo="aaa" bar="bbb" baz="ccc"] Tag body [/foobar] > my ($foo,$bar,$baz,$body,$opt) = @_; >
Slight problem with that -- it is actually:
my($foo, $bar, $baz, $opt, $body) = @_;
(Whitespace doesn't cost money.)
> Is the variable $body specific ?
No -- Perl applies in this case. The arguments are passed to the subroutine.
> In other words could $Body or $MyStuff be used in place $body ?
Yes, whatever you happen to name it.
> > Is it because of adding 'HasEndTag 1' to the UserTag definition > that you can grab the 'Tag Body' information ?
Yes.
And a bit more from Kevin:
The "Order" defines two things:
1. The order in which positional parameters are expected:
2. The order in which the given parameters will be passed to your code.
If I use the following example:
UserTag foobar Order foo bar baz
then the following tag calls are equivalent:
[foobar aaa bbb ccc]
[foobar baz="ccc" foo="aaa" bar="bbb"]
If the parameters are collected using the following code:
my ($one,$two,$three) = @_;
then above examples will will cause the following values to be set:
$one will be set to "aaa" $two will be set to "bbb" $three will be set to "ccc"
Of course, it's nicer to name the variables after the Order values, like this:
my ($foo,$bar,$baz) = @_;
|