CatalystX::RoseIntegrator - Catalyst/Rose Base Controller
WARNING: This is beta software. It works for me, not necessarily for you.
This documentation may lack information and / or be wrong. But it is a good start.
Feel free to report anything you would like to report ;-)
package MyApp::Controller::Books; use base 'CatalystX::RoseIntegrator'; # optional config setup __PACKAGE__->config( 'CatalystX::RoseIntegrator' = { template_type => 'TT', # default is 'TT' (i.e. TT2), only TT supported for the moment } ); # looks for books/edit.fb form configuration file, based on the presence of # the ":Form" attribute. sub edit : Local Form { my ( $self, $c, @args ) = @_; my $form = $self->form; # add email form field to fields already defined edit.fb $form->add_field( name => 'email', type => 'email' ); if ( $form->was_submitted ) { if ( $self->has_error ) { $c->stash->{ERROR} = "INVALID FORM"; } else { return $c->response->body("VALID FORM"); } } } # explicitedly use books/edit.fb, otherwise books/view.fb is used sub view : Local Form('/books/edit') { my ( $self, $c ) = @_; $c->stash->{template} = "books/edit.tt" # TT2 template; }
This base controller gives the power of Rose HTML/DB Objects to Catalyst in a simple manner.
Rose::HTML/DB::Object(s)? usage within Catalyst is straightforward. Since Catalyst handles page rendering, you don't call RHTMLO's methods, as you would normally. Instead, you simply add a :Form attribute to each method that you want to associate with a form. This will give you access to a RHTMLO::Form $self->form object within that controller method:
:Form
$self->form
# An editing screen for books sub edit : Local Form { my ( $self, $c ) = @_; $self->form->method('post'); # set form method }
The out-of-the-box setup is to look for a form configuration file, usually in Config::General format but any format recognized by Config::Loader should work, named for the current action url. So, if you were serving /books/edit, this plugin would look for:
/books/edit
root/forms/books/edit.conf
(The path is configurable) If no source file is found, an error is throwed.
Here is an example edit.yaml file (borrowed and adapted from you know where):
edit.yaml
# Form config file root/forms/books/edit.yaml name: books_edit method: post rdbo: Book fields_order: title, author, isbn, desc, submit fields: title: label: Book Title type: text required: 1 regexp: ^.{0,50}$ message: Max 50 characters regexp: ^[\w\.\(\)\s-]*$ message: Forbidden character(s) author: label: Author's Name type: text required: 1 regexp: ^.{0,50}$ message: Max 50 characters regexp: ^[\w\.\(\)\s-]*$ message: Forbidden character(s) isbn: label: ISBN# type: text regexp: ^(\d{10}|\d{13})$ message: Invalid ISBN number required: 1 desc: label: Description type: textarea cols: 80 rows: 5 submit: type: submit
Notice the 'rdbo' line, that specifies an optional RDBO class to tie to. With this, you don't have to specify sizes for the fields and you will be allowed to load and save content from / to the form directly from / to the DB.
To do that, use this:
my $book = $c->model('Book')->new; $form->book_from_form($book); $book->save,
and
my $book = $c->model('Book')->new(id => 15); $form->init_with_book($book);
Also notice that each validation regexp is associated with an error message. In the regexp field, instead of a real regexp, you can write -auto to check automatically the value with the type of the field (RHTMLO side). You can also enter -same-as field to check for equality (ASCII sense) with another field. This is good for password or email confirmations.
-same-as
This will automatically create a complete form for you, using the specified fields. Note that the root/forms path is configurable; this path is used by default to integrate with the TTSite helper.
root/forms
TTSite
Within your controller, you can call any method that you would on a normal RHTMLO object on the $self->form object. To manipulate the field named desc, simply call the field() method:
RHTMLO
desc
field()
# Change our desc field dynamically $self->form->field(desc, name => 'desc', label => 'Book Description', required => 1 );
To populate field options for country, you might use something like this to iterate through the database:
country
# not tested! $self->form->field(country, name => 'country', options => [ map { [ $_->id, $_->name ] } $c->model('Country::Manager')->get_countries ], );
The RHTMLO methodolody is to handle both rendering and validation of the form. As such, the form will "loop back" onto the same controller method. Within your controller, you would then use the standard RHTMLO submit/validate check:
if ( $self->form->was_submitted && !$self->has_error ) { $c->forward('/books/save'); }
This would forward to /books/save if the form was submitted and passed field validation. Otherwise, it would automatically re-render the form with invalid fields highlighted, leaving the database unchanged.
/books/save
To render the form in your tt2 template for example, you can use something like this to get a standard form for all your site:
<!-- root/src/myform.tt, included in other templates --> [% c.localize("An asterisk (<strong>*</strong>) indicates a mandatory field.") %]<br> [% RINTEG.start_xhtml %] [% FOREACH field IN RINTEG.ordered_fields %] [% field.xhtml_label %] [% IF field.required %] <strong>*</strong> [% END %] [% IF field.error %] <span class="error small"> [% field.error %] </span> [% END %] <br> [% field.xhtml_field %] <br><br> [% END %] [% RINTEG.end_xhtml %]
Catalyst::Controller::FormBuilder on which it is originally derived Catalyst::Manual, Catalyst::Request, Catalyst::Response Rose::HTML::Objects, Rose::DB::Object
Copyright (c) 2007 Alexandre Jousset <cpan@gtmp.org>. All Rights Reserved.
Thanks to Juan Camacho for inspiration (Catalyst::Controller::FormBuilder)
This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
To install CatalystX::RoseIntegrator, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CatalystX::RoseIntegrator
CPAN shell
perl -MCPAN -e shell install CatalystX::RoseIntegrator
For more information on module installation, please visit the detailed CPAN module installation guide.