lib/Reaction/Manual/RenderPage.pod

   1 =head1 NAME
   2
   3 Reaction::Manual::RenderPage - Page rendering
   4
   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
  41 =head2 Or, how to track why your page failed to render
  42
  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.
  52
  53 The View first fetches the root ViewPort from the Window's stack and
  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.
  57
  58 Is your head spinning yet?
  59
  60 Ingredients used:
  61
  62 * A Reaction::UI::Skin object built from:
  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
  69 * A Reaction::UI::LayoutSet object built from:
  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
  75 * A Reaction::UI::Widget object built from:
  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
  82 * A Reaction::UI::RenderingContext::TT object built from:
  83
  84     - Nothing
  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.