SL/Layout/Dispatcher.pm

   1 package SL::Layout::Dispatcher;
   2
   3 use strict;
   4
   5 use SL::Layout::Admin;
   6 use SL::Layout::AdminLogin;
   7 use SL::Layout::Login;
   8 use SL::Layout::Classic;
   9 use SL::Layout::V3;
  10 use SL::Layout::Javascript;
  11
  12 sub new {
  13   my ($class, %params) = @_;
  14
  15   return SL::Layout::Classic->new    if $params{style} eq 'old';
  16   return SL::Layout::V3->new         if $params{style} eq 'v3';
  17   return SL::Layout::Javascript->new if $params{style} eq 'neu';
  18   return SL::Layout::Admin->new      if $params{style} eq 'admin';
  19   return SL::Layout::AdminLogin->new if $params{style} eq 'admin_login';
  20   return SL::Layout::Login->new      if $params{style} eq 'login';
  21   return SL::Layout::None->new;
  22 }
  23
  24 1;
  25
  26 __END__
  27
  28 =encoding utf-8
  29
  30 =head1 NAME
  31
  32 SL::Layout::Dispatcher - provides layouts by name.
  33
  34 =head1 SYNOPSIS
  35
  36   use SL::Layout::Dispatcher;
  37   $::request->layout(SL::Layout::Dispatcher->new(style => 'login'));
  38
  39   # same as
  40
  41   use SL::Layout::Login;
  42   $::request->layout(SL::Layout::Login->new);
  43
  44 =head1 INTRODUCTION
  45
  46 A layout in kivitendo is anything that should be included into a text/html
  47 response without having each controller do it manually. This includes:
  48
  49 =over 4
  50
  51 =item *
  52
  53 menus
  54
  55 =item *
  56
  57 status bars
  58
  59 =item
  60
  61 div containers for error handling and ajax responses
  62
  63 =item *
  64
  65 javascript and css includes
  66
  67 =item *
  68
  69 html header and body
  70
  71 =back
  72
  73 It does not include:
  74
  75 =over 4
  76
  77 =item *
  78
  79 http headers
  80
  81 =item *
  82
  83 anthing that is not a text/html response
  84
  85 =back
  86
  87 All of these tasks are handled by a layout object, which is stored in the
  88 global L<$::request|SL::Request> object. An appropriate layout object will be
  89 chosen during the login/session_restore process.
  90
  91
  92 =head1 INTERFACE
  93
  94 Every layout must be instantiated from L<SL::Layout::Base> and must implement
  95 the following eight callbacks:
  96
  97 =over 4
  98
  99 =item C<pre_content>
 100
 101 Content that must, for whatever reason, appear before the main content.
 102
 103 =item C<start_content>
 104
 105 An introcutory clause for the main content. Usually something like C<< <div
 106 class='content'> >>.
 107
 108 =item C<end_content>
 109
 110 The corresponding end of L</start_content> like C<< </div> >>
 111
 112 =item C<post_content>
 113
 114 Any extra content that should appear after the main content in the response
 115 source. Note that it is preferred to put extra content after the main content,
 116 so that it gets rendered faster.
 117
 118 =item C<stylesheets>
 119
 120 A list of stylesheets that should be included as a full relative web path. Will
 121 be rendered into the html header.
 122
 123 =item C<stylesheets_inline>
 124
 125 A list of stylesheet snippets that need to be included in the response. Will be
 126 added to the html header.
 127
 128 =item C<javascripts>
 129
 130 A list of javascripts that should be included as a full relative web path.
 131
 132 Note:
 133 There is no guarantee where these will end up in the content. Currently they
 134 will be rendered into the header, but are likely to be moved into the footer in
 135 the future.
 136
 137 =item C<javascripts_inline>
 138
 139 A list of javascript snippets that need to be included in the response.
 140
 141 Note:
 142 These will end up in the footer, so make sure they don't contain
 143 initializations to static javascript includes that may be included earlier.
 144
 145 =back
 146
 147 =head1 RUNTIME INTERFACE
 148
 149 Each layout object can add stylesheets and javascripts at runtime, as long as
 150 its before the actual rendering has begun. This can be used to add special
 151 javascripts only your controller needs.
 152
 153 =over 4
 154
 155 =item C<add_stylesheets>
 156
 157 Adds the list of arguments to the list of used stylesheets.
 158
 159 These will first be searched in the theme folder for the current user, and only
 160 after that be searched from the common C<css/> folder.
 161
 162 Duplicated files will be only included once.
 163
 164 Non-existing files will be pruned from the list.
 165
 166 =item C<use_stylesheet>
 167
 168 Backwards compatible alias for C<add_stylesheets>. Deprecated.
 169
 170 =item C<static_stylesheets>
 171
 172 Can be overwritten in sub-layouts to return a list of needed stylesheets. The
 173 values will be resolved by the actual layout in addition to the
 174 C<add_stylesheets> accumulator.
 175
 176 =item C<add_javascripts>
 177
 178 Adds the list of arguments to the list of used javascripts.
 179
 180 Duplicated files will be only included once.
 181
 182 Non-existing files will be pruned from the list.
 183
 184 =item C<use_javascript>
 185
 186 Backwards compatible alias for C<add_javascripts>. Deprecated.
 187
 188
 189 =item C<static_javascripts>
 190
 191 Can be overwritten in sub-layouts to return a list of needed javascripts. The
 192 values will be resolved by the actual layout in addition to the
 193 C<add_javascripts> accumulator.
 194
 195 =item C<add_javascripts_inline>
 196
 197 Add a snippet of javascript.
 198
 199 =item C<add_stylesheets_inline>
 200
 201 Add a snippet of css.
 202
 203 =item C<focus>
 204
 205 If set with a selector, the layout will generate javascript to set the page
 206 focus to that selector on document.ready.
 207
 208 =back
 209
 210 =head1 BUGS
 211
 212 None yet :)
 213
 214 =head1 TODO
 215
 216 non existing css or js includes should generate a log entry.
 217
 218 =head1 AUTHOR
 219
 220 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>
 221
 222 =cut