PriceSource: editable Dokumentation
[kivitendo-erp.git] / 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<add_javascripts>
171
172 Adds the list of arguments to the list of used javascripts.
173
174 Duplicated files will be only included once.
175
176 Non-existing files will be pruned from the list.
177
178 =item C<use_javascript>
179
180 Backwards compatible alias for C<add_javascripts>. Deprecated.
181
182 =item C<add_javascripts_inline>
183
184 Add a snippet of javascript.
185
186 =item C<add_stylesheets_inline>
187
188 Add a snippet of css.
189
190 =item C<focus>
191
192 If set with a selector, the layout will generate javascript to set the page
193 focus to that selector on document.ready.
194
195 =back
196
197 =head1 BUGS
198
199 None yet :)
200
201 =head1 TODO
202
203 non existing css or js includes should generate a log entry.
204
205 =head1 AUTHOR
206
207 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>
208
209 =cut