- NAME
- SYNOPSIS
- DESCRIPTION

- Inheritance
- Inheriting from multiple locations

- METHODS

- get_path
- get_all_paths
- tree

- SEE ALSO
- MAINTAINER
- COPYRIGHT
- VERSION

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

# SEE ALSO

the GT::Template manpage

# MAINTAINER

Jason Rhinelander

# COPYRIGHT

Copyright (c) 2005 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

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