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