[catagits/Reaction.git] / lib / Reaction / Manual / RenderPage.pod

=head1 NAME

Reaction::Manual::RenderPage - Page rendering

=head2 A little overview

  .---------------------------------------.
  |           Controller Action           |
  |---------------------------------------|
  | Decides which logical part to provide |
  '---------------------------------------'
                      |
                      v
      .------------------------------.
      |           ViewPort           |
      |------------------------------|----------.
      | A logical part of the page   |          |
      '------------------------------'          |
                      |                  Inner ViewPorts
                      v                       Data      
   .-------------------------------------.      |
   |              LayoutSet              |      |
   |-------------------------------------|------.
   | A representational part of the page |      |
   '-------------------------------------'      |
                      |                       Looks  
                      v                     Structure
      .-------------------------------.         |
      |            Widget             |         |
      |-------------------------------|---------.
      | A functional part of the page |         |
      '-------------------------------'         |
                                           Preparation
                                            Structure 
      .-------------------------------.         |
      |            Output             |         |
      |-------------------------------|<--------'
      | The rendered part of the page |
      '-------------------------------'

=head2 Or, how to track why your page failed to render

Catalyst's C<begin> and C<end> actions are supplied by
L<Reaction::UI::Controller::Root>, which your C<Root> controller should inherit
from, or at least the root controller of the part of your application that is
using Reaction.

The C<begin> action creates a new L<Reaction::UI::Window> and stores it in $c->stash->{window}.
The C<end> action calls the flush() method on the stashed window object.
L<Reaction::UI::Window/flush> then calls L<Reaction::UI::View/render_window>
on the window's view.

The View first fetches the root ViewPort from the Window's stack and
creates a RenderingContext. The layout is chosen based on the ViewPort name or
though the ViewPort's C<layout> attribute. The Widget is then used to render the
content via the RenderingContext.

Is your head spinning yet?

Ingredients used:

* A Reaction::UI::Skin object built from:

    - The skin_name set on your View
    - The View object
    - The skin_base_dir (MyApp/share/skin)
    - The share/skin/defaults.conf + share/skin/<my_skin>/skin.conf

* A Reaction::UI::LayoutSet object built from:

    - The layoutset file itself, found in the share/skin/<my_skin>/layout directory
      or the share/skin/default/layout directory.
    - The Skin object

* A Reaction::UI::Widget object built from:

    - It's class, determined from the name of the ViewPort or read from the 
      layoutset file, and found in the widget_search_path.
    - The View object
    - The LayoutSet object

* A Reaction::UI::RenderingContext::TT object built from:

    - Nothing

To render the window the correct Reaction::UI::Widget object is
retrieved via the LayoutSet for the root ViewPort of the page. 

The LayoutSet used defaults to the "layout" attribute on the
ViewPort. If there is no layout attribute value set, it takes the
class name of the ViewPort, extracts the parts following
"::ViewPort::" and constructs the layoutset name from converting camel
cased parts of the namespace to lower-case underscored, and namespace
parts into directories.

  ## eg:
  My::ViewPort::Action::UserForm
  ## becomes
  action/user_form

The layoutset file should exist in the skin_base_dir, in the "layout"
directory under the "skin_name" dir set in your View config, or in the
"default/layout" directory. [[ A LayoutSet object is created based on
the layoutset name, skin object, source_file (path to file), top_skin
(skin object), next_skin if exists ]].

The layoutset file is parsed as the LayoutSet object is created, if a
"=widget" line is found, the "widget_type" attribute is set.

The class of the Widget object can be set in the layoutset object
args, or it defaults to being fetched via the Skin. The type of widget
is either specified in the layoutset file via the "=widget" directive
or retrieved by recreating the camelcased name from the layoutset
name. The Widget is assumed to be in the widget search path provided
by defaults.conf or your skin.conf.

The Widget itself is passed the ViewPort to render, and the
RenderingContext. The initial fragment name to render is also passed,
"widget".

The render stack is created using the widget order. The widget order
is fetched for the fragment from the layoutset, this is either the
widget class/layoutset, or retrieved from the extended layouts. As the
render_stack is built, the fragment methods in the Widget are called
to assign values from the ViewPort to arguments for the layout. (Or
other interesting things).

