home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / tsw / TSW_3.4.0.exe / Apache2 / perl / Resolver.pm < prev    next >
Encoding:
Perl POD Document  |  2003-11-12  |  3.5 KB  |  133 lines
  1. # Copyright (c) 1998-2003 by Jonathan Swartz. All rights reserved.
  2. # This program is free software; you can redistribute it and/or modify it
  3. # under the same terms as Perl itself.
  4.  
  5. package HTML::Mason::Resolver;
  6.  
  7. use strict;
  8.  
  9. use HTML::Mason::Exceptions( abbr => ['param_error', 'virtual_error'] );
  10.  
  11. use Params::Validate qw(:all);
  12. Params::Validate::validation_options( on_fail => sub { param_error join '', @_ } );
  13.  
  14. use HTML::Mason::ComponentSource;
  15.  
  16. use Class::Container;
  17. use base qw(Class::Container);
  18.  
  19. # Returns HTML::Mason::ComponentSource object
  20. sub get_info {
  21.     shift->_virtual;
  22. }
  23.  
  24. sub glob_path {
  25.     shift->_virtual;
  26. }
  27.  
  28. sub _virtual
  29. {
  30.     my $self = shift;
  31.  
  32.     my $sub = (caller(1))[3];
  33.     $sub =~ s/.*::(.*?)$/$1/;
  34.     virtual_error "$sub is a virtual method and must be overridden in " . ref($self);
  35. }
  36.  
  37. 1;
  38.  
  39. __END__
  40.  
  41. =head1 NAME
  42.  
  43. HTML::Mason::Resolver - Component path resolver base class
  44.  
  45. =head1 SYNOPSIS
  46.  
  47.   # make a subclass and use it
  48.  
  49. =head1 DESCRIPTION
  50.  
  51. The resolver is responsible for translating a component path like
  52. /foo/index.html into a component.  By default, Mason expects
  53. components to be stored on the filesystem, and uses the
  54. HTML::Mason::Resolver::File class to get information on these
  55. components.
  56.  
  57. The HTML::Mason::Resolver provides a virtual parent class from which
  58. all resolver implementations should inherit.
  59.  
  60. =head1 Class::Container
  61.  
  62. This class is used by most of the Mason object's to manage constructor
  63. parameters and has-a relationships with other objects.
  64.  
  65. See the documentation on this class for details on how to declare what
  66. paremeters are valid for your subclass's constructor.
  67.  
  68. HTML::Mason::Resolver is a subclass of Class::Container so you
  69. do not need to subclass it yourself.
  70.  
  71. =head1 METHODS
  72.  
  73. If you are interested in creating a resolver subclass, you must
  74. implement the following methods.
  75.  
  76. =over 4
  77.  
  78. =item new
  79.  
  80. This method is optional.  The new method included in this class is
  81. simply inherited from C<Class::Container>.
  82. If you need something more complicated done in your new method you
  83. will need to override it in your subclass.
  84.  
  85. =item get_info
  86.  
  87. Given an absolute component path, returns a new
  88. L<HTML::Mason::ComponentSource|HTML::Mason::ComponentSource> object.
  89.  
  90. =item glob_path
  91.  
  92. The only argument to this method is a path glob pattern, something
  93. like "/foo/*" or "/foo/*/bar".  Given this path, it should return a
  94. list of component paths for components which match this glob pattern.
  95.  
  96. For example, the filesystem resolver simply appends this pattern to
  97. each component root in turn and calls the Perl C<glob()> function to
  98. find matching files on the filesystem.
  99.  
  100. =back
  101.  
  102. =head2 Using a Resolver with HTML::Mason::ApacheHandler
  103.  
  104. If you are creating a new resolver that you intend to use with the
  105. L<HTML::Mason::ApacheHandler|HTML::Mason::ApacheHandler> module, then
  106. you must implement the following method as well, possibly in a
  107. different subclass.
  108.  
  109. =over 4
  110.  
  111. =item apache_request_to_comp_path ($r)
  112.  
  113. This method, given an Apache object, should return a component path.
  114. This method is used by the
  115. L<HTML::Mason::ApacheHandler|HTML::Mason::ApacheHandler> class to
  116. translate web requests into component paths.  You can omit this method
  117. if your resolver subclass will never be used in conjunction with
  118. L<HTML::Mason::ApacheHandler|HTML::Mason::ApacheHandler>.
  119.  
  120. =back
  121.  
  122. For example, Mason includes the
  123. L<HTML::Mason::Resolver::File|HTML::Mason::Resolver::File> and
  124. HTML::Mason::Resolver::File::ApacheHandler classes.  The latter simply
  125. adds an implementation of the C<apache_request_to_comp_path> method
  126. for file based components.
  127.  
  128. =head1 SEE ALSO
  129.  
  130. L<HTML::Mason|HTML::Mason>
  131.  
  132. =cut
  133.