5 use parent qw(Rose::Object);
10 use SL::Presenter::CustomerVendor;
11 use SL::Presenter::DeliveryOrder;
12 use SL::Presenter::EscapedText;
13 use SL::Presenter::Invoice;
14 use SL::Presenter::Order;
15 use SL::Presenter::Project;
16 use SL::Presenter::Record;
19 $::request->{presenter} ||= SL::Presenter->new;
20 return $::request->{presenter};
26 my ($options, %locals) = (@_ && ref($_[0])) ? @_ : ({ }, @_);
28 $options->{type} = lc($options->{type} || 'html');
31 if ($options->{inline}) {
35 $source = "templates/webpages/${template}." . $options->{type};
36 croak "Template file ${source} not found" unless -f $source;
39 my %params = ( %locals,
41 FLASH => $::form->{FLASH},
43 INSTANCE_CONF => $::instance_conf,
45 LXCONFIG => \%::lx_office_conf,
46 LXDEBUG => $::lxdebug,
47 MYCONFIG => \%::myconfig,
52 my $parser = $self->get_template;
53 $parser->process($source, \%params, \$output) || croak $parser->error;
55 return SL::Presenter::EscapedText->new(text => $output, is_escaped => 1);
62 Template->new({ INTERPOLATE => 0,
66 PLUGIN_BASE => 'SL::Template::Plugin',
67 INCLUDE_PATH => '.:templates/webpages',
68 COMPILE_EXT => '.tcc',
69 COMPILE_DIR => $::lx_office_conf{paths}->{userspath} . '/templates-cache',
70 ERROR => 'templates/webpages/generic/exception.html',
73 return $self->{template};
77 my ($self, $text) = @_;
79 return SL::Presenter::EscapedText->new(text => $text);
83 my ($self, $text) = @_;
85 return SL::Presenter::EscapedText->new(text => $text, is_escaped => 1);
94 SL::Presenter - presentation layer class
99 my $presenter = SL::Presenter->get;
101 # Lower-level template parsing:
102 my $html = $presenter->render(
103 'presenter/dir/template.html',
107 # Higher-level rendering of certain objects:
108 use SL::DB::Customer;
110 my $linked_customer_name = $presenter->customer($customer, display => 'table-cell');
112 # Render a list of links to sales/purchase records:
115 my $quotation = SL::DB::Manager::Order->get_first(where => { quotation => 1 });
116 my $records = $quotation->linked_records(direction => 'to');
117 my $html = $presenter->grouped_record_list($records);
119 =head1 CLASS FUNCTIONS
125 Returns the global presenter object and creates it if it doesn't exist
130 =head1 INSTANCE FUNCTIONS
134 =item C<render $template, [ $options, ] %locals>
136 Renders the template C<$template>. Provides other variables than
137 C<Form::parse_html_template> does.
139 C<$options>, if present, must be a hash reference. All remaining
140 parameters are slurped into C<%locals>.
142 This is the backend function that L<SL::Controller::Base/render>
143 calls. The big difference is that the presenter's L<render> function
144 always returns the input and never sends anything to the browser while
145 the controller's function usually sends the result to the
146 controller. Therefore the presenter's L<render> function does not use
147 all of the parameters for controlling the output that the controller's
150 What is rendered and how C<$template> is interpreted is determined by
151 the options I<type> and I<inline>.
153 If C<< $options->{inline} >> is trueish then C<$template> is a string
154 containing the template code to interprete.
156 If C<< $options->{inline} >> is falsish then C<$template> is
157 interpreted as the name of a template file. It is prefixed with
158 "templates/webpages/" and postfixed with a file extension based on
159 C<< $options->{type} >>. C<< $options->{type} >> can be either C<html>
160 or C<js> and defaults to C<html>. An exception will be thrown if that
163 The template itself has access to the following variables:
167 =item * C<AUTH> -- C<$::auth>
169 =item * C<FORM> -- C<$::form>
171 =item * C<LOCALE> -- C<$::locale>
173 =item * C<LXCONFIG> -- all parameters from C<config/kivitendo.conf>
174 with the same name they appear in the file (first level is the
175 section, second the actual variable, e.g. C<system.dbcharset>,
176 C<features.webdav> etc)
178 =item * C<LXDEBUG> -- C<$::lxdebug>
180 =item * C<MYCONFIG> -- C<%::myconfig>
182 =item * C<SELF> -- the controller instance
184 =item * All items from C<%locals>
188 The function will always return the output and never send anything to
191 Example: Render a HTML template with a certain title and a few locals
193 $presenter->render('todo/list',
194 title => 'List TODO items',
195 TODO_ITEMS => SL::DB::Manager::Todo->get_all_sorted);
197 Example: Render a string and return its content for further processing
198 by the calling function.
200 my $content = $presenter->render(
201 '[% USE JavaScript %][% JavaScript.replace_with("#someid", "js/something") %]',
205 =item C<escape $text>
207 Returns an HTML-escaped version of C<$text>. Instead of a string an
208 instance of the thin proxy-object L<SL::Presenter::EscapedText> is
211 It is safe to call C<escape> on an instance of
212 L<SL::Presenter::EscapedText>. This is a no-op (the same instance will
215 =item C<escaped_text $text>
217 Returns an instance of L<SL::Presenter::EscapedText>. C<$text> is
218 assumed to be a string that has already been HTML-escaped.
220 It is safe to call C<escaped_text> on an instance of
221 L<SL::Presenter::EscapedText>. This is a no-op (the same instance will
224 =item C<get_template>
226 Returns the global instance of L<Template> and creates it if it
227 doesn't exist already.
233 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>