/ 
Reaction-0.002005
River stage one • 1 direct dependent • 1 total dependent
/ Reaction::Manual::Overview

NAME

Reaction::Manual::Overview - Orientation in Reaction

DESCRIPTION

This document aims at describing the modular parts of Reaction and explain how they are tied together.

WHAT IS REACTION

Reaction is a Catalyst extension providing you with:

  • Model mutations abstracted into Action objects.

  • Reflection to generate interface models using the Action objects from a DBIx::Class schema.

  • An abstract UI expression system based on view, skin, rendering context, widget and layout set.

  • Stylable via skins. Parts of the skins can be extended and flexibly from large down to very small parts.

  • Full separation of interface rendering structure and templating, making re-usable extensions even easier.

THE BIG PICTURE

        .=========.
        | Request |
        '========='
             |
             |
             v
  .--------------------.   .============================.
  |  Web Application   |   |      Interface Model       |
  | Action Dispatching |<--| Object, Collection, Action |
  '--------------------'   '============================'
             |                            ^
             v                            |
  .====================.        .-------------------.
  |      ViewPort      |        |   Domain Model    |
  | Plain, Collection, |        |  Business Logic,  |
  |   Object, Action   |        | Persistence Layer |
  '===================='        '-------------------'
             |
             v
  .====================.
  |     FocusStack     |
  | Contains ViewPorts |
  '===================='
             |
             v
       .-----------.     .===================.
       |   View    |     | RenderingContext  |
       | HTML, PDF |---->| Template Toolkit  |----.
       '-----------'     '==================='    |
             |                     ^              |
             v                     |              |
 .======================.          |              |
 | LayoutSet / ViewPort |          |              |
 | Layouts: widget, foo |          |              |
 '======================'          |              |
             |                     |              |
             v                     |              |
.========================.         |              |
|   Widget / LayoutSet   |         |              |
| Fragments: widget, foo |---------'              v
'========================'                  .==========.
                                            | Response |
                                            '=========='

APPLICATION

A Reaction application is really a Catalyst application under the hood. Reaction uses reflection to build more flexible and re-usable Catalyst components.

The main application module (usually called MyApp or MyApp.pm in documentation) looks exactly like a typical Catalyst application module. Reaction's modular architecture allows it therefor to be integrated into other Catalyst applications, or to integrate other Catalyst extensions and components itself.

CONTROLLERS

Usually in Catalyst applications the controller's actions will take their arguments, maybe modify them or clean them up. After that they are processed by the model and then stashed away to be later used by the view.

Reactions approach is a bit different. The cleanup and validation of values, and the involvement of the model are abstracted into a Reaction::InterfaceModel::Action subclass. Examples for such actions would be Create, Update or Delete in a CRUD situation.

Controllers that use Reaction have to inherit from Reaction::UI::Controller or a subclass of it. Some other useful controller base classes are:

VIEWPORTS

Viewports represent the components that render your page when combined.

The begin action in Reaction::Controller::Root creates a new Reaction::UI::Window object and stores it as window in the stash. The focus stack of that window object is used as the base focus stack for the request.

You can add a new inner viewport to the focus stack with the push_viewport method available on your controller:

$controller->push_viewport($viewport_class, %viewport_args);

This will add a new instance of $viewport_class to the current focus stack using %viewport_args as arguments. For more information on the usage and other options (for example the next_action option, which redirects afterwards) see Reaction::UI::FocusStack and Reaction::UI::ViewPort.

You can use the Reaction::UI::ViewPort::Action viewport to build viewports that perform typical form actions like OK, Apply and Close.

FOCUSSTACKS

Viewports are pushed onto the current focus stack. The end action in Reaction::Controller::Root will flush the Reaction::UI::Window object stored as window in the stash.

DOMAIN MODELS

The domain models should be completely decoupled from the application and it's business logic. Normally, you need to decide whether to put your business logic in your controller or in your model. Reaction solves this problem by using interface models as a separation between the two.

If you want your domain model to be reflectable (DBIx::Class for example) you will have to use Moose to add attribute metadata to those classes.

INTERFACE MODELS

The interface models contain your business logic. That is, the application specific logic representing the model your application will use.

An interface model consists of action classes subclassing Reaction::InterfaceModel::Action. These instances will have both the request context and the target model available and can do their work in a do_apply method.

To allow your own models to be tied in to reflective controllers like Reaction::Controller::Collection, you can subclass Reaction::InterfaceModel::Object. That will provide you with a way to let the viewports introspect the actions that your interface model defines for this model.

An example of this would be:

- MyApp::Controller::Foo is a Reaction::Controller::Collection::CRUD 
  for MyApp::Model::Foo
- The model_name config setting is 'Model::Foo'
- User calls action MyApp::Controller::Foo->delete_old
- The 'delete_old' controller action will call 
  $self->basic_model_action($c, \%vp_args)
- The 'target' option in %vp_args will be asked for an action that
  corresponds with the 'delete_old' controller action
- An instance of MyApp::Model::Foo::Action::DeleteOld is
  returned
- This is passed as 'model' to a new instance of
  Reaction::UI::ViewPort::Action which is then pushed
  onto the focus stack.

Form processing as provided by Reaction::UI::ViewPort::Action is a very good example of Reaction's usefulness; Instead of creating a new dialog for every form using myriads of helper functions, you provide a controller baseclass rendering the dialog by introspecting an interface model object with fields and actions.

Then you just need to create a new controller and interface model for your new dialog and it just works.

If your model is a DBIx::Class::Schema and contains Moose metadata, you can let Reaction::InterfaceModel::Reflector::DBIC set up your interface model objects and actions.

SKINS, LAYOUTS AND WIDGETS

When you push a viewport onto the focus stack like this:

$controller->push_viewport('Reaction::UI::ViewPort::SiteLayout');

Reaction will look for a layout file named $search_path/skin/$skin_name/layout/site_layout.tt. If it can't find it, it will also look in the base skin and search paths.

You can also provide a specific layout:

$controller->push_viewport(
  'Reaction::UI::ViewPort::SiteLayout',
  layout => 'my_site_layout',
);

A new instance of Reaction::UI::LayoutSet will be created using the layout file. It is then used to determine the class of widget to create. The widget contains the Perl code counterpart of the templating part in the layout file.

The widget is either determined by the =widget template directive in the layout file or by the Reaction::UI::Skin object created to represent the skin.

The details of skins or layouts are documented in Reaction::Manual::Templates.

SEE ALSO

AUTHORS

See Reaction::Class for authors.

LICENSE

See Reaction::Class for the license.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 41:

Unknown directive: =bac

Around line 43:

You forgot a '=back' before '=head1'