SVN::Web::action - base class for SVN::Web::actions
This is the base class for all SVN::Web actions. It provides a constructor and some useful utility methods that actions may find useful. It also contains documentation for anyone interested in writing new SVN::Web actions.
SVN::Web actions are Perl modules loaded by SVN::Web. They are expected to retrieve some information from the Subversion repository, and return that information ready for the user's browser, optionally via formatting by a Template::Toolkit template.
Action names are listed in the SVN::Web configuration file, config.yaml, in the actions: clause. Each entry specifies the class that implements the action, options that are set globally for that action, and metadata that describes when and how the action should appear in the action menu.
actions:
actions: ... new_action: class: Class::That::Implements::Action action_menu: # Optional show: - file # Zero or more of this, ... - directory # ... this ... - revision # ... or this. - global # Or possibly just this one link_text: (text) # Mandatory head_only: 1 # Optional icon: /a/path # Optional opts: option1: value1 option2: value2 ...
Each action is a class that must implement a run() method.
run()
Actions should derive from SVN::Web::action. This gives them a default constructor that generates a hash based object.
use base 'SVN::Web::action';
The run method is where the action carries out its work.
run
The method is passed a single parameter, the standard $self hash ref. This contains numerous useful keys.
$self
The options for this action from config.yaml. Using the example from the OVERVIEW, this would lead to:
$self->{opts} = { 'option1' => 'value1', 'option2' => 'value2', };
An instance of a CGI object corresponding to the current request. This is normally an object from either the CGI or CGI::Fast modules, although it is possible to specify another class with the cgi_class directive in config.yaml.
cgi_class
You can use this object to retrieve the values of any parameters passed to your action.
For example, if your action takes a rev parameter, indicating the repository revision to work on;
rev
my $rev = $self->{cgi}->param('rev');
The path in the repository that was passed to the action.
A reference to an array of path components, one for each directory (and possible final file) in $self->{path}. Equivalent to [ split('/', $self->{path}) ]
[ split('/', $self->{path}) ]
The config hash, as read by YAML from config.yaml. Directives from the config file are second level hash keys. For example, the actions configuration directive contains a list of valid actions.
actions
my @valid_actions = @{ $self->{config}->{actions} };
The symbolic name of the repository being accessed.
A instance of the SVN::Repos class, corresponding to the repository being accessed. This repository has already been opened.
For example, to find the youngest (i.e., most recent) revision of the repository;
my $yr = $self->{repos}->fs()->youngest_rev();
The action that has been requested. It's possible for multiple action names to be mapped to a single class in the config file, and this lets you differentiate between them.
The URL for the currently running script.
The return value from run() determines how the data from the action is displayed.
If run() wants a template to be displayed containing formatted data from the method then the hash ref should contain two keys.
This is the name of the template to return. By convention the template and the action share the same name.
This is a hash ref. The hash keys become variables of the same name in the template.
The character set and MIME type can also be specified, in the charset and mimetype keys. If these values are not specified then they default to UTF-8 and text/html respectively.
charset
mimetype
UTF-8
text/html
E.g., for an action named my_action, using a template called my_action that looks like this:
my_action
<p>The youngest interesting revision of [% file %] is [% rev %].</p>
then this code would be appropriate.
# $rev and $file set earlier in the method return { template => 'my_action', data => { rev => $rev, file => $file, }, };
If the action does not want to use a template and just wants to return data, but retain control of the character set and MIME type, run() should return a hash ref. This should contain a key called body, the value of which will be sent directly to the browser.
body
E.g., for an action that generates a PNG image from data in the repository (perhaps using SVN::Churn);
# $png contains the PNG image, created earlier in the method return { mimetype => 'image/png', body => $png };
If the action just wants to return HTML in UTF-8, it can return a single scalar that contains the HTML to be sent to the browser.
return "<p>hello, world</p>";
The following methods are intended to share common code among actions.
Given a repository path, and a revision number, returns the most recent interesting revision for the path that is the same as, or older (i.e., smaller) than the revision number.
If called in an array context it returns all the arguments normally passed to a log message receiver.
Returns a list of 4 items. In order, they are:
The value of any CGI rev parameter passed to the action ($exp_rev).
The repository's youngest revision ($yng_rev) for the current path. This is not necessarily the same as the repositories youngest revision.
The actual revision ($act_rev) that will be acted on. This is the explicit rev, if it's defined, otherwise it's the youngest rev.
A boolean value indicating whether or not we can be considered to be at the HEAD of the repository ($at_head).
Given a cstring that represents a Subversion time, format the time using POSIX::strftime() and the current settings of the timedate_format and timezone configuration directives.
timedate_format
timezone
If the output from the action can usefully be cached then consider implementing a cache_key method.
cache_key
This method receives the same parameters as the run() method, and must use those parameters to generate a unique key for the content generated by the run() method.
For example, consider the standard Revision action. This action only depends on a single parameter -- the repository revision number. So that makes a good cache key.
Revision
sub cache_key { my $self = shift; return $self->{cgi}->param('rev'); }
Other actions may have more complicated keys.
If your action needs to fail for some reason -- perhaps the parameters passed to it are incorrect, or the user lacks the necessary permissions, then throw an exception.
Exceptions, along with examples, are described in SVN::Web::X.
Copyright 2005-2007 by Nik Clayton <nik@FreeBSD.org>.
<nik@FreeBSD.org>
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://www.perl.com/perl/misc/Artistic.html
To install SVN::Web, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SVN::Web
CPAN shell
perl -MCPAN -e shell install SVN::Web
For more information on module installation, please visit the detailed CPAN module installation guide.