File Coverage

blib/lib/Yancy/Controller/Yancy.pm

Criterion	Covered	Total	%
statement	252	257	98.0
branch	79	88	89.7
condition	70	93	75.2
subroutine	25	25	100.0
pod	8	8	100.0
total	434	471	92.1

package Yancy::Controller::Yancy;
our $VERSION = '1.086';
# ABSTRACT: Basic controller for displaying content

#pod =head1 SYNOPSIS
#pod
#pod     use Mojolicious::Lite;
#pod     plugin Yancy => {
#pod         schema => {
#pod             blog => {
#pod                 properties => {
#pod                     id => { type => 'integer' },
#pod                     title => { type => 'string' },
#pod                     html => { type => 'string' },
#pod                 },
#pod             },
#pod         },
#pod     };
#pod
#pod     app->routes->get( '/' )->to(
#pod         'yancy#list',
#pod         schema => 'blog',
#pod         template => 'index',
#pod     );
#pod
#pod     __DATA__
#pod     @@ index.html.ep
#pod     % for my $item ( @{ stash 'items' } ) {
#pod         <%= $item->{title} %>
#pod         <%== $item->{html} %>
#pod     % }
#pod
#pod =head1 DESCRIPTION
#pod
#pod This controller contains basic route handlers for displaying content
#pod configured in Yancy schema. These route handlers reduce the amount
#pod of code you need to write to display or modify your content.
#pod
#pod Route handlers use the Mojolicious C for configuration. These values
#pod can be set at route creation, or by an C route handler.
#pod
#pod Using these route handlers also gives you a built-in JSON API for your
#pod website. Any user agent that requests JSON will get JSON instead of
#pod HTML. For full details on how JSON clients are detected, see
#pod L.
#pod
#pod =head1 ACTION HOOKS
#pod
#pod Every action can call one or more of your application's
#pod L.
#pod These helpers can change the item before it is displayed or
#pod before it is saved to the database.
#pod
#pod These helpers get one argument: An item being displayed, created, saved,
#pod or deleted. The helper then returns the item to be displayed, created,
#pod or saved.
#pod
#pod     use Mojolicious::Lite -signatures;
#pod     plugin Yancy => { ... };
#pod
#pod     # Set a last_updated timestamp when creating or updating events
#pod     helper update_timestamp => sub( $c, $item ) {
#pod         $item->{last_updated} = time;
#pod         return $item;
#pod     };
#pod     post '/event/:event_id' => 'yancy#set',
#pod         {
#pod             event_id => undef,
#pod             schema => 'events',
#pod             helpers => [ 'update_timestamp' ],
#pod             forward_to => 'events.get',
#pod         },
#pod         'events.set';
#pod
#pod Helpers can also be anonymous subrefs for those times when you want a
#pod unique behavior for a single route.
#pod
#pod     # Format the last_updated timestamp when showing event details
#pod     use Time::Piece;
#pod     get '/event/:event_id' => 'yancy#get',
#pod         {
#pod             schema => 'events',
#pod             helpers => [
#pod                 sub( $c, $item ) {
#pod                     $item->{last_updated} = Time::Piece->new( $item->{last_updated} );
#pod                     return $item;
#pod                 },
#pod             ],
#pod         },
#pod         'events.get';
#pod
#pod =head1 EXTENDING
#pod
#pod Here are some tips for inheriting from this controller to add
#pod functionality.
#pod
#pod =over
#pod
#pod =item set
#pod
#pod =over
#pod
#pod =item *
#pod
#pod When setting field values to add to the updated/created item, use C<<
#pod $c->req->param >> not C<< $c->param >>. The underlying code uses C<<
#pod $c->req->param >> to get all of the params, which will not be updated if
#pod you use C<< $c->param >>.
#pod
#pod =back
#pod
#pod =back
#pod
#pod =head1 DIAGNOSTICS
#pod
#pod =over
#pod
#pod =item Page not found
#pod
#pod If you get a C<404 Not Found> response or Mojolicious's "Page not found... yet!" page,
#pod it could be from one of a few reasons:
#pod
#pod =over
#pod
#pod =item No route with the given path was found
#pod
#pod Check to make sure that your routes match the URL.
#pod
#pod =item Configured template not found
#pod
#pod Make sure the template is configured and named correctly and the correct format
#pod and renderer are being used.
#pod
#pod =back
#pod
#pod The Mojolicious debug log will have more information. Make sure you are
#pod logging at C level by running in C mode (the
#pod default), or setting the C environment variable to
#pod C. See L
#pod tutorial|Mojolicious::Guides::Tutorial/Mode> for more information.
#pod
#pod =back
#pod
#pod =head1 TEMPLATES
#pod
#pod To override these templates, add your own at the designated path inside
#pod your app's C directory.
#pod
#pod =head2 yancy/table.html.ep
#pod
#pod The default C template. Uses the following additional stash values
#pod for configuration:
#pod
#pod =over
#pod
#pod =item properties
#pod
#pod An array reference of columns to display in the table. The same as
#pod C in the schema configuration. Defaults to
#pod C in the schema configuration or all of the schema's
#pod columns in C order. See L
#pod Your Schema> for more information.
#pod
#pod =item table
#pod
#pod     get '/events' => (
#pod         controller => 'yancy',
#pod         action => 'list',
#pod         table => {
#pod             thead => 0, # Disable column headers
#pod             class => 'table table-responsive', # Add a class
#pod         },
#pod     );
#pod
#pod Attributes for the table tag. A hash reference of the following keys:
#pod
#pod =over
#pod
#pod =item thead
#pod
#pod Whether or not to display the table head section, which contains the
#pod column headings.  Defaults to true (C<1>). Set to false (C<0>) to
#pod disable C<<
#pod
#pod =item show_filter
#pod
#pod Show filter input boxes for each column in the header. Pressing C
#pod will filter the table.
#pod
#pod =item id
#pod
#pod The ID of the table element.
#pod
#pod =item class
#pod
#pod The class(s) of the table element.
#pod
#pod =back
#pod
#pod =back
#pod
#pod =head1 SEE ALSO
#pod
#pod L
#pod
#pod =cut

