NAME

OpenInteract2::Brick::[% brick_name %] - [% brick_summary %]

SYNOPSIS

[% brick_example | indent(2) %]

DESCRIPTION

[% brick_description %]

Resources

You can grab resources individually using the names below and load_resource() and copy_resources_to(), or you can copy all the resources at once using copy_all_resources_to() -- see OpenInteract2::Brick for details.

[% FOREACH file_info = all_files %] =item [% file_info.name %] [% END %]

COPYRIGHT

Copyright (c) 2005 [% author_names.join( ', ' ) %]. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

[% FOREACH author_info = authors %] [% author_info.name %] <[% author_info.email %]> [% END %]

NAME

OpenInteract2::Brick - Base class for inlined data packages

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

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

CLASS METHODS

new( $type )

Returns an instance of the bricks associated with $type, which should always be a lowercased value.

list_bricks()

Returns a sorted list of all available brick names. With the name you can instantiate a new brick:

 my @brick_names = OpenInteract2::Brick->list_bricks;
 foreach my $name ( @brick_names ) {
     my $brick = OpenInteract2::Brick->new( $name );
     print "Resources in brick '$name': ",
           join( ", ", $brick->list_resources ), "\n";
 }

OBJECT METHODS

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 load_resource():

 my $startup_info = $loader->load_resource( 'startup_mp2.pl' );
 print "Startup script is:\n", $startup_info->{contents};

load_resource( $resource_name

Loads the resource and metdata associated with $resource_name. If $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:

• content: Contents of the resource.

• destination: Space-delimited string of directories where this resource should be copied. Note that the string may have template directives in it.

• evaluate: Whether you should evaluate the data in 'content' before storing it.

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;

copy_all_resources_to( $destination_dir, [ \%token_replacements ] )

Copies all resources from this brick to $destination_dir. See copy_resources_to() for more.

Returns: hashref with keys 'copied', 'skipped', 'same' each of which has as its value an arrayref of the relevant files.

copy_resources_to( $destination_dir, \%token_replacements, @resource_names )

Copies the resources with @resource_names to the given $destination_dir. For those resources that are evaluatable use the \%token_replacements when evaluating as Template Toolkit templates.

If the source and destination are the same -- checked by the content size and MD5 digest -- we don't do a copy.

We also don't do a copy if the resource is specified in the directory's has a '.no_overwrite' file. (See OpenInteract2::Config::Readonly for this file's format and how we use it.)

Returns: hashref with keys 'copied', 'skipped', 'same' each of which has as its value an arrayref of the relevant files.

SUBCLASSING

Since you typically don't create subclasses by hand this is mostly unnecessary. If you're interested in creating a ::Brick subclass by hand first look in the 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:

get_name()

Return the name by which people instantiate this loader. Should be lower-cased.

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:

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.

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.

load( $resource_name )

Return the content associated with $resource_name. The caller (OpenInteract2::Brick checks that $resource_name is valid before invoking this method.

SEE ALSO

Class::Factory

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.

AUTHORS

Chris Winters <chris@cwinters.com>

cpanm OpenInteract2::URL

perl -MCPAN -e shell
install OpenInteract2::URL