NAME

Mojolicious::Plugin::Yancy - Embed a simple admin CMS into your Mojolicious application

VERSION

version 0.005

SYNOPSIS

    use Mojolicious::Lite;
    plugin Yancy => {
        backend => 'pg://postgres@/mydb',
        collections => { ... },
    };

    ## With custom auth routine
    use Mojo::Base 'Mojolicious';
    sub startup( $app ) {
        my $auth_route = $app->routes->under( '/yancy', sub( $c ) {
            # ... Validate user
            return 1;
        } );
        $app->plugin( 'Yancy', {
            backend => 'pg://postgres@/mydb',
            collections => { ... },
            route => $auth_route,
        });
    }

DESCRIPTION

This plugin allows you to add a simple content management system (CMS) to administrate content on your Mojolicious site. This includes a JavaScript web application to edit the content and a REST API to help quickly build your own application.

METHODS

register

Set up the plugin. Called automatically by Mojolicious.

CONFIGURATION

For getting started with a configuration for Yancy, see "CONFIGURATION" in Yancy.

Additional configuration keys accepted by the plugin are:

route

A base route to add Yancy to. This allows you to customize the URL and add authentication or authorization. Defaults to allowing access to the Yancy web application under /yancy, and the REST API under /yancy/api.

filters

A hash of name => subref pairs of filters to make available. See "yancy.filter.add" for how to create a filter subroutine.

HELPERS

This plugin adds some helpers for use in routes, templates, and plugins.

yancy.backend

    my $be = $c->yancy->backend;

Get the currently-configured Yancy backend object.

yancy.list

    my @items = $c->yancy->list( $collection, \%param, \%opt );

Get a list of items from the backend. $collection is a collection name. \%param is a SQL::Abstract where clause structure. Some basic examples:

    # All people named exactly 'Turanga Leela'
    $c->yancy->list( people => { name => 'Turanga Leela' } );

    # All people with "Wong" in their name
    $c->yancy->list( people => { name => { like => '%Wong%' } } );

\%opt is a hash of options with the following keys:

• limit - The number of rows to return

• offset - The number of rows to skip before returning rows

See your backend documentation for more information about the list method arguments. This helper only returns the list of items, not the total count of items or any other value.

yancy.get

    my $item = $c->yancy->get( $collection, $id );

Get an item from the backend. $collection is the collection name. $id is the ID of the item to get.

yancy.set

    $c->yancy->set( $collection, $id, $item_data );

Update an item in the backend. $collection is the collection name. $id is the ID of the item to update. $item_data is a hash of data to update.

yancy.create

    my $item = $c->yancy->create( $collection, $item_data );

Create a new item. $collection is the collection name. $item_data is a hash of data for the new item.

yancy.delete

    $c->yancy->delete( $collection, $id );

Delete an item from the backend. $collection is the collection name. $id is the ID of the item to delete.

yancy.filter.add

    my $filter_sub = sub( $field_name, $field_value, $field_conf ) { ... }
    $c->yancy->filter->add( $name => $filter_sub );

Create a new filter. $name is the name of the filter to give in the field's configuration. $subref is a subroutine reference that accepts three arguments:

• $field_name - The name of the field being filtered

• $field_value - The value to filter

• $field_conf - The full configuration for the field

For example, here is a filter that will run a password through a one-way hash digest:

    use Digest;
    my $digest = sub( $field_name, $field_value, $field_conf ) {
        my $type = $field_conf->{ 'x-digest' }{ type };
        Digest->new( $type )->add( $field_value )->b64digest;
    };
    $c->yancy->filter->add( 'digest' => $digest );

And you configure this on a field using x-filter and x-digest:

    # mysite.conf
    {
        collections => {
            users => {
                properties => {
                    username => { type => 'string' },
                    password => {
                        type => 'string',
                        format => 'password',
                        'x-filter' => [ 'digest' ], # The name of the filter
                        'x-digest' => {             # Filter configuration
                            type => 'SHA-1',
                        },
                    },
                },
            },
        },
    }

See "CONFIGURATION" in Yancy for more information on how to add filters to fields.

yancy.filter.apply

    my $filtered_data = $c->yancy->filter->apply( $collection, $item_data );

Run the configured filters on the given $item_data. $collection is a collection name. Returns the hash of $filtered_data.

SEE ALSO

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

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

cpanm Yancy

perl -MCPAN -e shell
install Yancy