package App::ZofCMS::Config;

use warnings;
use strict;

our $VERSION = '0.0103';

use CGI qw/:standard Vars/;
use Carp;

require File::Spec;

sub new {
    my $class = shift;
    my $self = bless {}, $class;
    
    $self->cgi( CGI->new );
    $self->query( $self->_prepare_query );
    
    return $self;
}

sub load {
    my ( $self, $conf_file, $no_page_check ) = @_;

        
    my $conf = do $conf_file
        or croak "Failed to load config file ($!) ($@)";

    defined $conf->{zcms_template_extension}
        or $conf->{zcms_template_extension} = '.tmpl';

    unless ( $no_page_check ) {
        my $query = $self->query;
        my $is_valid_page = $self->_is_valid_page(
            $query,
            $conf,
        );
        
        unless ( $is_valid_page ) {
            @$query{ qw/page dir/ } = qw|404 /|;
        }
    }
        
    return $self->conf( $conf );
}

sub _is_valid_page {
    my ( $self, $query, $conf ) = @_;

    my ( $ext, $templates_dir, $valid_pages )
    = @$conf{ qw/zcms_template_extension templates valid_pages/ };

    unless ( ref $valid_pages eq 'HASH' ) {
        croak "Config file error: valid_pages must be a hashref";
    }
    
    for ( @{ $valid_pages->{pages} || [] } ) {
        return 1
            if $_ eq $query->{dir} . $query->{page};
    }

    for ( @{ $valid_pages->{dirs} || [] } ) {
        return 1
            if $_ eq $query->{dir}
                and -e File::Spec->catfile( $templates_dir, $query->{dir}, $query->{page} . $ext);
    }
    
    return 0;
}

sub _prepare_query {
    my $self = shift;
    
    my %query = Vars();

    unless ( defined $query{page} and length $query{page} ) {
        $query{page} = 'index';
    }

    if ( $query{page} =~ m|/| ) {
        ( $query{dir}, $query{page} ) = $query{page} =~ m|(.*/)([^/]*)$|;
    }

    unless ( defined $query{page} and length $query{page} ) {
        $query{page} = 'index';
    }

    unless ( defined $query{dir} and length $query{dir} ) {
        $query{dir} = '/';
    }

    $query{dir} =~ s/\Q..//g;
    
    $query{dir} = "/$query{dir}"
        unless substr($query{dir}, 0, 1) eq '/';

    $query{dir} .= '/'
        unless substr($query{dir}, -1) eq '/';

    return \%query;
}

sub cgi {
    my $self = shift;
    if ( @_ ) {
        $self->{ cgi } = shift;
    }
    return $self->{ cgi };
}


sub query {
    my $self = shift;
    if ( @_ ) {
        $self->{ query } = shift;
    }
    return $self->{ query };
}


sub conf {
    my $self = shift;
    if ( @_ ) {
        $self->{ conf } = shift;
    }
    return $self->{ conf };
}



1;
__END__

=head1 NAME

App::ZofCMS::Config - "core" part of ZofCMS - web-framework/templating system

=head1 SYNOPSYS

This module is part of "core" of ZofCMS web-framework/templating system.
Please read L<App::ZofCMS> if you haven't done so already. The module is
not to be used as a standalone module, thus no synopsys is provided.
See L<CONFIGURATION FILE EXAMPLES> section below.

=head1 ZofCMS CONFIGURATION FILE

    # sample contents of config.txt ZofCMS configuration file
    {
        data_store      => '../zcms_site/data',
        templates       => '../zcms_site/templates',
        valid_pages => {
            pages   => [
                '/index',
                '/foo/bar/baz',
            ],
            dirs    => [
                '/',
                '/tools/',
                '/tools/ZofCMS/',
            ],
        },
        template_defaults => {
            t   => {
                top => '<a class="back_to_top" href="#">back to top</a>',
            },
            conf    => {
                base    => 'base.tmpl',
            },
            plugins => [ qw/TOC Breadcrumbs/ ],
        },
        dir_defaults => {
            '/' => {
                t => {
                    current_dir => '/',
                }
            },
            '/foos/' => {
                t => {
                    current_dir => '/foos/',
                },
            },
        },
        zcms_template_extension => '.tmpl',
    };

ZofCMS config file is just a text file which contains a perl hashref. Note:
the config file will be loaded with C<do>, thus it's perfectly fine to
do something perlish in the config file before having a hashref as the last
thing in the file; that includes the ability to do something like this:

    {
        template_defaults => {
            t => {
                current_time => scalar(localtime),
            },
        },
    }

