The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
=head1 NAME

YATT::Lite::WebMVC0::SiteApp - PSGI Handler for yatt

=head1 SYNOPSIS

  # In app.psgi

  use FindBin;
  use YATT::Lite::WebMVC0::SiteApp -as_base;
  use YATT::Lite qw/Entity *CON/;

  return do {

    my $site = MY->new(doc_root => "$FindBin::Bin/html");

    #----- You can define entities here. ----
    Entity session => sub {
      my ($this, $key) = @_;
      my $sess = $CON->get_session
        or return;
      $sess->param($key);
    };

    if (YATT::Lite::Factory->want_object) {

      # When app.psgi is loaded from yatt support scripts(eg. yatt lint),
      # return bare object, not app.

      $site;

    } else {

      # Otherwise, normal PSGI. You can use Plack::Builder and/or middleware.

      $site->to_app;
    }
  };

=head1 DESCRIPTION

C<SiteApp> is a L<Factory|YATT::Lite::Factory>
of L<DirApp|YATT::Lite::WebMVC0::DirApp>, which is a web specific
subclass of L<YATT::Lite>.

SiteApp takes a template directory tree at startup
and becomes a L<PSGI> application.

When SiteApp called for incoming request,
it first determins a sub-directory for the request.
Then SiteApp looks for DirApp from own cache, load/build it when necessary,
and finally invoke DirApp to handle do rest of work.

=head1 CONFIGS

SiteApp accepts L<YATT::Lite::Object> style configurations.

=head2 doc_root

Document root of this PSGI application. F<*.yatt> should be placed under this.
Usually, F<$FindBin::Bin/html>

=head2 app_ns

Namespace of per-directory L<YATT::Lite> class. Default is C<MyApp>.
This will also be used as a base class of each C<YATT::Lite> instances.
This class will be loaded at startup (but can be missing).
If it exists, it must be a subclass of C<YATT::Lite>.

=head2 app_root

The application directory where F<app.psgi> lives in.
Sometime omissible, but recommended to set as C<$FindBin::Bin>.

=head2 app_base

Base DirApp for all DirApp under C<doc_root>.
A.k.a inheritance of app-directory.
Omissible. Usually, F<$FindBin::Bin/ytmpl>.

=head2 site_prefix

If your F<app.psgi> is located under subpath, specify this.
You can refer this from F<*.yatt> via C<&yatt:site_prefix();>.

=head2 header_charset

Default charset for HTTP response headers. Default is utf-8.

=head2 tmpl_encoding, output_encoding

Encoding of F<*.yatt> and HTTP response body, respectively.

XXX: should note about widechars....

=head2 no_nested_query

By default, yatt turns specific parameters into hashes/arrays
like L<PHP|http://www.php.net/manual/en/faq.html.php#faq.html.arrays>
and L<Ruby on Rails|http://guides.rubyonrails.org/action_controller_overview.html#hash-and-array-parameters>.
This feature is useful(I hope), but is experimental.
So if you don't want this feature, turn this config on.

=head2 psgi_static

Requests other than F<*.yatt>, F<*.ytmpl>, F<*.ydo> are passed to this PSGI app.
Default is:

  Plack::App::File->new(root => $self->{cf_doc_root})->to_app


=head2 backend

Room for your Model instance.
If it is given and it has C<startup> method is implemented,
C<< $backend->startup($siteapp, @all_dirapps) >>
will be called when C<prepare_app>.

=head1 METHODS

=head2 call($env)

PSGI entry function. SiteApp uses C<$env> as following:

=over 4

=item PATH_TRANSLATED, REDIRECT_STATUS

If C<< $env->{REDIRECT_STATUS} >> is C<200> and
has non empty C<< $env->{PATH_TRANSLATED} >>,
yatt tries to serve specified path.

=item PATH_INFO

Otherwise, yatt examines C<< $env->{PATH_INFO} >>
under F<doc_root> and F<app_base>, in this order.

=back

=head2 prepare_app

PSGI startup hook.

=head2 render($path_info, $args)

Aid for batch execution.

=head2 make_connection($parent_fh, @config)

Build helper for L<YATT::Lite::WebMVC0::Connection> object.
C<$parent_fh> can be undef.
If specified, C<< $con->flush >> will flush buffered contents to $parent_fh.

=head1 HOOKS

=head2 before_dirhandler($dirapp, $connection, $filename)