Giter VIP home page Giter VIP logo

yancy's Introduction

Build Status Coverage Status

NAME

Yancy - The Best Web Framework Deserves the Best CMS

VERSION

version 1.069

SYNOPSIS

# Mojolicious
$self->plugin( Yancy => backend => 'postgresql://postgres@/mydb' );

# Mojolicious::Lite
plugin Yancy => backend => 'postgresql://postgres@/mydb'; # mysql, sqlite, dbic...

# Secure access to the admin UI with Basic authentication
my $under = $app->routes->under( '/yancy', sub( $c ) {
    return 1 if $c->req->url->to_abs->userinfo eq 'Bender:rocks';
    $c->res->headers->www_authenticate('Basic');
    $c->render(text => 'Authentication required!', status => 401);
    return undef;
});
$self->plugin( Yancy => backend => 'postgresql://postgres@/mydb', route => $under );

# ... then load the editor at http://127.0.0.1:3000/yancy

DESCRIPTION

Screenshot of list of Futurama characters
Screenshot of editing form for a person

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 "Schema" in Yancy::Help::Config 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!

GUIDES

For in-depth documentation on Yancy, see the following guides:

OTHER RESOURCES

Example Applications

The Yancy Git repository on Github includes some example applications you can use to help build your own websites. View the example application directory.

BUNDLED PROJECTS

This project bundles some other projects with the following licenses:

  • jQuery (version 3.2.1) Copyright JS Foundation and other contributors (MIT License)
  • Bootstrap (version 4.3.1) Copyright 2011-2019 the Bootstrap Authors and Twitter, Inc. (MIT License)
  • Popper.js (version 1.13.0) Copyright 2017 Federico Zivolo (MIT License)
  • FontAwesome (version 4.7.0) Copyright Dave Gandy (SIL OFL 1.1 and MIT License)
  • Vue.js (version 2.5.3) Copyright 2013-2018, Yuxi (Evan) You (MIT License)
  • marked (version 0.3.12) Copyright 2011-2018, Christopher Jeffrey (MIT License)

The bundled versions of these modules may change. If you rely on these in your own app, be sure to watch the changelog for version updates.

SEE ALSO

Mojolicious

AUTHOR

Doug Bell [email protected]

CONTRIBUTORS

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 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.

yancy's People

Contributors

mohawk2 avatar wbazant avatar manwar avatar lindleyw avatar uniejo avatar borisdaeppen avatar joshrabinowitz avatar rmallah avatar

Watchers

James Cloos avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.