NAME

GT::Template::Inheritance - Provides GT::Template inheritance/local file determination.

SYNOPSIS

    use GT::Template::Inheritance;

    my $file = GT::Template::Inheritance->get_path(
        file => "foo.htm",
        path => "/path/to/my/template/set"
    );

    my @files = GT::Template::Inheritance->get_all_paths(
        file => "foo.htm",
        path => "/path/to/my/template/set"
    );

    my @paths = GT::Template::Inheritance->tree(
        path => "/path/to/my/template/set"
    );

DESCRIPTION

GT::Template::Inheritance provides an interface to accessing files for GT::Template template parsing and include handling. It supports following inheritance directories and respects ``local'' template directories.

Inheritance

GT::Template inheritance works by looking for a .tplinfo file in the template directory (or local/.tplinfo, if it exists). In order for the template directory to inherit from another template directory, this file must exist and must evaluate to a hash reference containing an inheritance key. The following is a possible .tplinfo file contents:

    {
        inheritance => '../other'
    }

The above example would indicate that files in this template set can be inherited from the ../other path, relative to the current template set directory. The inheritance directory may also contain a full path.

Inheriting from multiple locations

You may also inherit from multiple locations by using an array reference for the inheritance value:

    {
        inheritance => ['../other', '/full/path/to/a/third']
    }

With the above .tplinfo file, files would be checked for in the current path, then ../other, then any of ../other's inherited directories, then in third, then in any of third's inherited directories.

Also keep in mind that ``local'' directories, if they exist, will be checked for the file before each of their respective directories.

Assuming that the initial template path was /full/path/one, and assuming that ../other inherited from ../other2, the directories checked would be as follows:

    /full/path/one/local
    /full/path/one
    /full/path/one/../other/local            # i.e. /full/path/other/local
    /full/path/one/../other                  # i.e. /full/path/other
    /full/path/one/../other/../other2/local  # i.e. /full/path/other2/local
    /full/path/one/../other/../other2        # i.e. /full/path/other2
    /full/path/to/a/third/local
    /full/path/to/a/third

METHODS

All methods in GT::Template::Inheritance are class methods. Each method takes a hash of options as an argument.

get_path

get_all_paths

These methods are used to obtain the location of the file GT::Template will use, taking into account all inherited and ``local'' template directories. The get_path option will return the path to the file that will be included, while the get_all_paths option returns the path to all copies of the file found in the local/inheritance tree. Both methods take a hash containing the following:

file: The name of the file desired.
path: The template directory at which to start looking for the above file. Depending on the existance of ``local'' directories and template inheritance, more than just this directory will be checked for the file.
local: Optional. Can be passed with a false value to override the checking of ``local'' directories for files.
inheritance: Optional. Can be passed with a false value to override the checking of inheritance directories for files.

tree

This method returns a list of directories that would be searched for a given file, in the order they would be searched. It takes the path, local, and inheritance options above, but not the file option.

MAINTAINER

Jason Rhinelander

COPYRIGHT

VERSION

Revision: $Id: Inheritance.pm,v 1.7 2005/02/09 20:51:27 jagerman Exp $