NAME

Catalyst::Controller::Rose::Search - base class for searching a RDBO model

SYNOPSIS

# subclass this module in your controller

package MyApp::Controller::Foo;
use base qw( Catalyst::Controller::Rose::Search );

use Foo::Form;

sub make_form  { Foo::Form->new }
sub model_name { 'Foo' }     # isa Catalyst::Model::RDBO subclass
sub can_search
{
    my ($self, $c) = @_;
    return $c->session->{user}->{roles}->{search};
}

1;

# now can call http://yoururl/foo/search
# or just http://yoururl/foo

DESCRIPTION

Catalyst::Controller::Rose::Search provides controller access to many of the features of Catalyst::Model::RDBO.

URL-ACCESSIBLE METHODS

The following methods are tagged as Local and will appear in your subclass's URL namespace by default.

default

A generic default() method which just issues a redirect() to search().

search

The primary method. See setup() and results() for ways to alter the default bahaviour.

INTERNAL METHODS

The following methods can be overridden in your subclass.

can_search

Returns true (1) if the request is authorized, false (0) if not. Default is true.

view_on_single_result

If the search results match only one row, then redirect to the URL returned. Default return is false (disabled).

Example:

sub view_on_single_result
{
    my ($self, $c, $obj) = @_;
    return $c->uri_for('/my/record', $obj->id, 'edit');
}

This method is intended for use with Catalyst::Controller::Rose::CRUD.

Called by search().

You can temporarily override the return value of this method by setting a true value in the stash key _no_view_on_single_result:

$c->stash->{_no_view_on_single_result} = 1;  # override

This allows for calling search() from other controllers and getting results even if there is only one hit.

setup

Called by search() to create the query structure passed to the model. Some string mangling is performed in order to play nicely with the RDBO query conventions.

This method calls make_form() and rose_query().

make_form

Returns a form object, which should be a subclass of Rose::HTML::Form (or at least have a similar API).

Override this method or stash a form object in your auto() method. If creating the form object is time-intensive, consider caching the form object and then just clearing it every time a request arrives:

use Foo::Form;
my $form = Foo::Form->new;

sub make_form
{
    $form->clear;
    return $form;
}

You can also avoid make_form() altogether by stashing the form object yourself in auto():

sub auto : Private
{
    my ($self, $c) = @_;
    $c->stash->{form} = Foo::Form->new;
    1;
}

model_name

Should return the name of the Model to be called in search().

rose_query()

Creates a RDBO query structure based on the incoming request params() and the fields defined in the make_form() form object. Some special syntax is supported:

• You may use * or % as a wildcard.

• !

  You may put a ! at the start of a query to invert it:

  !foo       # means NOT foo

results

Sets up the stash for use by the View. The following structure is set by default under the search keyword:

{
   results     => [ @array_of_RDBO_objects ],
   query       => { %param_to_values },
   query_str   => $plain_query_suitable_for_humans,
   order       => [ @array_of_hashrefs_used_by_view_column_sort ],
   pager       => $Data_Pageset_object
}

EXAMPLES

See the examples/ dir in the distribution.

AUTHOR

Peter Karman <perl@peknet.com>

Thanks to Atomic Learning, Inc for sponsoring the development of this module.

LICENSE

This library is free software. You may redistribute it and/or modify it under the same terms as Perl itself.

cpanm Catalyst::Controller::Rose

perl -MCPAN -e shell
install Catalyst::Controller::Rose