=encoding utf8

=head1 NAME

Ado::Manual - Getting started with Ado 

=head1 DESCRIPTION

Ado is a lightweight and reliable base for developing realtime 
web applications with database backend for the enterprise.
Ado is based on L<Mojolicious> and implements many of the 
recommendations from L<Mojolicious::Guides>. 
When in doubt it is recommended to follow these recommendations.

Ado is a tipical Mojo application but it adds some default configuration and
a model layer. An SQLite database is bundled in the distribution at
C<etc/ado.sqlite> to get started quickly. Tables can be accessed and 
manipulated using L<DBI>, L<DBIx::Simple> or any ORM. 
We prefer L<DBIx::Simple::Class> trough L<Mojolicious::Plugin::DSC>.
L<DBIx::Simple::Class> is a simple OM that provides representation 
of table records as plain Perl objects.                                   

=head1 INSTALLATION

Ado is meant to be installed into a folder of your choice.
It can go into the C<site> folder of your B<I<non-system Perl distro>> but
better install it in its own folder.

We do not recommend using Ado with your system Perl!
Get a precompiled Perl distro like "Citrus Perl" 
(L<http://www.citrusperl.com/download.html>) or
"ActivePerl Community Edition"
(L<http://www.activestate.com/activeperl/downloads>) for your OS, 
or build your own using L<App::perlbrew>.

Ado can be downloaded from CPAN L<http://search.cpan.org/dist/Ado/>
or installed via the C<cpan> commandline tool.
To install manually Ado after downloading, run the following commands:

  tar -zxf Ado-X.XX.tar.gz
  cd Ado-X.XX/
  perl Build.PL --install_base $HOME/path/to/ado
  #if run without --install_base $HOME/opt/ado will be suggested
  ./Build
  ./Build installdeps
  ./Build test
  ./Build install

=head1 SUPPORT AND DOCUMENTATION

After installing, you can find documentation with the
perldoc command.  

    perldoc Ado
    perldoc Ado::Manual #this page

To use c<perldoc> for reading documentation you need to add 
the full path to L<Ado> C<lib/> directory to C<PERL5LIB> environment variable.
For better experience run the B<C<ado>> application and read the documentation
from your browser.

  $HOME/opt/ado/bin/ado daemon

Go to http:/localhost:3000/perldoc

You can report bugs and suggest features at L<http://github.com/kberov/Ado/issues>.
Bugs will be considered and fixed as time permits.
Feel invited to make pull requests for your contributions.

=head1 CONTRIBUTING

Generally the rules outlined in L<Mojolicious::Guides::Contributing>
apply for L<Ado> too.
For specific to Ado rules see L<Ado::Manual::Contributing>.


=head1 REST API

Ado strives for strict separation of concerns. The best way to achieve 
this is to fully separate the client code from the server code. 
Ado is ideally suited for the purpose thanks to
L<Mojolicious>. Every resource is accessible via the REST API.
We follow closely and elaborate on the recommendations in
"RESTful Service Best Practices" 
at L<www.RestApiTutorial.com>. See L<Ado::Manual::RESTAPI>.

=head1 PLUGINS

One way to contribute to L<Ado> is by writing plugins.
They work the same way as L<Mojolicious::Plugins> and share 
the same common base trough L<Ado::Plugin>.
Ado plugins have one small additional feature. 
They can store separately their own configuration in
C<$ENV{MOJO_HOME}/etc/plugins/plugin_name.conf>.
Business-specific applications for an Ado-based system 
are usually implemented as plugins.
See L<Ado::Manual::Plugins> and L<Ado::Plugin> 
for more information.

=head1 SEE ALSO


L<Ado>, L<Mojolicious::Guides>, 
L<Mojolicious::Guides::Contributing>,
L<Module::Build::Cookbook/prefix_vs_install_base>, 
L<http://www.thefreedictionary.com/ado>.


=head1 AUTHOR

Красимир Беров (Krasimir Berov)

=head1 COPYRIGHT AND LICENSE

Copyright 2013 Красимир Беров (Krasimir Berov).

This program is free software, you can redistribute it and/or
modify it under the terms of the 
GNU Lesser General Public License v3 (LGPL-3.0).
You may copy, distribute and modify the software provided that 
modifications are open source. However, software that includes 
the license may release under a different license.

See http://opensource.org/licenses/lgpl-3.0.html for more information.