use Mojo::Base 'Mojolicious::Controller';
use Mojo::JSON qw( to_json );
use Yancy::Util qw( derp is_type );
use POSIX qw( ceil );

#pod =method schema
#pod
#pod Get the L object to handle the current request. This uses
#pod the C stash value to look up the schema from the default model. Override
#pod the default model using the C stash value.
#pod
#pod =cut

sub schema {
  my ( $self ) = @_;
  if ( $self->stash( 'collection' ) ) {
    derp '"collection" stash key is now "schema" in controller configuration';
  }
  my $schema_name = $self->stash( 'schema' ) || $self->stash( 'collection' )
    || die "Schema name not defined in stash";
  my $model = $self->stash( 'model' ) // $self->yancy->model;
  return $model->schema( $schema_name );
}

#pod =method item_id
#pod
#pod Get the ID for the currently-requested item, if available, or C.
#pod
#pod =cut

sub item_id {
  my ( $self ) = @_;
  my $id_field = $self->schema->id_field;
  if ( ref $id_field eq 'ARRAY' ) {
    my $id = { map { $_ => $self->stash( $_ ) } grep defined $self->stash( $_ ), @$id_field };
    return keys %$id == @$id_field ? $id : undef;
  }
  return $self->stash( $id_field ) // undef;
}

#pod =method clean_item
#pod
#pod Clean the given item by removing any sensitive fields (like passwords).
#pod
#pod =cut

