Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SVN::Web::action(3)   User Contributed Perl Documentation  SVN::Web::action(3)

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
	   "[A split('/',A $self->{path})A ]"

       $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>

perl v5.24.1			  2012-10-17		   SVN::Web::action(3)

NAME | DESCRIPTION | OVERVIEW | SUBCLASSING | METHODS | UTILITY METHODS | CACHING | ERRORS AND EXCEPTIONS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=SVN::Web::action&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help