/ 
Class-DBI-Factory-0.86
River stage zero No dependents
/ Class::DBI::Factory::Config

NAME

Class::DBI::Factory::Config - an AppConfig-based configuration mechanism for Class::DBI::Factory

SYNOPSIS

$config = Class::DBI::Factory::Config->new({
	-file => 
});

my @classes = $config->classes;

my $tdir = $config->get('template_dir');

my @referers = $config->get('allowed_referer');

INTRODUCTION

This is just a thin bit of glue that sits between AppConfig and Class::DBI::Factory. Its main purpose is to define the skeleton of parameters that AppConfig uses, but it also provides some useful shorthands for accessing commonly-needed parameters.

In the normal course of events you will never need to work with or subclass this module, or indeed know anything about it. The factory class will take care of constructing and maintaining its own configuration object and following the instructions contained therein.

AppConfig was chosen primarily because it is used by the Template Toolkit and therefore already loaded by my applications. If you're not using TT you may prefer to substitute some other configuration mechanism. You can also subclass more selectively, of course.

DATA SKELETON

The skeleton defined by this module is used by AppConfig to parse configuration files. It details the variables that we are expecting and what to do with each one. Simple variables don't need to be mentioned, but anything with multiple values or more than one level should be prescribed here.

skeleton()

This method returns a hashref that describes the configuration data it expects to encounter. You can refer to the documentation for AppConfig for details of how this works, but for most purposes you should only need to work with the list_parameters, hash_parameters and default_values methods.

You can subclass the whole skeleton() method, but for most purposes it will probably suffice to override some of the methods it calls:

list_parameters

Returns a list of parameter names that should be handled as lists of values rather than as simple scalars.

extra_list_parameters

This is included for convenience: if you want to extend the standard list of list parameters, rather than replacing it, then override this method and return your additions as a list of parameter names.

hash_parameters

Returns a list of parameter names that should be handled as hashes - ie the configuration files will specify both key and value.

extra_hash_parameters

This is included for convenience: if you want to extend the standard list of hash parameters, rather than replacing it, then override this method and return your additions as a list of parameter names.

(At the moment the standard list is empty, but that may not be true for future versions, so it's safer to use the extra methods.)

default_values

Returns a hash of (parameter name => value), in which the value may be simple, a list or a hash. Its treatment will depend on what your data skeleton specifies for that parameter.

extra_defaults

Another shortcut: returns a hash of name => default value which is appended to the usual set of defaults, if you just want to add a couple rather than specifying a whole new set.

INTERFACE

If you decide to replace this module with one of your own, all you have to do is provide these methods:

new()

$config = Class::DBI::Factory::Config->new('/path/to/file');

Should optionally take a file path parameter and pass it to file(): otherwise, just creates an empty configuration object ready for use but not yet populated.

load_packages()

Attempts to load each of the packages specified in 'use_package' config parameters, if any. This requires that a 'package_dir' path has also been supplied, and optionally a 'package_file_suffix', though that will default to 'info' if not found. Note no dot needed, as with all suffix parameters here.

packages()

Returns a list of the packages successfully loaded.

package_loaded()

Returns true if the named package was successfully loaded at startup.

classes()

A shorthand for $config->get('class'): returns a list.

_load_package()

_load_package is mostly obvious: it works out the package file location and passes it to the AppConfig object's file() method for reading.

There is also some shuffling going on here to record the package in which certain key variables are declared. To do that we create a separate, temporary AppConfig object and from that pull a list of all the class and *_view parameters. This information, reversed, is stored in the class_package and view_package hash parameters of the main appconfig object, and used later to respond to queries from templates.

in other words, if the package 'foo' defines a view:

permitted_view = bar

Then we will also store the fact that it did so:

view_package bar = foo

The order of events is such that the package file can override this assumption, by defining its own view_package pair:

permitted_view = bar
view_package bar = default

class = My::Bar
class_package = default

At present the class_package information is only used to make interface decisions, so feel free to tinker with it.

class_package()

$config->class_package('My::Data::Class');

returns the name of the package responsible for bringing this class into the application.

view_package()

$config->view_package('discussions');

returns the name of the package responsible for permitting this view.

file()

$config->file('/path/to/file', '/path/to/otherfile');

Reads configuration files from the supplied addresses, and stores the addresses in case of a later refresh() or rebuild().

refresh()

$config->refresh();
$config->refresh('/path/to/file');

Checks the modification date for each of the configuration files that have been read: if any have changed since we read it, the whole configuration object is dropped and rebuilt.

By default it will revisit the whole set of read configuration files, but if you supply a list of files, refresh() will confine itself to looking at the intersection of your list and the list of files already read. Use $config->file to read a new file, in other words: refresh only works on files that have already been read at least once.

Note that if a configuration file is missing at startup it will not be looked for later: this only refreshes the files already read.

rebuild()

This will drop all configuration information and start again by re-reading all the configuration files. Any other changes your application has made, eg by setting values directly, will be lost.

get()

$config->get('smtp_server');

Gets the named value.

set()

$config->set(smtp_server => 'localhost');

Sets the named value.

all()

returns a simple list of all the variable names held.

template_path()

Returns a reference to an array of directories in which to look for TT templates.

These can be defined in two ways: directly, with a 'template_dir' parameter, or in two stages, with a 'template_root' and one or more 'template_subdir' parameters.

Sequence is important, since the first encountered instance of a template will be used. The order of definition is preserved (so site file > package file > global file), except that all template_dir values are given priority over all template_subdir values: the former would normally be defined by a standard package, the latter by local site configuration.

SEE ALSO

AppConfig Class::DBI Class::DBI::Factory Class::DBI::Factory::Handler Class::DBI::Factory::List

AUTHOR

William Ross, wross@cpan.org

COPYRIGHT

Copyright 2001-4 William Ross, spanner ltd.

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