Provided by: libsvn-web-perl_0.63-3.1_all bug

NAME

       SVN::Web::action - base class for SVN::Web::actions

DESCRIPTION

       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.

OVERVIEW

       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:
           ...
           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.

SUBCLASSING

       Actions should derive from SVN::Web::action.  This gives them a default constructor that
       generates a hash based object.

         use base 'SVN::Web::action';

METHODS

   run()
       The "run" method is where the action carries out its work.

       Parameters

       The method is passed a single parameter, the standard $self hash ref.  This contains
       numerous useful keys.

       $self->{opts}
           The options for this action from config.yaml.  Using the example from the OVERVIEW,
           this would lead to:

             $self->{opts} = { 'option1' => 'value1',
                               'option2' => 'value2',
                             };

       $self->{cgi}
           An instance of a CGI compatible 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. Since we now
           use Plack, this is a Plack::Request object.

           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;

             my $rev = $self->{cgi}->param('rev');

       $self->{path}
           The path in the repository that was passed to the action.

       $self->{navpaths}
           A reference to an array of path components, one for each directory (and possible final
           file) in $self->{path}.  Equivalent to "[ split('/', $self->{path}) ]"

       $self->{config}
           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.

             my @valid_actions = @{ $self->{config}->{actions} };

       $self->{reposname}
           The symbolic name of the repository being accessed.

       $self->{repos}
           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();

       $self->{action}
           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.

       $self->{script}
           The URL for the currently running script.

       Return value

       The return value from "run()" determines how the data from the action is displayed.

       Using a template

       If "run()" wants a template to be displayed containing formatted data from the method then
       the hash ref should contain two keys.

       template
           This is the name of the template to return.  By convention the template and the action
           share the same name.

       data
           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.

       E.g., for an action named "my_action", using a template called "my_action" that looks like
       this:

         <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,
                              },
                };

       Returning data with optional charset and MIME type

       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.

       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.

       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
                };

       Returning HTML with default charset and MIME type

       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>";

UTILITY METHODS

       The following methods are intended to share common code among actions.

   recent_interesting_rev($path, $rev)
       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.

   get_revs()
       Returns a list of 4 items.  In order, they are:

       Explicit rev
           The value of any CGI "rev" parameter passed to the action ($exp_rev).

       Youngest rev
           The repository's youngest revision ($yng_rev) for the current path.  This is not
           necessarily the same as the repositories youngest revision.

       Actual rev
           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.

       Head
           A boolean value indicating whether or not we can be considered to be at the HEAD of
           the repository ($at_head).

   format_svn_timestamp()
       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.

CACHING

       If the output from the action can usefully be cached then consider implementing a
       "cache_key" method.

       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.

         sub cache_key {
             my $self = shift;

             return $self->{cgi}->param('rev');
         }

       Other actions may have more complicated keys.

ERRORS AND EXCEPTIONS

       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

       Copyright 2005-2007 by Nik Clayton "<nik@FreeBSD.org>".

       Copyright 2012 by Dean Hamstead "<dean@fragfest.com.au>".

       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>