The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Yancy-1.088
River stage one • 3 direct dependents • 3 total dependents
43 ++
/ Yancy::Guides::Tutorial

NAME

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

VERSION

version 1.088

DESCRIPTION

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

Admin App

Yancy provides an application to edit content at the path /yancy on your website. Yancy can manage data in multiple databases using different backend modules. 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:

Postgres

PostgreSQL is supported through the 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' );

MySQL

MySQL is supported through the 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' );

SQLite

SQLite is supported through the 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:' );

DBIx::Class

If you have a 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' );

Content Tools

Schema Information and Validation

Yancy scans your database to determine what kind of data is inside, but Yancy also accepts a JSON Schema 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 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',
                    },
                },
            },
        };

Data Helpers

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 "HELPERS" in Mojolicious::Plugin::Yancy 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,
        );
    };

Forms

The 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 Yancy::Plugin::Form::Bootstrap4 module, Yancy can create forms using Twitter Bootstrap 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' )

Controllers

Yancy can add basic CRUD operations without writing the code yourself. The 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' )

Plugins

Yancy also has plugins for...

More development will be happening here soon!

AUTHOR

Doug Bell <preaction@cpan.org>

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.