The config file specifies which pages are "valid" pages for displaying.
Specifies where is your "data" storage (i.e. your <HTML::Template> files)
and your "templates" storage (i.e. your ZofCMS templates). Besides that,
in the config file you can specify some of the default parameters which will
be included in your ZofCMS templates unless you override them (from the
templates). Extra keys in the config files may be introduced by some
plugins (e.g L<App::ZofCMS::Plugin::DBI>). Currently, the following keys
have meaning for ZofCMS core:

=head2 C<data_store>

    {
        data_store => '../zcms_site/data',
    }

The C<data_store> key specifies the directory (relative you C<index.pl>)
with your "data", i.e. the L<HTML::Template> files which you can reference
from ZofCMS templates. More on this in L<App::ZofCMS::Template> documentaion

=head2 C<templates>

    {
        templates => '../zcms_site/templates',
    }

Alike C<data_store>, C<templates> key points to the directory where you
keep your ZofCMS template files which are explained in
L<App::ZofCMS::Template> documentaion. B<Note:> the value of this key is
refered to as "templates dir" in the documentation below.

=head2 C<valid_pages>

    {
        valid_pages => {
            pages   => [
                '/index',
                '/foo/bar/baz',
            ],
            dirs    => [
                '/',
                '/tools/',
                '/tools/ZofCMS/',
            ],
        },
    }

The C<valid_pages> specify which particular pages are available on your
site. If the page provided to C<index.pl> via C<page> and (optionally)
C<dir> parameter does not match C<valid_page> the user will be presented
with a 404 - Not Found page. The C<valid_pages> value is a hashref with
two keys each of which takes an arrayref as an argument; they are explained
a little further below, but first:

=head3 Note on C<page> and C<dir> query parameters

Which page to display in ZofCMS is determined by two query parameters:
C<page> and C<dir>. They are calculated in the following passion:

If C<page> query parameter is not specified it will default to
'index', if C<dir> query parameter is not specified it will default to
C</>. If C<page> query parameter contains a slash (C</>) the C<page>
will be split and the part containing the slash will B<overwrite> anything
that you've set to the C<dir> query parameter. In other words these two
mean the same thing: C<index.pl?page=foo/bar>  C<index.pl?page=bar&dir=foo>.
In fact, the C<index.pl?page=foo/bar> will be transformed into
C<index.pl?page=bar&dir=/foo/> by App::ZofCMS::Config module, note how
the leading and ending slash was appended to the C<dir> automatically.

B<Note:> personally I use Apache's C<mod_rewrite> to "fix" the query,
in other words, the example above the URI can look like 
C<http://example.com/foo/bar>

=head3 C<pages>

    pages   => [
        '/index',
        '/foo/bar/baz',
    ],

The C<pages> key's arrayref contains valid pages, listed one by one.
If we would to take site http://example.com/ running on ZofCMS as an
example, and would specify only
C<< pages => [ '/index', '/foo/bar/baz', ] >> in the config file and would
not specify the C<dirs> key (see below) then the only pages accessible
on the site would be C<http://example.com/> and
C<http://example.com/index.pl?page=foo/bar/baz>. Of course,
C<http://example.com/index.pl?page=index&dir=/> is the same as
C<http://example.com/>, see B<Note on page and dir query parameters>
above.

The way the check on C<pages> is done is:
C<$dir_param . $page_param eq $some_page_in_pages_arrayref>. If all of
pages from C<pages> arrayref failed then the check against C<dirs> is done.

=head3 C<dirs>

    dirs => [
        '/',
        '/tools/',
        '/tools/ZofCMS/',
    ],

The check for valid pages using C<dirs> arrayref is a bit different and
serves as a shortcut of some sort. What is done with the elements in
C<dirs> arrayref is ZofCMS makes a path and a filename in the following
form: $templates_dir (see above) + $dir_param (query parameter C<dir>)
+ $page_param (query parameter C<page>) + C<'.tmpl'> then it checks
if that file exists; if it doesn't - user is presented with 404.

Let's make this information into an example. Let's assume that you have set
your "templates dir" to
C<../zcms_site/templates/>, you didn't set anything for C<pages> key in
C<valid_pages> in your configuration file but you've set
C<< dirs => [ '/tools/' ] >> for C<valid_pages>. On top of all that,
you have created a file C<../zcms_site/templates/tools/stuff.tmpl> which
is the only file in that directory.
If user would go to C<http://example.com/index.pl?page=tools/stuff>,
ZofCMS would interpet C<../zcms_site/templates/tools/stuff.tmpl> template
and display a page, any other pages would give him a 404.