sub clean_item {
  my ( $self, $item ) = @_;
  my $props = $self->schema->json_schema->{properties};
  my @keep_props = grep { ($props->{$_}{format}//'') ne 'password' } keys %$props;
  return { map { $_ => $item->{$_} } @keep_props };
}

#pod =method list
#pod
#pod     $routes->get( '/' )->to(
#pod         'yancy#list',
#pod         schema => $schema_name,
#pod         template => $template_name,
#pod     );
#pod
#pod This method is used to list content.
#pod
#pod =head4 Input Stash
#pod
#pod This method uses the following stash values for configuration:
#pod
#pod =over
#pod
#pod =item schema
#pod
#pod The schema to use. Required.
#pod
#pod =item template
#pod
#pod The name of the template to use. See L
#pod for how template names are resolved. Defaults to C.
#pod
#pod =item limit
#pod
#pod The number of items to show on the page. Defaults to C<10>.
#pod
#pod =item page
#pod
#pod The page number to show. Defaults to C<1>. The page number will
#pod be used to calculate the C parameter to L.
#pod
#pod =item filter
#pod
#pod A hash reference of field/value pairs to filter the contents of the list
#pod or a subref that generates this hash reference. The subref will be passed
#pod the current controller object (C<$c>).
#pod
#pod This overrides any query filters and so can be used to enforce
#pod authorization / security.
#pod
#pod =item order_by
#pod
#pod Set the default order for the items. Supports any L
#pod C structure.
#pod
#pod =item before_render
#pod
#pod An array reference of hooks to call once for each item in the C list.
#pod See L for usage.
#pod
#pod =back
#pod
#pod =head4 Output Stash
#pod
#pod The following stash values are set by this method:
#pod
#pod =over
#pod
#pod =item items
#pod
#pod An array reference of items to display.
#pod
#pod =item total
#pod
#pod The total number of items that match the given filters.
#pod
#pod =item total_pages
#pod
#pod The number of pages of items. Can be used for pagination.
#pod
#pod =back
#pod
#pod =head4 Query Params
#pod
#pod The following URL query parameters are allowed for this method:
#pod
#pod =over
#pod
#pod =item $page
#pod
#pod Instead of using the C stash value, you can use the C<$page> query
#pod paremeter to set the page.
#pod
#pod =item $offset
#pod
#pod Instead of using the C stash value, you can use the C<$offset>
#pod query parameter to set the page offset. This is overridden by the
#pod C<$page> query parameter.
#pod
#pod =item $limit
#pod
#pod Instead of using the C stash value, you can use the C<$limit>
#pod query parameter to allow users to specify their own page size.
#pod
#pod =item $order_by
#pod
#pod One or more fields to order by. Can be specified as C<<  >> or
#pod C<< asc: >> to sort in ascending order or C<< desc: >>
#pod to sort in descending order.
#pod
#pod =item $match
#pod
#pod How to match multiple field filters. Can be C or C (default
#pod C). C means all fields must match for a row to be returned.
#pod C means at least one field must match for a row to be returned.
#pod
#pod =item Additional Field Filters
#pod
#pod Any named query parameter that matches a field in the schema will be
#pod used to further filter the results. The stash C will override
#pod this filter, so that the stash C can be used for security.
#pod
#pod =back
#pod
#pod =head4 Content Negotiation
#pod
#pod If the C request accepts content type is C, or
#pod the URL ends in C<.json>, the results page will be returned as a JSON
#pod object with the following keys:
#pod
#pod =over
#pod
#pod =item items
#pod
#pod The array of items for this page.
#pod
#pod =item total
#pod
#pod The total number of results for the query.
#pod
#pod =item offset
#pod
#pod The current offset. Get the next page of results by increasing this
#pod number and setting the C<$offset> query parameter.
#pod
#pod =back
#pod
#pod =cut

sub list {
    my ( $c ) = @_;
    my ( $filter, $opt ) = $c->_get_list_args;
    my $result = $c->schema->list( $filter, $opt );

    # XXX: Filters are deprecated
    my $schema_name = $c->stash( 'schema' ) || $c->stash( 'collection' )
      || die "Schema name not defined in stash";
    $result->{items} = [
      map {
        $c->yancy->filter->apply( $schema_name, $_, 'x-filter-output' )
      }
      @{ $result->{items} }
    ];

    for my $helper ( @{ $c->stash( 'before_render' ) // [] } ) {
        $c->$helper( $_ ) for @{ $result->{items} };
    }
    $result->{items} = [ map $c->clean_item( $_ ), @{ $result->{items} } ];
    # By the time `any` is reached, the format will be blank. To support
    # any format of template, we need to restore the format stash
    my $format = $c->stash( 'format' );
    return $c->respond_to(
        json => sub {
            $c->stash( json => { %$result, offset => $opt->{offset} } );
        },
        any => sub {
            if ( !$c->stash( 'template' ) ) {
                $c->stash( template => 'yancy/table' );
            }
            $c->stash(
                ( format => $format )x!!$format,
                %$result,
                total_pages => ceil( $result->{total} / $opt->{limit} ),
            );
        },
    );
}

#pod =method get
#pod
#pod     $routes->get( '/:id_field' )->to(
#pod         'yancy#get',
#pod         schema => $schema_name,
#pod         template => $template_name,
#pod     );
#pod
#pod This method is used to show a single item.
#pod
#pod =head4 Input Stash
#pod
#pod This method uses the following stash values for configuration:
#pod
#pod =over
#pod
#pod =item schema
#pod
#pod The schema to use. Required.
#pod
#pod =item "id_field"
#pod
#pod The ID field(s) for the item should be defined as stash items, usually via
#pod route placeholders named after the field.
#pod
#pod     # Schema ID field is "page_id"
#pod     $routes->get( '/pages/:page_id' )
#pod
#pod =item template
#pod
#pod The name of the template to use. See L
#pod for how template names are resolved.
#pod
#pod =item before_render
#pod
#pod An array reference of helpers to call before the item is displayed.  See
#pod L for usage.
#pod
#pod =back
#pod
#pod =head4 Output Stash
#pod
#pod The following stash values are set by this method:
#pod
#pod =over
#pod
#pod =item item
#pod
#pod The item that is being displayed.
#pod
#pod =back
#pod
#pod =head4 Content Negotiation
#pod
#pod If the C request accepts content type is C, or
#pod the URL ends in C<.json>, the item will be returned as a JSON object.
#pod
#pod =cut

sub get {
    my ( $c ) = @_;
    my $schema = $c->schema;
    my $id = $c->item_id;
    if ( !$id ) {
      my $id_field = $schema->id_field;
      die sprintf "ID field(s) %s not defined in stash",
        join ', ', map qq("$_"), $id_field eq 'ARRAY' ? @$id_field : $id_field;
    }
    my $item = $schema->get( $id );
    if ( !$item ) {
        $c->reply->not_found;
        return;
    }

    # XXX: Filters are deprecated
    my $schema_name = $c->stash( 'schema' ) || $c->stash( 'collection' )
      || die "Schema name not defined in stash";
    $item = $c->yancy->filter->apply( $schema_name, $item, 'x-filter-output' );

    for my $helper ( @{ $c->stash( 'before_render' ) // [] } ) {
        $c->$helper( $item );
    }

    $item = $c->clean_item( $item );

    # By the time `any` is reached, the format will be blank. To support
    # any format of template, we need to restore the format stash
    my $format = $c->stash( 'format' );
    return $c->respond_to(
        json => sub { $c->stash( json => $item ) },
        any => sub { $c->stash( item => $item, ( format => $format )x!!$format ) },
    );
}

#pod =method set
#pod
#pod     # Update an existing item
#pod     $routes->any( [ 'GET', 'POST' ] => '/:id_field/edit' )->to(
#pod         'yancy#set',
#pod         schema => $schema_name,
#pod         template => $template_name,
#pod     );
#pod
#pod     # Create a new item
#pod     $routes->any( [ 'GET', 'POST' ] => '/create' )->to(
#pod         'yancy#set',
#pod         schema => $schema_name,
#pod         template => $template_name,
#pod         forward_to => $route_name,
#pod     );
#pod
#pod This route creates a new item or updates an existing item in
#pod a schema. If the user is making a C request, they will simply
#pod be shown the template. If the user is making a C or C
#pod request, the form parameters will be read, the data will be validated
#pod against L,
#pod and the user will either be shown the form again with the
#pod result of the form submission (success or failure) or the user will be
#pod forwarded to another place.
#pod
#pod Displaying a form could be done as a separate route using the C
#pod method, but with more code:
#pod
#pod     $routes->get( '/:id_field/edit' )->to(
#pod         'yancy#get',
#pod         schema => $schema_name,
#pod         template => $template_name,
#pod     );
#pod     $routes->post( '/:id_field/edit' )->to(
#pod         'yancy#set',
#pod         schema => $schema_name,
#pod         template => $template_name,
#pod     );
#pod
#pod =head4 Input Stash
#pod
#pod This method uses the following stash values for configuration:
#pod
#pod =over
#pod
#pod =item schema
#pod
#pod The schema to use. Required.
#pod
#pod =item "id_field"
#pod
#pod The ID field(s) for the item should be defined as stash items, usually via
#pod route placeholders named after the field. Optional: If not specified, a new
#pod item will be created.
#pod
#pod     # Schema ID field is "page_id"
#pod     $routes->post( '/pages/:page_id' )
#pod
#pod =item template
#pod
#pod The name of the template to use. See L
#pod for how template names are resolved.
#pod
#pod =item before_write
#pod
#pod An array reference of helpers to call after the new values are applied
#pod to the item, but before the item is written to the database. See
#pod L for usage.
#pod
#pod =item forward_to
#pod
#pod The name of a route to forward the user to on success. Optional. Any
#pod route placeholders that match item field names will be filled in.
#pod
#pod     $routes->get( '/:blog_id/:slug' )->name( 'blog.view' );
#pod     $routes->post( '/create' )->to(
#pod         'yancy#set',
#pod         schema => 'blog',
#pod         template => 'blog_edit.html.ep',
#pod         forward_to => 'blog.view',
#pod     );
#pod
#pod     # { id => 1, slug => 'first-post' }
#pod     # forward_to => '/1/first-post'
#pod
#pod Forwarding will not happen for JSON requests.
#pod
#pod =item properties
#pod
#pod Restrict this route to only setting the given properties. An array
#pod reference of properties to allow. Trying to set additional properties
#pod will result in an error.
#pod
#pod B Unless restricted to certain properties using this
#pod configuration, this method accepts all valid data configured for the
#pod schema. The data being submitted can be more than just the fields
#pod you make available in the form. If you do not want certain data to be
#pod written through this form, you can prevent it by using this.
#pod
#pod =back
#pod
#pod =head4 Output Stash
#pod
#pod The following stash values are set by this method:
#pod
#pod =over
#pod
#pod =item item
#pod
#pod The item that is being edited, if the C is given. Otherwise, the
#pod item that was created.
#pod
#pod =item errors
#pod
#pod An array of hash references of errors that occurred during data
#pod validation. Each hash reference is either a L
#pod object or a hash reference with a C field. See L
#pod yancy.validate helper docs|Mojolicious::Plugin::Yancy/yancy.validate>
#pod and L for more details.
#pod
#pod =back
#pod
#pod =head4 Query Params
#pod
#pod This method accepts query parameters named for the fields in the schema.
#pod
#pod Each field in the item is also set as a param using
#pod L so that tag helpers like C
#pod will be pre-filled with the values. See
#pod L for more information. This also means
#pod that fields can be pre-filled with initial data or new data by using GET
#pod query parameters.
#pod
#pod =head4 CSRF Protection
#pod
#pod This method is protected by L
#pod (CSRF) protection|Mojolicious::Guides::Rendering/Cross-site request
#pod forgery>. CSRF protection prevents other sites from tricking your users
#pod into doing something on your site that they didn't intend, such as
#pod editing or deleting content. You must add a C<< <%= csrf_field %> >> to
#pod your form in order to delete an item successfully. See
#pod L.
#pod
#pod =head4 Content Negotiation
#pod
#pod If the C or C request content type is C,
#pod the request body will be treated as a JSON object to create/set. In this
#pod case, the form query parameters are not used.
#pod
#pod =cut

sub set {
    my ( $c ) = @_;
    my $schema = $c->schema;
    my $id_field = $schema->id_field;
    my $id = $c->item_id;

    # Display the form, if requested. This makes the simple case of
    # displaying and managing a form easier with a single route instead
    # of two routes (one to "yancy#get" and one to "yancy#set")
    if ( $c->req->method eq 'GET' ) {
        if ( defined $id ) {
            my $item = $schema->get( $id );

            # XXX: Filters are deprecated
            my $schema_name = $c->stash( 'schema' ) || $c->stash( 'collection' )
              || die "Schema name not defined in stash";
            $item = $c->yancy->filter->apply( $schema_name, $item, 'x-filter-output' );

            $c->stash( item => $c->clean_item( $item ) );
            my $props = $schema->json_schema->{properties};
            for my $key ( keys %$props ) {
                # Mojolicious TagHelpers take current values through the
                # params, but also we allow pre-filling values through the
                # GET query parameters (except for passwords)
                next if $props->{ $key }{ format }
                    && $props->{ $key }{ format } eq 'password';
                $c->param( $key => $c->param( $key ) // $item->{ $key } );
            }
        }
        else {
            # Add an empty hashref for creating a new item
            $c->stash( item => {} );
        }

        $c->respond_to(
            json => {
                status => 400,
                json => {
                    errors => [
                        {
                            message => 'GET request for JSON invalid',
                        },
                    ],
                },
            },
            any => { },
        );
        return;
    }

    if ( $c->accepts( 'html' ) && $c->validation->csrf_protect->has_error( 'csrf_token' ) ) {
        $c->app->log->error( 'CSRF token validation failed' );
        my $item = $schema->get( $id );

        # XXX: Filters are deprecated
        my $schema_name = $c->stash( 'schema' ) || $c->stash( 'collection' )
          || die "Schema name not defined in stash";
        $item = $c->yancy->filter->apply( $schema_name, $item, 'x-filter-output' );

        $c->render(
            status => 400,
            item => $c->clean_item( $item ),
            errors => [
                {
                    message => 'CSRF token invalid.',
                },
            ],
        );
        return;
    }

    my $data = eval { $c->req->json } || $c->req->params->to_hash;
    delete $data->{csrf_token};
    my @errors;

    my $allowed_props = $c->stash( 'properties' );
    my $props = $schema->json_schema->{properties};
    for my $key ( keys %$props ) {
        if ( $allowed_props && $data->{ $key } && !grep { $_ eq $key } @$allowed_props ) {
            push @errors, {message => sprintf( 'Properties not allowed: %s.', $key ), path => '/'};
        }
        my $format = $props->{ $key }{ format } // '';
        # Password cannot be changed to an empty string
        if ( $format eq 'password' ) {
            if ( exists $data->{ $key } &&
                ( !defined $data->{ $key } || $data->{ $key } eq '' )
            ) {
                delete $data->{ $key };
            }
        }
        # Upload files
        elsif ( $format eq 'filepath' and my $upload = $c->param( $key ) ) {
            my $path = $c->yancy->file->write( $upload );
            $data->{ $key } = $path;
        }
    }
    if ( @errors ) {
        $c->res->code( 400 );
        my $item = $schema->get( $id );

        # XXX: Filters are deprecated
        my $schema_name = $c->stash( 'schema' ) || $c->stash( 'collection' )
          || die "Schema name not defined in stash";
        $item = $c->yancy->filter->apply( $schema_name, $item, 'x-filter-output' );

        $c->respond_to(
            json => { json => { errors => \@errors } },
            any => { item => $item, errors => \@errors },
        );
        return;
    }

    for my $helper ( @{ $c->stash( 'before_write' ) // [] } ) {
        $c->$helper( $data );
    }
    # ID could change during our helpers
    $id = $c->item_id;
    my $has_id = defined $id;

    # XXX: Filters are deprecated
    my $schema_name = $c->stash( 'schema' ) || $c->stash( 'collection' )
      || die "Schema name not defined in stash";
    $data = $c->yancy->filter->apply( $schema_name, $data );

    if ( $has_id ) {
        eval { $schema->set( $id, $data ) };
        # ID field(s) may have changed
        if ( ref $id_field eq 'ARRAY' ) {
            for my $field ( @$id_field ) {
                $id->{ $field } = $data->{ $field } || $id->{ $field };
            }
        }
        else {
            $id = $data->{ $id_field } || $id;
        }
        #; $c->app->log->info( 'Set success, new id: ' . $id );
    }
    else {
        $id = eval { $schema->create( $data ) };
    }

    if ( my $errors = $@ ) {
        if ( ref $errors eq 'ARRAY' ) {
            # Validation error
            $c->res->code( 400 );
            $errors = [map {{message => $_->message, path => $_->path }} @$errors];
        }
        else {
            # Unknown error
            $c->res->code( 500 );
            $errors = [ { message => $errors } ];
        }
        my $item = $c->clean_item( $schema->get( $id ) );

        # XXX: Filters are deprecated
        my $schema_name = $c->stash( 'schema' ) || $c->stash( 'collection' )
          || die "Schema name not defined in stash";
        $item = $c->yancy->filter->apply( $schema_name, $item, 'x-filter-output' );

        $c->respond_to(
            json => { json => { errors => $errors } },
            any => { item => $item, errors => $errors },
        );
        return;
    }

    my $item = $c->clean_item( $schema->get( $id ) );
    # XXX: Filters are deprecated
    $item = $c->yancy->filter->apply( $schema_name, $item, 'x-filter-output' );

    return $c->respond_to(
        json => sub {
            $c->stash(
                status => $has_id ? 200 : 201,
                json => $item,
            );
        },
        any => sub {
            if ( my $route = $c->stash( 'forward_to' ) ) {
                $c->redirect_to( $route, %$item );
                return;
            }
            $c->stash( item => $item );
        },
    );
}

#pod =method delete
#pod
#pod     $routes->any( [ 'GET', 'POST' ], '/delete/:id_field' )->to(
#pod         'yancy#delete',
#pod         schema => $schema_name,
#pod         template => $template_name,
#pod         forward_to => $route_name,
#pod     );
#pod
#pod This route deletes an item from a schema. If the user is making
#pod a C request, they will simply be shown the template (which can be
#pod used to confirm the delete). If the user is making a C or C
#pod request, the item will be deleted and the user will either be shown the
#pod form again with the result of the form submission (success or failure)
#pod or the user will be forwarded to another place.
#pod
#pod =head4 Input Stash
#pod
#pod This method uses the following stash values for configuration:
#pod
#pod =over
#pod
#pod =item schema
#pod
#pod The schema to use. Required.
#pod
#pod =item "id_field"
#pod
#pod The ID field(s) for the item should be defined as stash items, usually via
#pod route placeholders named after the field.
#pod
#pod     # Schema ID field is "page_id"
#pod     $routes->get( '/pages/:page_id' )
#pod
#pod =item template
#pod
#pod The name of the template to use. See L
#pod for how template names are resolved.
#pod
#pod =item forward_to
#pod
#pod The name of a route to forward the user to on success. Optional.
#pod Forwarding will not happen for JSON requests.
#pod
#pod =item before_delete
#pod
#pod An array reference of helpers to call just before the item is deleted.
#pod See L for usage.
#pod
#pod =back
#pod
#pod =head4 Output Stash
#pod
#pod The following stash values are set by this method:
#pod
#pod =over
#pod
#pod =item item
#pod
#pod The item that will be deleted. If displaying the form again after the item is deleted,
#pod this will be C.
#pod
#pod =back
#pod
#pod =head4 CSRF Protection
#pod
#pod This method is protected by L
#pod (CSRF) protection|Mojolicious::Guides::Rendering/Cross-site request
#pod forgery>.  CSRF protection prevents other sites from tricking your users
#pod into doing something on your site that they didn't intend, such as
#pod editing or deleting content.  You must add a C<< <%= csrf_field %> >> to
#pod your form in order to delete an item successfully. See
#pod L.
#pod
#pod =cut

sub delete {
    my ( $c ) = @_;
    my $schema = $c->schema;
    my $id = $c->item_id;
    if ( !$id ) {
      my $id_field = $schema->id_field;
      die sprintf "ID field(s) %s not defined in stash",
        join ', ', map qq("$_"), $id_field eq 'ARRAY' ? @$id_field : $id_field;
    }

    # Display the form, if requested. This makes it easy to display
    # a confirmation page in a single route.
    if ( $c->req->method eq 'GET' ) {
        my $item = $c->clean_item( $schema->get( $id ) );
        $c->respond_to(
            json => {
                status => 400,
                json => {
                    errors => [
                        {
                            message => 'GET request for JSON invalid',
                        },
                    ],
                },
            },
            any => { item => $item },
        );
        return;
    }

    if ( $c->accepts( 'html' ) && $c->validation->csrf_protect->has_error( 'csrf_token' ) ) {
        $c->app->log->error( 'CSRF token validation failed' );
        $c->render(
            status => 400,
            item => $c->clean_item( $schema->get( $id ) ),
            errors => [
                {
                    message => 'CSRF token invalid.',
                },
            ],
        );
        return;
    }

    my $item = $schema->get( $id );
    for my $helper ( @{ $c->stash( 'before_delete' ) // [] } ) {
        $c->$helper( $item );
    }
    # ID fields could change during helper
    $id = $c->item_id;
    $schema->delete( $id );

    return $c->respond_to(
        json => sub {
            $c->rendered( 204 );
            return;
        },
        any => sub {
            if ( my $route = $c->stash( 'forward_to' ) ) {
                $c->redirect_to( $route );
                return;
            }
        },
    );
}

#pod =method feed
#pod
#pod     $routes->websocket( '/' )->to(
#pod         'yancy#feed',
#pod         schema => $schema_name,
#pod     );
#pod
#pod Subscribe to a feed of changes to the given schema. This first sends a list result
#pod (like L would). Then it sends change messages. Change messages are JSON objects
#pod with different fields based on the method of change:
#pod
#pod     # An item in the list was changed
#pod     {
#pod         method => "set",
#pod         # The position of the changed item in the list, 0-based
#pod         index => 2,
#pod         item => {
#pod             # These are the fields that changed
#pod             name    => 'Lars Fillmore',
#pod         },
#pod     }
#pod
#pod     # An item was added to the list
#pod     {
#pod         method => "create",
#pod         # The position of the new item in the list, 0-based
#pod         index => 0,
#pod         item => {
#pod             # The entire, newly-created item
#pod             # ...
#pod         },
#pod     }
#pod
#pod     # An item was removed from the list. This does not necessarily mean
#pod     # the item was removed from the database.
#pod     {
#pod         method => "delete",
#pod         # The position of the item removed from the list, 0-based
#pod         index => 0,
#pod     }
#pod
#pod B Allow the client to send change messages to the server.
#pod
#pod =head4 Input Stash
#pod
#pod This method uses the following stash values for configuration:
#pod
#pod =over
#pod
#pod =item schema
#pod
#pod The schema to use. Required.
#pod
#pod =item limit
#pod
#pod The number of items to show on the page. Defaults to C<10>.
#pod
#pod =item page
#pod
#pod The page number to show. Defaults to C<1>. The page number will
#pod be used to calculate the C parameter to L.
#pod
#pod =item filter
#pod
#pod A hash reference of field/value pairs to filter the contents of the list
#pod or a subref that generates this hash reference. The subref will be passed
#pod the current controller object (C<$c>).
#pod
#pod This overrides any query filters and so can be used to enforce
#pod authorization / security.
#pod
#pod =item order_by
#pod
#pod Set the default order for the items. Supports any L
#pod C structure.
#pod
#pod =item before_render
#pod
#pod An array reference of hooks to call once for each item in the C list
#pod before they are sent as messages. See L for usage.
#pod
#pod =back
#pod
#pod =head4 Query Params
#pod
#pod The following URL query parameters are allowed for this method:
#pod
#pod =over
#pod
#pod =item $page
#pod
#pod Instead of using the C stash value, you can use the C<$page> query
#pod parameter to set the page.
#pod
#pod =item $offset
#pod
#pod Instead of using the C stash value, you can use the C<$offset>
#pod query parameter to set the page offset. This is overridden by the
#pod C<$page> query parameter.
#pod
#pod =item $limit
#pod
#pod Instead of using the C stash value, you can use the C<$limit>
#pod query parameter to allow users to specify their own page size.
#pod
#pod =item $order_by
#pod
#pod One or more fields to order by. Can be specified as C<<  >> or
#pod C<< asc: >> to sort in ascending order or C<< desc: >>
#pod to sort in descending order.
#pod
#pod =item $match
#pod
#pod How to match multiple field filters. Can be C or C (default
#pod C). C means all fields must match for a row to be returned.
#pod C means at least one field must match for a row to be returned.
#pod
#pod =item Additional Field Filters
#pod
#pod Any named query parameter that matches a field in the schema will be
#pod used to further filter the results. The stash C will override
#pod this filter, so that the stash C can be used for security.
#pod
#pod =back
#pod
#pod =cut

sub feed {
    my ( $c ) = @_;
    $c->inactivity_timeout( 3600 );
    my $schema = $c->schema;

    # First, send the message for the initial page
    my ( $filter, $opt ) = $c->_get_list_args;
    my $result = $schema->list( $filter, $opt );
    for my $helper ( @{ $c->stash( 'before_render' ) // [] } ) {
        $c->$helper( $_ ) for @{ $result->{items} };
    }
    my $x_id_field = $schema->id_field;
    my @id_fields = ref $x_id_field eq 'ARRAY' ? @$x_id_field : ( $x_id_field );
    #; $c->log->debug( 'Original result: ' . $c->dumper( $result ) );
    $c->send({ json => { %$result, method => 'list' } });

    # Now, poll the database for updates every few seconds.
    # XXX: Create Yancy::Plugin::PubSub to do push messaging instead of
    # ugly polling...
    my $id = Mojo::IOLoop->recurring( $c->stash( 'interval' ) // 10, sub {
        my $new_result = $schema->list( $filter, $opt );
        #; $c->log->debug( 'New result: ' . $c->dumper( $new_result ) );
        my %seen_items;
        my @created_items;
        NEW_ITEM: for my $new_i ( 0..$#{ $new_result->{items} } ) {
            my $new_item = $new_result->{items}[$new_i];
            # Loop through the old result to find the existing items by
            # their ID fields
            for my $old_i ( 0..$#{ $result->{items} } ) {
                my $old_item = $result->{items}[$old_i];
                if ( @id_fields == grep { $new_item->{ $_ } eq $old_item->{ $_ } } @id_fields ) {
                    # Found it!
                    $seen_items{ $old_i }++;
                    my %diff =
                        map { $_ => $new_item->{ $_ } }
                        grep {; no warnings 'uninitialized'; $new_item->{ $_ } ne $old_item->{ $_ } }
                        keys %$new_item, keys %$old_item
                        ;
                    if ( keys %diff ) {
                        my $message = {
                            method => 'set',
                            index => $old_i,
                            item => \%diff,
                        };
                        #$c->log->debug( $c->dumper( $message ) );
                        $c->send({ json => $message });
                    }
                    next NEW_ITEM;
                }
            }
            # If we can't find the new item, it must have been added.
            # Queue it up to send after deletes to maintain indexes.
            push @created_items, {
                method => 'create',
                index => $new_i,
                item => $new_item,
            };
        }
        # Any items we did not see must have been removed from the list,
        # or pushed out by newly-created items. Send these in reverse to
        # maintain indexes.
        for my $old_i ( reverse grep { !$seen_items{ $_ } } 0..$#{ $result->{items} } ) {
            my $message = {
                method => 'delete',
                index => $old_i,
            };
            #$c->log->debug( $c->dumper( $message ) );
            $c->send({ json => $message });
        }
        # Now we can send the created items, from lowest index to
        # highest index
        for my $item ( @created_items ) {
            #$c->log->debug( $c->dumper( $item ) );
            $c->send({ json => $item });
        }

        $result = $new_result;
    } );
    $c->on( finish => sub { Mojo::IOLoop->remove( $id ) } );
    # XXX: Allow client to send "list" message to change the parameters
    # of the list. Respond with an entirely new result (not a diff).
    # XXX: Allow client to send "create", "set", and "delete" messages
    # to create, set, and delete items
}

sub _get_list_args {
    my ( $c ) = @_;

    my $limit = $c->param( '$limit' ) // $c->stash->{ limit } // 10;
    my $offset = $c->param( '$page' ) ? ( $c->param( '$page' ) - 1 ) * $limit
        : $c->param( '$offset' ) ? $c->param( '$offset' )
        : ( ( $c->stash->{page} // 1 ) - 1 ) * $limit;
    $c->stash( page => int( $offset / $limit ) + 1 );
    my $opt = {
        limit => $limit,
        offset => $offset,
    };

    if ( my $order_by = $c->param( '$order_by' ) ) {
        $opt->{order_by} = [
            map +{ "-" . ( $_->[1] ? $_->[0] : 'asc' ) => $_->[1] // $_->[0] },
            map +[ split /:/ ],
            split /,/, $order_by
        ];
    }
    elsif ( $order_by = $c->stash( 'order_by' ) ) {
        $opt->{order_by} = $order_by;
    }

    my $schema = $c->schema;
    my $props  = $schema->json_schema->{properties};
    my %param_filter = ();
    for my $key ( @{ $c->req->params->names } ) {
        next unless exists $props->{ $key };
        my $type = $props->{$key}{type} || 'string';
        my $value = $c->param( $key );
        if ( is_type( $type, 'string' ) ) {
            if ( ( $value =~ tr/*/%/ ) <= 0 ) {
                 $value = "\%$value\%";
            }
            $param_filter{ $key } = { -like => $value };
        }
        elsif ( grep is_type( $type, $_ ), qw(number integer) ) {
            $param_filter{ $key } = $value ;
        }
        elsif ( is_type( $type, 'boolean' ) ) {
            $param_filter{ ($value && $value ne 'false')? '-bool' : '-not_bool' } = $key;
        }
        elsif ( is_type($type, 'array') ) {
            $param_filter{ $key } = { '-has' =>  $value };
        }
        else {
            die "Sorry type '" .
                to_json( $type ) .
                "' is not handled yet, only string|number|integer|boolean|array is supported."
        }
    }
    my $filter = {
        %param_filter,
        # Stash filter always overrides param filter, for security
        %{ $c->_resolve_filter },
    };
    if ( $c->param( '$match' ) && $c->param( '$match' ) eq 'any' ) {
        $filter = [
            map +{ $_ => $filter->{ $_ } }, keys %$filter
        ];
    }

    #; use Data::Dumper;
    #; $c->app->log->info( Dumper $filter );
    #; $c->app->log->info( Dumper $opt );

    return ( $filter, $opt );
}

sub _resolve_filter {
    my ( $c ) = @_;
    my $filter = $c->stash( 'filter' );
    if ( ref $filter eq 'CODE' ) {
        return $filter->( $c );
    }
    return $filter // {};
}

1;

__END__