The stack is passed to the RenderingContext to complete.
Commit	Line	Data
5c818114	1	=head1 NAME
d325256f	2
5c818114	3	Reaction::Manual::RenderPage - Page rendering
d325256f	4
aeb875d9	5	=head2 A little overview
	6
	7	.---------------------------------------.
	8	\| Controller Action \|
	9	\|---------------------------------------\|
	10	\| Decides which logical part to provide \|
	11	'---------------------------------------'
	12	\|
	13	v
	14	.------------------------------.
	15	\| ViewPort \|
	16	\|------------------------------\|----------.
	17	\| A logical part of the page \| \|
	18	'------------------------------' \|
	19	\| Inner ViewPorts
	20	v Data
	21	.-------------------------------------. \|
	22	\| LayoutSet \| \|
	23	\|-------------------------------------\|------.
	24	\| A representational part of the page \| \|
	25	'-------------------------------------' \|
	26	\| Looks
	27	v Structure
	28	.-------------------------------. \|
	29	\| Widget \| \|
	30	\|-------------------------------\|---------.
	31	\| A functional part of the page \| \|
	32	'-------------------------------' \|
	33	Preparation
	34	Structure
	35	.-------------------------------. \|
	36	\| Output \| \|
	37	\|-------------------------------\|<--------'
	38	\| The rendered part of the page \|
	39	'-------------------------------'
	40
d325256f	41	=head2 Or, how to track why your page failed to render
d325256f	42
0fd7c39d	43	Catalyst's C<begin> and C<end> actions are supplied by
	44	L<Reaction::UI::Controller::Root>, which your C<Root> controller should inherit
	45	from, or at least the root controller of the part of your application that is
	46	using Reaction.
	47
	48	The C<begin> action creates a new L<Reaction::UI::Window> and stores it in $c->stash->{window}.
	49	The C<end> action calls the flush() method on the stashed window object.
	50	L<Reaction::UI::Window/flush> then calls L<Reaction::UI::View/render_window>
	51	on the window's view.
d325256f	52
d325256f	53	The View first fetches the root ViewPort from the Window's stack and
b6c6aad4	54	creates a RenderingContext. The layout is chosen based on the ViewPort name or
	55	though the ViewPort's C<layout> attribute. The Widget is then used to render the
	56	content via the RenderingContext.
d325256f	57
0fd7c39d	58	Is your head spinning yet?
0fd7c39d	59
d325256f	60	Ingredients used:
0fd7c39d	61
d325256f	62	* A Reaction::UI::Skin object built from:
0fd7c39d	63
	64	- The skin_name set on your View
	65	- The View object
	66	- The skin_base_dir (MyApp/share/skin)
	67	- The share/skin/defaults.conf + share/skin/<my_skin>/skin.conf
	68
d325256f	69	* A Reaction::UI::LayoutSet object built from:
0fd7c39d	70
	71	- The layoutset file itself, found in the share/skin/<my_skin>/layout directory
	72	or the share/skin/default/layout directory.
	73	- The Skin object
	74
d325256f	75	* A Reaction::UI::Widget object built from:
0fd7c39d	76
	77	- It's class, determined from the name of the ViewPort or read from the
	78	layoutset file, and found in the widget_search_path.
	79	- The View object
	80	- The LayoutSet object
	81
d325256f	82	* A Reaction::UI::RenderingContext::TT object built from:
0fd7c39d	83
0fd7c39d	84	- Nothing
d325256f	85
	86	To render the window the correct Reaction::UI::Widget object is
	87	retrieved via the LayoutSet for the root ViewPort of the page.
	88
	89	The LayoutSet used defaults to the "layout" attribute on the
	90	ViewPort. If there is no layout attribute value set, it takes the
	91	class name of the ViewPort, extracts the parts following
	92	"::ViewPort::" and constructs the layoutset name from converting camel
	93	cased parts of the namespace to lower-case underscored, and namespace
	94	parts into directories.
	95
	96	## eg:
	97	My::ViewPort::Action::UserForm
	98	## becomes
	99	action/user_form
	100
	101	The layoutset file should exist in the skin_base_dir, in the "layout"
	102	directory under the "skin_name" dir set in your View config, or in the
	103	"default/layout" directory. [[ A LayoutSet object is created based on
	104	the layoutset name, skin object, source_file (path to file), top_skin
	105	(skin object), next_skin if exists ]].
	106
	107	The layoutset file is parsed as the LayoutSet object is created, if a
	108	"=widget" line is found, the "widget_type" attribute is set.
	109
	110	The class of the Widget object can be set in the layoutset object
	111	args, or it defaults to being fetched via the Skin. The type of widget
	112	is either specified in the layoutset file via the "=widget" directive
	113	or retrieved by recreating the camelcased name from the layoutset
	114	name. The Widget is assumed to be in the widget search path provided
	115	by defaults.conf or your skin.conf.
	116
	117	The Widget itself is passed the ViewPort to render, and the
	118	RenderingContext. The initial fragment name to render is also passed,
	119	"widget".
	120
	121	The render stack is created using the widget order. The widget order
	122	is fetched for the fragment from the layoutset, this is either the
	123	widget class/layoutset, or retrieved from the extended layouts. As the
	124	render_stack is built, the fragment methods in the Widget are called
	125	to assign values from the ViewPort to arguments for the layout. (Or
	126	other interesting things).
	127
	128	The stack is passed to the RenderingContext to complete.