lib/Reaction/Manual/Templates.pod

   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