GCT::XSP::ActionTaglib - Helps Compose AxKit XSP taglibs in a simple and extensible manor.
package MyTaglib; use GCT::XSP::ActionTaglib; @ISA = qw(use GCT::XSP::ActionTaglib;); our $NS = 'MyTaglib-URI'; our $tagactions; $tagactions->{tag1}=[ ...actionlist for tag1... ];
ActionTaglib helps write a talgib module for AxKit. One or more 'actions' are assigned to each XML element processed by the taglib. When the XSP page is 'run' ActionTaglib performs these actions as it parses the XML elements they are assigned to. An action is implemented as two Perl subroutines one for when the opening XML element is parsed, the 'start' subroutine, and one for when the closing XML element is parsed, the 'end' subroutine. For example:
by adding a tag1 entry to the tagactions hashref as follows:
$tagactions->{tag1}=[{-action => 'myaction'}];
And adding the following tags to an XSP page (with the relevant namespace settings)
<ns:tag1> ... </ns:tag1>
'myaction_start' will be called for the opening <ns:tag1> and 'myaction_end' will be called for the closing element </ns:tag1>.
This behavior extends Apache::AxKit::Language::XSP which does essentially the same thing but with one 'action' for all XML elements (parse_start / parse_end). The hope is to make taglibs easier to layout and read but more importantly it is possible to share actions between taglibs and thus save writing the same code twice for different taglibs. Libraries of actions can be written and shared by importing their actions into a taglib module that uses ActionTaglib.
ActionTaglib has two further features to enhance the idea and useage of 'actions'. The first is that a tag can be assigned multiple actions and the second is actions can be given arbitrary options. Multiple actions are assigned in the following manor:
$tagactions->{tag1}=[{-action => 'library_action'}, {-action => 'myaction'} ];
With our <ns:tag1> ... </ns:tag1> example 'library_action_start' followed by 'myaction_start' would be called for the opening element <ns:tag> and 'myaction_end' followed by 'library_action_end' would be called for the closing element </ns:tag>. Note the change in order, actions are proccess in the forward order for an opening element and in the reverse order for a closnig element.
Options can be parsed in the following manor:
$tagactions->{tag1}= [{-action => 'myaction', -options => {-anyoption => 'anyvalue'} }];
The tagactions hashref, as introduced above, accosiates XML elements with the actions that should be performed to proccess them. The format is to specify an array, called an 'actionlist' for each tag as follows:
$tagactions->{tag1} = [..actionlist for tag1..]
Actions are the spcifed, in order, as elements of the array as follows:
[action,action,action...]
Each action is defined by a hash containing th following keys:
-action. Required string. the name of the action to call.
-when. Optional string, Values can be 'start', 'end' or the default 'both'. If the value is 'start' is the action will only be called for the opening tag, if the value is 'end' the action will only be called for the closing tag and if the value is 'both' (or the key -when is ommited) the action will be called for both the opeing and closing tag.
-pkg. Optional string, The pkg that contanis the action to be called. If ommited the default package is the package of the taglib being written, i.e. the current package..
-options. Optional hash, Any options to be passed to the action.
The options are passed as a hash of option value pairs. A complete example of a tagactions hashref is given bellow.
Actions are written in a very similar way to you would write the parse_start and parse_end subs when using AxKit::Lanaguage::XSP directly. Just like the parse* subs in AxKit::Langauge::XSP, action subs output some perl code, as a string, which will be added to the script that is being built for the current XSP page. The proccess, for taglibs in general, is that an XSP page is parsed (with a SAX parser), taglibs transfor it into a perl script, the perl script is executed and ouputs an XML document. The genrated script uses a DOM to build and output it's XML document but this is all handeled by AxKit::Langauge::XSP and a taglib author often need not know.
If you have never written a parse_start or parse_end using AxKit::Language::XSP you can still write actions. They are defined by writing two subs: actionname_start{} and actionname_end{}. which are called or an element that is specified to use the action named 'actionname', that _start sub when the an opening tag is being parsed and the _end sub when a closing tag is being parsed. They both take the following arguments:
($parseargs,$options,$action,$i,$actionlist,$tagactions)
Which are as follows:
$parseargs, array, contains ($e, $tag, %attribs) for the _start sub and ($e, $tag) for the end sub, which is the same idea as used with parse_start and parse_end in AxKit::Lanagauge::XSP.
$options. hashref, the options to use for this action as specified in the $tagactionshash.
Note the passed values of $action, $i, $actionlist and $tagactions are used for wrtiting more advanced actions. They enable an action to modify the $tagactions hahref it is in and thus change the way actions are performed for tags while the source ducument is being parsed, in otherwords on-the-fly. This feature must be used with care becuase the $tagactions hash could easily be changed in a way that makes no sence. However it is enables us to write actions that and, remove or change other action specifications in the taglib.
$action, hashref, the action currently being run.
$i, integer, the index of the current action in it's action list.
$actionlist, arrayref, the actionlist in which the current action is specified.
$tagactions, hasref, all the tagactions.
The variables in passed in parse args are as follows:
$e, the script being build
$tag, the name of the tag being parsed
$attribs, a hash of the attributes bellonging to the current tag.
MORE TO COME...
An example
$tagactions->{helloworld} = [{-action => 'format', #the name of the action -pkg => 'htmlformating', #the package it is defined in -when => 'both', #when to call the action -options => {-type => 'bold'} },{ -action => 'text', -when => 'start', -options => { text => 'Hello World'} }];
None by default.
Adam Griffiths, <adam@goldcrosstechnical.co.uk>
None known, please report any to bugreport@goldcrosstechnical.co.uk
perl, AxKit, Apache::AxKit::Language::XSP.
For writing action libraries@
ActionExporter.
Other talgib authoring modules:
Apache::AxKit::Language::XSP::TaglibHelper, Apache::AxKit::Language::XSP::ObjectTaglib, Apache::AxKit::Language::XSP::SimpleTaglib.
Copyright (C) 2003, Adam Griffiths, Goldcross Technical. All Rights Reserved.
This Program is free software. You may copy or redistribute it under the same terms as Perl itself.
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
To install GCT::XSP::ActionTaglib, copy and paste the appropriate command in to your terminal.
cpanm
cpanm GCT::XSP::ActionTaglib
CPAN shell
perl -MCPAN -e shell install GCT::XSP::ActionTaglib
For more information on module installation, please visit the detailed CPAN module installation guide.