SL/Layout/Dispatcher.pm

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