# PODNAME: Yancy::Guides::Tutorial
# ABSTRACT: Yancy's First Steps

__END__

=pod

=head1 NAME

Yancy::Guides::Tutorial - Yancy's First Steps

=head1 VERSION

version 1.081

=head1 DESCRIPTION

L<Yancy> is a content management system (CMS) for L<Mojolicious>.  It
includes an admin application to edit content and tools to quickly build
an application.

=head2 Admin App

Yancy provides an application to edit content at the path C</yancy> on
your website. Yancy can manage data in multiple databases using
different L<backend modules|Yancy::Backend>. You can provide a URL
string to tell Yancy how to connect to your database, or you can provide
your database object.  Yancy supports the following databases:

=head3 Postgres

L<PostgreSQL|http://postgresql.org> is supported through the L<Mojo::Pg>
module.

    # PostgreSQL: A Mojo::Pg connection string
    plugin Yancy => backend => 'postgresql://postgres@/test';

    # PostgreSQL: A Mojo::Pg object
    plugin Yancy => backend => Mojo::Pg->new( 'postgresql://postgres@/test' );

=head3 MySQL

L<MySQL|http://mysql.com> is supported through the L<Mojo::mysql>
module.

    # MySQL: A Mojo::mysql connection string
    plugin Yancy => backend => 'mysql://user@/test';

    # MySQL: A Mojo::mysql object
    plugin Yancy => backend => Mojo::mysql->strict_mode( 'mysql://user@/test' );

=head3 SQLite

L<SQLite|http://sqlite.org> is supported through the L<Mojo::SQLite> module.
This is a good option if you want to try Yancy out.

    # SQLite: A Mojo::SQLite connection string
    plugin Yancy => backend => 'sqlite:test.db';

    # SQLite: A Mojo::SQLite object
    plugin Yancy => backend => Mojo::SQLite->new( 'sqlite::temp:' );

=head3 DBIx::Class

If you have a L<DBIx::Class> schema, Yancy can use it to edit the content.

    # DBIx::Class: A connection string
    plugin Yancy => backend => 'dbic://My::Schema/dbi:SQLite:test.db';

    # DBIx::Class: A DBIx::Class::Schema object
    plugin Yancy => backend => My::Schema->connect( 'dbi:SQLite:test.db' );

=head2 Content Tools

=head3 Schema Information and Validation

Yancy scans your database to determine what kind of data is inside, but
Yancy also accepts a L<JSON Schema|http://json-schema.org> to add more
information about your data. You can add descriptions, examples, and
other documentation that will appear in the admin application. You can
also add type, format, and other validation information, which Yancy
will use to validate input from users. See L<Yancy::Guides::Schema>
for how to define your schema.

    plugin Yancy => backend => 'postgres://postgres@/test',
        schema => {
            employees => {
                title => 'Employees',
                description => 'Our crack team of loyal dregs.',
                properties => {
                    address => {
                        description => 'Where to notify next-of-kin.',
                        # Regexp to validate this field
                        pattern => '^\d+ \S+',
                    },
                    email => {
                        # Use the browser's native e-mail input
                        format => 'email',
                    },
                },
            },
        };

=head3 Data Helpers

L<Mojolicious::Plugin::Yancy> provides helpers to work with your database content.
These use the validations provided in the schema to validate user input. These
helpers can be used in your route handlers to quickly add basic Create, Read, Update,
and Delete (CRUD) functionality. See L<Mojolicious::Plugin::Yancy/HELPERS> for a list
of provided helpers.

    # View a list of blog entries
    get '/' => sub( $c ) {
        my @blog_entries = $c->yancy->list(
            blog_entries =>
            { published => 1 },
            { order_by => { -desc => 'published_date' } },
        );
        $c->render(
            'blog_list',
            items => \@blog_entries,
        );
    };

    # View a single blog entry
    get '/blog/:blog_entry_id' => sub( $c ) {
        my $blog_entry = $c->yancy->get(
            blog_entries => $c->param( 'blog_entry_id' ),
        );
        $c->render(
            'blog_entry',
            item => $blog_entry,
        );
    };

=head3 Forms

The L<Yancy::Plugin::Form> plugin can generate input fields or entire
forms based on your schema information. The annotations in your schema
appear in the forms to help users fill them out. Additionally, with the
L<Yancy::Plugin::Form::Bootstrap4> module, Yancy can create forms using
L<Twitter Bootstrap|http://getbootstrap.com> components.

    # Load the form plugin
    app->yancy->plugin( 'Form::Bootstrap4' );

    # Edit a blog entry
    any [ 'GET', 'POST' ], '/edit/:blog_entry_id' => sub( $c ) {
        if ( $c->req->method eq 'GET' ) {
            my $blog_entry = $c->yancy->get(
                blog_entries => $c->param( 'blog_entry_id' ),
            );
            return $c->render(
                'blog_entry',
                item => $blog_entry,
            );
        }
        my $id = $c->param( 'blog_entry_id' );
        my $item = $c->req->params->to_hash;
        delete $item->{csrf_token}; # See https://docs.mojolicious.org/Mojolicious/Guides/Rendering#Cross-site-request-forgery
        $c->yancy->set( blog_entries => $id, $c->req->params->to_hash );
        $c->redirect_to( '/blog/' . $id );
    };

    __DATA__
    @@ blog_form.html.ep
    %= $c->yancy->form->form_for( 'blog_entries', item => stash 'item' )

=head3 Controllers

Yancy can add basic CRUD operations without writing the code yourself. The
L<Yancy::Controller::Yancy> module uses the schema information to show, search,
edit, create, and delete database items.

    # A rewrite of the routes above to use Yancy::Controller::Yancy

    # View a list of blog entries
    get '/' => {
        controller => 'yancy',
        action => 'list',
        schema => 'blog_entries',
        filter => { published => 1 },
        order_by => { -desc => 'published_date' },
    } => 'blog.list';

    # View a single blog entry
    get '/blog/:blog_entry_id' => {
        controller => 'yancy',
        action => 'get',
        schema => 'blog_entries',
    } => 'blog.get';

    # Load the form plugin
    app->yancy->plugin( 'Form::Bootstrap4' );

    # Edit a blog entry
    any [ 'GET', 'POST' ], '/edit/:blog_entry_id' => {
        controller => 'yancy',
        action => 'set',
        schema => 'blog_entries',
        template => 'blog_form',
        redirect_to => 'blog.get',
    } => 'blog.edit';

    __DATA__
    @@ blog_form.html.ep
    %= $c->yancy->form->form_for( 'blog_entries' )

=head3 Plugins

Yancy also has plugins for...

=over

=item * User authentication: L<Yancy::Plugin::Auth>

=item * File management: L<Yancy::Plugin::File>

=back

More development will be happening here soon!

=head1 AUTHOR

Doug Bell <preaction@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Doug Bell.

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

=cut