=encoding utf8
 
=head1 NAME
 
PEF::Front - B<P>erl B<E>ffective Web B<F>ramework
 
=head1 SYNOPSIS
 
  # startup.pl
  use MyApp::AppFrontConfig;
  use PEF::Front::Preload qw(no_db_connect);
  use PEF::Front::Route ('/' => '/appIndex');
  
  PEF::Front::Route->to_app();
 
  # MyApp::AppFrontConfig.pm
  package MyApp::AppFrontConfig;
  sub cfg_no_nls { 1 }
  sub cfg_no_multilang_support { 1 }
  
  1;
  
  # $project_dir/templates/index.html
  some Template-Toolkit style template.

=head1 DESCRIPTION

PEF::Front is a Perl web framework with following features.

=over

=item B<Easy in development>

You just write API of your application and it's automatically exposed as AJAX
or data retrieving methods in your templates. HTML templates can be programmed
separately.

=item B<Fast and versatile template engine>

HTML templates can be programmed by other people who know nothing about Perl.

=item B<Explicit model methods description>

Your API calls are described in YAML files. There're can be set default 
values, complex parameter checks, input parameter filters, output filters
and other things.

HTML/AJAX developer can look into these YAML files to understand backend API.

=item B<Safe>

Thanks very comprehensive parameter checks, passed into handler request is
already checked and filtered, you don't need to make additional validation.

=item B<Flexible rules>

Different output filters can be applied to the same data to get different 
data representation. Input data can be obtained automatically from session,
headers, cookies, form and other sources. Results from handlers can set or 
unset headers or cookies. All this is described in YAML and all these 
rules are compiled into native Perl code.

=item B<Routing>

Request routing is very powerful and effective. Your routing rules are 
compiled into native Perl code.

=item B<Highly configurable>

There're many configurable parameters and functions. They have some sensible
defaults that you have to configure only small part of them. It's very easy
to configure them in your own *::AppFrontConfig module. 

=item B<PSGI>

PSGI is very effective protocol for passing incoming requests into 
application. You can use PEF::Front with any PSGI-server. 
I use L<uwsgi|https://uwsgi-docs.readthedocs.io/en/latest/PSGIquickstart.html>. 
It is also very wise to have some reverse-proxy server in front of 
PSGI-server for static content. I use L<Nginx|https://www.nginx.com/>.

=item B<More productive out of the box>

PEF::Front has many components that a really useful for typical web 
applications:

=over

=item Sessions

Session data can be automatically loaded during request validation.

=item Oauth2

There're components to easily make authorization on your site for B<Facebook>, 
B<GitHub>, B<Google>, B<LinkedIn>, B<MSN>, B<PayPal>, B<Vkontakte> 
and B<Yandex> users.

=item Localization support

There's a message translation support in templates and handlers and 
automatic language detection based on URL, HTTP headers and Geo IP.

=item Captcha

Captcha check during request validation. Simple captcha component. Custom
captcha image generation is possible.

=back

=item B<Websockets and Server Sent Events>

Basically these technologies require some event loop architecture to 
reduce overhead on every connection. But it requires non-trivial callback
code for series of complex queries to DB. 
It is possible to make in quite "usual" code using L<Coro> + L<AnyEvent> 
environment with L<DBIx::Connection::Pool> for pool of asynchronous 
L<DBIx::Connector>s. Thre's even L<DBIx::Struct> ORM that supports 
such a pool of connectors. 

B<Websockets and Server Sent Events> are available as external modules.

=back

=head1 Your Application

=head2 Project structure

Typical directory structure of Your application is alike:

    + $project_dir/
      + $app/
        + $Project/
          - AppFrontConfig.pm
          + InFilter/
          + OutFilter/
          + Local/
      + bin/
        - startup.pl
      + model/
      + templates/
      + var/
        + cache/
        + captcha-db/
        + tt_cache/
        + upload/
      + www-static/
        + captchas/
        + images/
        + jss/
        + styles/

You can redefine almost everything here except B<InFilter>, B<OutFilter> 
and B<Local> directories.

=head3 What is what

=over

=item bin 

Different executables. startup.pl is one of them. Actually this file can have
any name that is known to PSGI-server.

=item $app

Directory of main application code and AppFrontConfig.pm module. Framework 
determines it automatically from path to loaded AppFrontConfig.pm module.

=item $Project

Directory structure of application modules.

=item InFilter

Optional modules for input data validation.

=item OutFilter

Optional modules for transformation of output data.

=item Local

Incoming request handlers. 

=item model

YAML-files with descriptions of model methods. Every file describes one method.

=item templates

Directory of templates. Currently only Template-Toolkit style is supported.

=item var/cache

Session data and cached responses of handlers. 
 
=item var/captcha-db

Database for generated captchas.

=item var/tt_cache

Cache of compiled templates.

=item var/upload

Root directory for uploaded files.

=item www-static

Directory of static content. This is typically served by some fast web-server 
like L<Nginx|https://www.nginx.com/>.

=item www-static/captchas

Directory of generated captcha images. This is typically served by the same 
web-server for static content.

=back

=head2 Minimal application

Minimal application can consist of only two files: B<AppFrontConfig.pm>
and B<setup.pl>. 

It would look like this:

  # MyApp::AppFrontConfig.pm
  package MyApp::AppFrontConfig;
  sub cfg_no_nls { 1 }
  sub cfg_no_multilang_support { 1 }
  
  1;

  # startup.pl
  use MyApp::AppFrontConfig;
  use PEF::Front::Response;
  use PEF::Front::Route;
  
  PEF::Front::Route::add_route(
   get '/' => sub {
      PEF::Front::Response->new(headers => ['Content-Type' => 'text/plain'], body => 'Hello World!');
    }
  );
  
  PEF::Front::Route->to_app();
 
You have to define minimal config and routes. Routes can return HTTP response directly. 

=head1 More information

There're guides and demos. 

=over

=item L<Quick-Start guide|PEF::Front::Guide::QuickStart>

=item L<Configuration parameters|PEF::Front::Config>

=item L<Model methods description|PEF::Front::Model>

=item L<Routing of incoming requests|PEF::Front::Route>

=item L<Template processing|PEF::Front::RenderTT>

=back

=head1 AUTHOR
 
This module was written and is maintained by Anton Petrusevich.

=head1 Copyright and License
 
Copyright (c) 2016 Anton Petrusevich. Some Rights Reserved.
 
This module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.

=cut