L./P.select_tag: 'default' auf Liste von Rose::DB::Object-Instanzen setzen können...
[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::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