Commit | Line | Data |
ec4dc0c4 |
1 | =head1 NAME |
2 | |
3 | Reaction::Manual::Templates |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | This is a detailed description of reaction's template system. |
8 | |
9 | =head1 OVERVIEW |
10 | |
11 | =head2 SKINS |
12 | |
13 | =head3 Organization |
14 | |
15 | Reaction's templates are organized into sets called skins. A skin is defined by |
16 | a directory containing several template files and static assets. Skins live in |
17 | directories under the C<share/skin> path in your application distribution. Each |
18 | directory and the template files within compose their own skin. Templates live |
19 | in the C<layout> directory and assets live in the C<web> directory. |
20 | |
21 | =head3 Core Skins |
22 | |
23 | Reaction provides prebuilt skins called C<base> and C<default>. These provide |
24 | the basic html components for a typical web application, such as forms, fields |
25 | and table list views. Skins are extensible, which means you can include all the |
26 | templates from another skin within your custom skin through a configuration |
27 | directive instead of copying template files, making your template setup easy to |
28 | maintain. |
29 | |
30 | =head3 Configuration Directives |
31 | |
32 | The C<share/skin/defaults.conf> file holds general application-wide skin |
33 | configuration. Each skin can be configured individually by placing a C<skin.conf> |
34 | file in it's root directory. |
35 | |
36 | =over |
37 | |
38 | =item * extends $skin_name |
39 | |
40 | Defines C<$skin_name> as the base skin. |
41 | |
42 | =back |
43 | |
44 | =head2 TEMPLATES |
45 | |
46 | Template files are sets of pod-like directives which define a set of layouts. |
47 | They are used for the sole purpose of describing how the data is to be layed out |
48 | at render time. Each template file contains a set of layout definitions which are |
49 | used by reaction widgets to generate the final content. Variables are defined and |
50 | populated in the widgets then passed to the layout fragments in a given template |
51 | file. |
52 | |
53 | =head3 Template Directives |
54 | |
55 | =over |
56 | |
57 | =item * =for layout $fragment_name |
58 | |
59 | Defines a layout fragment called C<$fragment_name>, everything under the |
60 | directive up to the next fragment directive is part of the definition. By default, |
61 | variables with the same name as an existing layout definition are rendered as the |
62 | equivalent layout. Widgets might interfere and select an alternate layout or |
63 | template to be rendered instead. A templates' rendering process always starts by |
64 | a layout called C<widget>. |
65 | |
66 | =item * =extends $template_name |
67 | |
68 | Makes the current template inherit the layout definitions in C<$template_name>. |
69 | Layouts defined in the template override the ones in the base template. The |
70 | special C<NEXT> template name specifies that inheritance should use the equivalent |
71 | template from the base skin as configured in C<skin.conf>. |
72 | |
73 | =item * =widget $widget_name |
74 | |
75 | Selects C<$widget_name> as the driver for the current template. |
76 | |
77 | =back |
78 | |
79 | =head2 LAYOUT FRAGMENTS |
80 | |
81 | =head3 Scope |
82 | |
83 | A layout definition creates a variable scope attached to that layout. Variables |
84 | only exist within their specific layout fragments, that is, they are scoped to |
85 | specific layouts. Overriding a layout places it in the same scope as the base layout. |
86 | |
87 | =head3 Using layouts defined in base templates |
88 | |
89 | The special [% call_next %] variable will be replaced by the layout in the base |
90 | template within the same scope. |
91 | |
92 | =cut |