Yancy::Controller::Yancy - Basic controller for displaying content
version 1.036
use Mojolicious::Lite; plugin Yancy => { schema => { blog => { properties => { id => { type => 'integer' }, title => { type => 'string' }, html => { type => 'string' }, }, }, }, }; app->routes->get( '/' )->to( 'yancy#list', schema => 'blog', template => 'index', ); __DATA__ @@ index.html.ep % for my $item ( @{ stash 'items' } ) { <h1><%= $item->{title} %></h1> <%== $item->{html} %> % }
This controller contains basic route handlers for displaying content configured in Yancy schema. These route handlers reduce the amount of code you need to write to display or modify your content.
Route handlers use the Mojolicious stash for configuration. These values can be set at route creation, or by an under route handler.
stash
under
Using these route handlers also gives you a built-in JSON API for your website. Any user agent that requests JSON will get JSON instead of HTML. For full details on how JSON clients are detected, see "Content negotiation" in Mojolicious::Guides::Rendering.
$routes->get( '/' )->to( 'yancy#list', schema => $schema_name, template => $template_name, );
This method is used to list content.
This method uses the following stash values for configuration:
The schema to use. Required.
The name of the template to use. See "Renderer" in Mojolicious::Guides::Rendering for how template names are resolved. Defaults to yancy/table.
yancy/table
The number of items to show on the page. Defaults to 10.
10
The page number to show. Defaults to 1. The page number will be used to calculate the offset parameter to "list" in Yancy::Backend.
1
offset
A hash reference of field/value pairs to filter the contents of the list or a subref that generates this hash reference. The subref will be passed the current controller object ($c).
$c
This overrides any query filters and so can be used to enforce authorization / security.
Set the default order for the items. Supports any "list" in Yancy::Backend order_by structure.
order_by
The following stash values are set by this method:
An array reference of items to display.
The number of pages of items. Can be used for pagination.
The following URL query parameters are allowed for this method:
Instead of using the page stash value, you can use the $page query paremeter to set the page.
page
$page
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.
$offset
Instead of using the limit stash value, you can use the $limit query parameter to allow users to specify their own page size.
limit
$limit
One or more fields to order by. Must be specified as asc:<name> to sort in ascending order or desc:<field> to sort in descending order.
asc:<name>
desc:<field>
Any named query parameter that matches a field in the schema will be used to further filter the results. The stash filter will override this filter, so that the stash filter can be used for security.
filter
$routes->get( '/:id' )->to( 'yancy#get', schema => $schema_name, template => $template_name, );
This method is used to show a single item.
The ID of the item from the schema. Required. Usually part of the route path as a placeholder.
The name of the template to use. See "Renderer" in Mojolicious::Guides::Rendering for how template names are resolved.
The item that is being displayed.
$routes->any( [ 'GET', 'POST' ] => '/:id/edit' )->to( 'yancy#set', schema => $schema_name, template => $template_name, ); $routes->any( [ 'GET', 'POST' ] => '/create' )->to( 'yancy#set', schema => $schema_name, template => $template_name, forward_to => $route_name, );
This route creates a new item or updates an existing item in a schema. 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, the data will be validated against the schema configuration, 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.
GET
POST
PUT
If the POST or PUT request content type is application/json, the request body will be treated as a JSON object to create/set. In this case, the form query parameters are not used.
application/json
The ID of the item from the schema. Optional: If not specified, a new item will be created. Usually part of the route path as a placeholder.
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( 'yancy#set', schema => '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.
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 schema. 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 item that is being edited, if the id is given. Otherwise, the item that was created.
id
An array of hash references of errors that occurred during data validation. Each hash reference is either a JSON::Validator::Error object or a hash reference with a message field. See the yancy.validate helper docs and "validate" in JSON::Validator for more details.
message
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.
text_field
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.
<%= csrf_field %>
Displaying a form could be done as a separate route using the yancy#get method, but with more code:
yancy#get
$routes->get( '/:id/edit' )->to( 'yancy#get', schema => $schema_name, template => $template_name, ); $routes->post( '/:id/edit' )->to( 'yancy#set', schema => $schema_name, template => $template_name, );
$routes->any( [ 'GET', 'POST' ], '/delete/:id' )->to( 'yancy#delete', schema => $schema_name, template => $template_name, forward_to => $route_name, );
This route deletes an item from a schema. 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 item 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.
DELETE
The name of a route to forward the user to on success. Optional. Forwarding will not happen for JSON requests.
The item that will be deleted. If displaying the form again after the item is deleted, this will be undef.
undef
Here are some tips for inheriting from this controller to add functionality.
When setting field values to add to the updated/created item, use $c->req->param not $c->param. The underlying code uses $c->req->param to get all of the params, which will not be updated if you use $c->param.
$c->req->param
$c->param
If you get a 404 Not Found response or Mojolicious's "Page not found... yet!" page, it could be from one of a few reasons:
404 Not Found
Check to make sure that your routes match the URL.
Make sure the template is configured and named correctly and the correct format and renderer are being used.
The Mojolicious debug log will have more information. Make sure you are logging at debug level by running in development mode (the default), or setting the MOJO_LOG_LEVEL environment variable to debug. See MODE in the Mojolicious tutorial for more information.
debug
development
MOJO_LOG_LEVEL
The default list template. Uses the following additional stash values for configuration:
list
An array reference of columns to display in the table. The same as x-list-columns in the schema configuration. Defaults to x-list-columns in the schema configuration or all of the schema's columns in x-order order. See "Extended Collection Configuration" in Yancy::Help::Config for more information.
x-list-columns
x-order
get '/events' => ( controller => 'yancy', action => 'list', table => { thead => 0, # Disable column headers class => 'table table-responsive', # Add a class }, );
Attributes for the table tag. A hash reference of the following keys:
Whether or not to display the table head section, which contains the column headings. Defaults to true (1). Set to false (0) to disable <thead>.
0
<thead>
Show filter input boxes for each column in the header. Pressing Enter will filter the table.
Enter
The ID of the table element.
The class(s) of the table element.
Yancy
Doug Bell <preaction@cpan.org>
This software is copyright (c) 2019 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.
To install Yancy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Yancy
CPAN shell
perl -MCPAN -e shell install Yancy
For more information on module installation, please visit the detailed CPAN module installation guide.