B<Note:> directories specified in C<dirs> arrayref are not recursable, i.e.
specifying C<< dirs => [ '/' ] >>  enable pages in '/tools/'. Later, a
special flag to indicate recursing may be implemented.

=head2 C<template_defaults>

    {
        template_defaults => {
            foo => 'bar',
            t   => {
                top => 'blah',
            },
            d   => {
                foo => 'bar',
            }
            conf    => {
                base    => 'base.tmpl',
            },
            plugins => [ qw/TOC Breadcrumbs/ ],
        },
    }

These are the "defaults" for all of ZofCMS templates of your ZofCMS site.
In other words (refering to the example above) if you don't set key C<foo>
in any of your ZofCMS templates, it will take on its default value C<bar>.

The exception are special keys (which are described in
L<App::ZofCMS::Template>): C<t>, C<d>, C<conf> and C<plugins>, their
B<contents> will act as defaults. In other words, (again refering to the
sample above) if you set C<< t => { foo => 'bar' } >> in your ZofCMS
template, the result will be as if you have set
C<< t => { foo => 'bar', top => 'blah' } >>. Same applies for special keys
C<d>, C<conf> and C<plugins>.

B<Note>: as you will read later, C<plugins> key takes an arrayref, keys of
which may be scalars or hashrefs containing priority numbers. If you
add the same plugin in the template itself and C<template_defaults>, plugin
will be executed only once. If you add the same plugin with different
priority numbers, the priority number set in the template itself will be
used.

=head2 C<dir_defaults>

        dir_defaults => {
            '/' => {
                t => {
                    current_dir => '/',
                }
            },
            '/foos/' => {
                t => {
                    current_dir => '/foos/',
                },
            },
        }

The C<dir_defaults> key functions exactly the same as C<template_defaults>
(see above) with one exception, it's directory-specific. Once again, it
takes a hashref as a value, the keys of that hashref are dirrectories for
which you want to apply the defaults specified as values, which are hashrefs
identical to C<template_defaults>.

By "directory" is ment the C<dir> query parameter that is calculated
as is described in section B<Note on page and dir query parameters>
above.

B<Note:> when specifying the "directory keys", make sure to have the leading
and ending slash (or just one slash if it's a "root" directory),
because that's what the C<dir> query parameter looks like after being
processed.

=head2 C<zcms_template_extension>

    { zcms_template_extension => '.tmpl', }

B<Optional>. The C<zcms_template_extension> key takes a string as an argument. This string
represents the extensions for your ZofCMS Template files. B<Defaults to:> C<.tmpl>

=head1 METHODS

The methods described below can be used either by plugins (see
L<App::ZofCMS::Plugin> or by code
specified in C<exec_before> and C<exec> keys in ZofCMS template, this
is described in L<App::ZofCMS::Template>

=head2 C<cgi>

    my $cgi = $config->cgi;

Takes no arguments, returns a L<CGI> object which is created during
loading of your main config file.

=head2 C<query>

    my $query = $config->query;

    $config->query( { new => 'query', param => 'value' } );

Takes an optional argument which must be a hashref. The keys of this
hashref will appear as if they are query parameters and the values will
appear as if they are values of those parameters by any
plugins/exec_before/exec code which processes query after your call.
Returns a hashref keys of which represent query parameters and values
are obviously values of those parameters. B<Note:> this hashref
is created from L<CGI>'s C<Vars()> function. Refer to L<CGI> documentation
if something doesn't look right.

=head2 C<conf>

    my $conf = $config->conf;
    $config->conf( { data_store => '../zcms_site/data' } );

Returns the hashref of your main config file. Takes one optional argument
which is a hashref, it will be appear as if it was loaded from your
main config file -- bad idea to set it like this, in my opinion.

=head1 AUTHOR

Zoffix Znet, C<< <zoffix at cpan.org> >>
(L<http://zoffix.com>, L<http://haslayout.net>)

=head1 BUGS

Please report any bugs or feature requests to C<bug-app-zofcms at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-ZofCMS>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc App::ZofCMS

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-ZofCMS>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/App-ZofCMS>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/App-ZofCMS>

=item * Search CPAN

L<http://search.cpan.org/dist/App-ZofCMS>

=back

=head1 COPYRIGHT & LICENSE

Copyright 2008 Zoffix Znet, all rights reserved.

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


=cut

