=head1 NAME
Reaction::Manual::Tutorial - Step by Step Tutorial
=head1 DESCRIPTION
This document aims at giving simple step-by-step leading to an example application
using the common functionality provided by L.
=head1 CREATING A NEW APPLICATION
At first we have to create a new application. For this we use the C
script as we would for any other Catalyst application:
$ catalyst.pl MyApp
[lots "created ..." messages]
There is nothing to change in the application class file.
As you work through this tutorial you'll be creating several new files in
various directories. You can save some time by creating the directories now,
like this:
mkdir -p share/skin/myapp/layout lib/MyApp/View/Site/Widget lib/MyApp/Schema lib/MyApp/InterfaceModel
=head1 THE VIEW
Since we are not just rendering templates with Reaction, but layouts and widgets,
a simple TT view won't suffice. We need to create our own C:
package MyApp::View::Site;
use Reaction::Class;
use namespace::autoclean;
extends 'Reaction::UI::View::TT';
__PACKAGE__->meta->make_immutable;
1;
The C and C. C is Reaction's most basic skin
while the C skin extends the base by embellishing the layouts with more XHTML.
The default skin is designed to be a working skin.
In other words, if you want to write most of the low-level XHTML yourself
then put the following in your skin.conf:
extends /Reaction/base
If you want to use more XHTML out of the box, then configure your application to extend
the default skin.
It's worth noting that you are not bound to the XHTML of the default or base skin layouts,
because you are able to override layout fragments in your own skin.
Next we create C to allow settings that concern all skins of
the application. It should contain only this:
widget_search_path MyApp::View::Site::Widget
widget_search_path Reaction::UI::Widget
This will tell Reaction to look in C and
C for widget classes. That means that our layout named
C will check for C first and then look if
C exists.
We want the first line to be able to create our own widgets and the second line to
have Reaction find its own widgets.
Now we need to tell Reaction what skin it should use. We do this by adding this section
to our C:
skin_name myapp
The value should be the name of the target directory under C.
=head1 LAYOUTS
We will need two layout files to begin with. One controlling the site layout and one
for the root action.
The first will be created as C:
=extends NEXT
=for layout body
Welcome to MyApp
[% inner %]
=cut
The C<=extends> directive specifies that this layout file is an extension of another
layout file. The C value here tells Reaction that this extends the C
layout in the base skin, which we have defined as C. That means, you
can take a look at the layout we are extending at C
in the L distribution.
The C<=for layout> directives allows us to set a layout fragment. We define a C fragment
containing the common C for all pages using this site layout. The C<[% inner %]> is
where the deeper parts of the stack will be included, in the case of our C action that
would be the C with the C layout.
If we want to override a specific fragment, we can do just that. There are two choices
when overriding a specific fragment. One can disregard the parent fragment all together
and start from scratch or they could reuse the parent fragment and add to it. The key to
re-using a parent (extended) layout fragment is the keyword C. Specifically,
we insert C<[% call_next %]> to include the layout fragment of the parent.
The parent layout fragment is found either in another layout template named in the
C<=extends> directive or it's in a subclass of Reaction::UI::Widget.
In the latter case, the Widget subclass name matches the name of the template or
the widget name posed at the top of the layout file via the C<=widget> directive.
Once you know the hierarchy C follows, then you know where to examine
the details of the parent layouts or widgets.
The layout representing the root action is called C:
=for layout widget
Hello, World!
=cut
This one is rather simple. The C<=for layout widget> directive is special in that the
C fragment will always be where the rendering starts. In fact, our C
layout too contains a C fragment, you just don't see it because you inherited it from
your base skin (or your base skin's base skin, for that matter) instead of defining it yourself.
=head1 A SIMPLE WIDGET
If we wanted to use a different kind of widget than that assumed automatically by Reaction, we
could add a
=widget ClassName
directive at the top of the layout file. But for now, we will instead create our own
widget at C:
package MyApp::View::Site::Widget::Root;
use Reaction::UI::WidgetClass;
use namespace::autoclean;
__PACKAGE__->meta->make_immutable;
1;
This adds no new functionality at the moment. It just uses C to ease
and automate the setup of a new widget class. The widget can provide functionality and fragments
to the layout. In a way, it can be seen as the Perl code backend to the layout file.
You can now start your C