Catalyst::Controller::Rose::Search(3)

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.

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 334:
    Expected '=item *'