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 |
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 | |
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? |
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 | |
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. |