Update of /cvsroot/openinteract/OpenInteract2/lib/OpenInteract2
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv24476
Added Files:
Brick.pm
Log Message:
add base class for resource loader
--- NEW FILE: Brick.pm ---
package OpenInteract2::Brick;
# $Id: Brick.pm,v 1.1 2005/01/28 16:47:44 lachoy Exp $
use strict;
use base qw( Class::Factory );
use OpenInteract2::Exception qw( oi_error );
use OpenInteract2::Util;
$OpenInteract2::Brick::VERSION = sprintf("%d.%02d", q$Revision: 1.1 $ =~ /(\d+)\.(\d+)/);
sub list_resources {
my ( $self ) = @_;
my $all_resources = $self->get_resources;
return sort @{ $all_resources };
}
sub load_resource {
my ( $self, $name ) = @_;
unless ( $name ) {
oi_error "You must specify a resource name to load.";
}
my $all_resources = $self->get_resources;
my $info = $all_resources->{ $name };
unless ( $info ) {
oi_error "Resource '$name' is invalid. Valid resources are: ",
join( ', ', sort keys %{ $all_resources } );
}
$info->[1] ||= 'yes';
return {
content => $self->load( $name ),
destination => $info->[0],
evaluate => $info->[1],
};
}
sub get_name { _must_implement( 'get_name', @_ ) }
sub get_resources { _must_implement( 'get_resources', @_ ) }
sub load { _must_implement( 'load', @_ ) }
sub _must_implement {
my ( $method, $item ) = @_;
my $class = ref( $item ) || $item;
oi_error "Class '$class' must implement method '$method'";
}
OpenInteract2::Util->find_factory_subclasses(
'OpenInteract2::Brick', @INC
);
1;
__END__
=head1 NAME
OpenInteract2::Brick - Base class for inlined data packages
=head1 SYNOPSIS
use OpenInteract2::Brick;
my $loader = OpenInteract2::Brick->new( 'apache' );
my @resources = $loader->list_resources;
print "Resources available in 'Apache': ",
join( ', ', @resources ), "\n";
my $httpd_static_info = $loader->load_resource( 'httpd_static.conf' );
print "File should be stored in: $httpd_static_info->{destination}\n";
print "File contents:\n$httpd_static_info->{content}\n";
=head1 DESCRIPTION
Rather than including lots of sample files used to create packages and
websites, OI2 has a set of 'bricks'. Each one of these classes has one
or more inlined files you can ask for by file name. Each of these
files also has associated with it some metadata to determine where it
should go and whether it should be evaluated as a template before
being stored. (Of course, you're free to ignore these data and do
whatever you want with the contents, but other parts of the OI2
framework need them.)
=head1 CLASS METHODS
B<new( $type )>
Returns an instance of the bricks associated with C<$type>, which
should always be a lowercased value.
=head1 OBJECT METHODS
B<list_resources()>
Returns an array of all resources defined. These are always simple
filenames with no paths, so with the 'apache2' type you would do
something like:
my $loader = OpenInteract2::Brick->new( 'apache2' );
print "Apache2 resources:\n ",
join( "\n ", $loader->list_resources ), "\n";
And get:
Apache2 resources:
httpd_mp2_solo.conf
startup_mp2.pl
These resource names are what you use in C<load_resource()>:
my $startup_info = $loader->load_resource( 'startup_mp2.pl' );
print "Startup script is:\n", $startup_info->{contents};
B<load_resource( $resource_name >
Loads the resource and metdata associated with C<$resource_name>. If
C<$resource_name> is empty or no resource is actually associated with
it we throw an exception.
If the resource is found we return a hashref with the following keys:
=over 4
=item *
B<content>: Contents of the resource.
=item *
B<destination>: Space-delimited string of directories where this
resource should be copied. Note that the string may have template
directives in it.
=item *
B<evaluate>: Whether you should evaluate the data in 'content' before
storing it.
=back
Regarding template directives. A number of resources have template
directives in them so they can be properly named -- for instance, the
perl 'package' declaration in the generated action whene you create a
new package looks like this:
package OpenInteract2::Action::[% class_name %];
When we use this resource we first run it through a template processor
(Template Toolkit) so that when we create a package called
'baseball_stats' the above will get translated to:
package OpenInteract2::Action::BaseballStats;
=head1 SUBCLASSING
Since you typically don't create subclasses by hand this is mostly
unnecessary. If you're interested in creating a C<::Brick> subclass by
hand first look in the C<build_bricks> script found at the root of the
OI2 source tree -- it builds the class dynamically based on
specifications and files found in the filesystem.
That said, subclasses must implement the following methods:
B<get_name()>
Return the name by which people instantiate this loader. Should be
lower-cased.
B<get_resources()>
Return a hash of data regarding the resources specified by this
class. Keys are resource names (generally filenames) and values are
arrayrefs with two elements:
=over 4
=item 0.
String with destination information. This tells the caller where the
contents should be stored. Should be space-delimited and may have
template directives in it.
=item 1.
Whether the content can be evaluated by a template processor as 'yes'
or 'no'. Generally you should leave this as 'yes' unless the specified
resource is actually a TT2 template.
=back
B<load( $resource_name )>
Return the content associated with C<$resource_name>. The caller
(L<OpenInteract2::Brick> checks that C<$resource_name> is valid before
invoking this method.
=head1 SEE ALSO
L<Class::Factory>
=head1 COPYRIGHT
Copyright (c) 2005 Chris Winters. All rights reserved.
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
=head1 AUTHORS
Chris Winters E<lt>ch...@cw...E<gt>
|
