NAME

Mojolicious::Plugin::DBIC::Controller::DBIC - Build simple views to DBIC data

VERSION

version 0.005

SYNOPSIS

use Mojolicious::Lite;
plugin DBIC => { schema => ... };
get '/', {
    controller => 'DBIC',
    action => 'list',
    resultset => 'BlogPosts',
    template => 'blog/list',
};

DESCRIPTION

This controller allows for easy working with data from the schema. Controllers are configured through the stash when setting up the routes.

METHODS

list

get '/', {
    controller => 'DBIC',
    action => 'list',
    resultset => 'BlogPosts',
    template => 'blog/list',
};

List data in a ResultSet. Returns false if it has rendered a response, true if dispatch can continue.

This method uses the following stash values for configuration:

resultset

The DBIx::Class::ResultSet class to list.

This method sets the following stash values for template rendering:

resultset

The DBIx::Class::ResultSet object containing the desired objects.

limit

The number of items to show on the page. Defaults to 10.

page

The page number to show. Defaults to 1.

order_by

Set the default order for the items. Supports any DBIx::Class order_by structure.

Query Params

The following URL query parameters are allowed for this method:

$page

Instead of using the page stash value, you can use the $page query paremeter to set the page.

$offset

Instead of using the page stash value, you can use the $offset query parameter to set the page offset. This is overridden by the $page query parameter.

$limit

Instead of using the limit stash value, you can use the $limit query parameter to allow users to specify their own page size.

$order_by

One or more fields to order by. Can be specified as <name> or asc:<name> to sort in ascending order or desc:<field> to sort in descending order.

get

get '/blog/:id', {
    controller => 'DBIC',
    action => 'get',
    resultset => 'BlogPosts',
    template => 'blog/get',
};

Fetch a single result by its ID. If no result is found, renders a not found error. Returns false if it has rendered a response, true if dispatch can continue.

This method uses the following stash values for configuration:

resultset

The DBIx::Class::ResultSet class to use.

id

The ID to pass to "find" in DBIx::Class::ResultSet.

This method sets the following stash values for template rendering:

row

The DBIx::Class::Row object containing the desired object.

set

$routes->any( [ 'GET', 'POST' ] => '/:id/edit' )->to(
    'DBIC#set',
    resultset => $resultset_name,
    template => $template_name,
);

$routes->any( [ 'GET', 'POST' ] => '/create' )->to(
    'DBIC#set',
    resultset => $resultset_name,
    template => $template_name,
    forward_to => $route_name,
);

This route creates a new item or updates an existing item in a collection. If the user is making a GET request, they will simply be shown the template. If the user is making a POST or PUT request, the form parameters will be read, and the user will either be shown the form again with the result of the form submission (success or failure) or the user will be forwarded to another place.

This method uses the following stash values for configuration:

resultset

The resultset to use. Required.

id

The ID of the item from the collection. Optional: If not specified, a new item will be created. Usually part of the route path as a placeholder.

template

The name of the template to use. See "Renderer" in Mojolicious::Guides::Rendering for how template names are resolved.

forward_to

The name of a route to forward the user to on success. Optional. Any route placeholders that match item field names will be filled in.

$routes->get( '/:id/:slug' )->name( 'blog.view' );
$routes->post( '/create' )->to(
    'DBIC#set',
    resultset => 'blog',
    template => 'blog_edit.html.ep',
    forward_to => 'blog.view',
);

# { id => 1, slug => 'first-post' }
# forward_to => '/1/first-post'

Forwarding will not happen for JSON requests.

properties

Restrict this route to only setting the given properties. An array reference of properties to allow. Trying to set additional properties will result in an error.

NOTE: Unless restricted to certain properties using this configuration, this method accepts all valid data configured for the collection. The data being submitted can be more than just the fields you make available in the form. If you do not want certain data to be written through this form, you can prevent it by using this.

The following stash values are set by this method:

row

The DBIx::Class::Row that is being edited, if the id is given. Otherwise, the item that was created.

error

A scalar containing the exception thrown by the insert/update.

Each field in the item is also set as a param using "param" in Mojolicious::Controller so that tag helpers like text_field will be pre-filled with the values. See Mojolicious::Plugin::TagHelpers for more information. This also means that fields can be pre-filled with initial data or new data by using GET query parameters.

This method is protected by Mojolicious's Cross-Site Request Forgery (CSRF) protection. CSRF protection prevents other sites from tricking your users into doing something on your site that they didn't intend, such as editing or deleting content. You must add a <%= csrf_field %> to your form in order to delete an item successfully. See "Cross-site request forgery" in Mojolicious::Guides::Rendering.

Displaying a form could be done as a separate route using the dbic#get method, but with more code:

$routes->get( '/:id/edit' )->to(
    'DBIC#get',
    resultset => $resultset_name,
    template => $template_name,
);
$routes->post( '/:id/edit' )->to(
    'DBIC#set',
    resultset => $resultset_name,
    template => $template_name,
);

delete

$routes->any( [ 'GET', 'POST' ], '/delete/:id' )->to(
    'DBIC#delete',
    resultset => $resultset_name,
    template => $template_name,
    forward_to => $route_name,
);

This route deletes a row from a ResultSet. If the user is making a GET request, they will simply be shown the template (which can be used to confirm the delete). If the user is making a POST or DELETE request, the row will be deleted and the user will either be shown the form again with the result of the form submission (success or failure) or the user will be forwarded to another place.

This method uses the following stash values for configuration:

resultset

The ResultSet class to use. Required.

id

The ID of the row from the table. Required. Usually part of the route path as a placeholder.

template

The name of the template to use. See "Renderer" in Mojolicious::Guides::Rendering for how template names are resolved.

forward_to

The name of a route to forward the user to on success. Optional. Forwarding will not happen for JSON requests.

The following stash values are set by this method:

row

The row that will be deleted. If displaying the form again after the row is deleted, this will be undef.

This method is protected by Mojolicious's Cross-Site Request Forgery (CSRF) protection. CSRF protection prevents other sites from tricking your users into doing something on your site that they didn't intend, such as editing or deleting content. You must add a <%= csrf_field %> to your form in order to delete an item successfully. See "Cross-site request forgery" in Mojolicious::Guides::Rendering.

SEE ALSO

Mojolicious::Plugin::DBIC

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 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 Mojolicious::Plugin::DBIC

perl -MCPAN -e shell
install Mojolicious::Plugin::DBIC