SL/Presenter.pm

   1 package SL::Presenter;
   2
   3 use strict;
   4
   5 use parent qw(Rose::Object);
   6
   7 use Carp;
   8 use Template;
   9
  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;
  17
  18 sub get {
  19   $::request->{presenter} ||= SL::Presenter->new;
  20   return $::request->{presenter};
  21 }
  22
  23 sub render {
  24   my $self               = shift;
  25   my $template           = shift;
  26   my ($options, %locals) = (@_ && ref($_[0])) ? @_ : ({ }, @_);
  27
  28   $options->{type}       = lc($options->{type} || 'html');
  29
  30   my $source;
  31   if ($options->{inline}) {
  32     $source = \$template;
  33
  34   } else {
  35     $source = "templates/webpages/${template}." . $options->{type};
  36     croak "Template file ${source} not found" unless -f $source;
  37   }
  38
  39   my %params = ( %locals,
  40                  AUTH          => $::auth,
  41                  FLASH         => $::form->{FLASH},
  42                  FORM          => $::form,
  43                  INSTANCE_CONF => $::instance_conf,
  44                  LOCALE        => $::locale,
  45                  LXCONFIG      => \%::lx_office_conf,
  46                  LXDEBUG       => $::lxdebug,
  47                  MYCONFIG      => \%::myconfig,
  48                  PRESENTER     => $self,
  49                );
  50
  51   my $output;
  52   my $parser = $self->get_template;
  53   $parser->process($source, \%params, \$output) || croak $parser->error;
  54
  55   return SL::Presenter::EscapedText->new(text => $output, is_escaped => 1);
  56 }
  57
  58 sub get_template {
  59   my ($self) = @_;
  60
  61   $self->{template} ||=
  62     Template->new({ INTERPOLATE  => 0,
  63                     EVAL_PERL    => 0,
  64                     ABSOLUTE     => 1,
  65                     CACHE_SIZE   => 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',
  71                   }) || croak;
  72
  73   return $self->{template};
  74 }
  75
  76 sub escape {
  77   my ($self, $text) = @_;
  78
  79   return SL::Presenter::EscapedText->new(text => $text);
  80 }
  81
  82 sub escaped_text {
  83   my ($self, $text) = @_;
  84
  85   return SL::Presenter::EscapedText->new(text => $text, is_escaped => 1);
  86 }
  87
  88 1;
  89
  90 __END__
  91
  92 =head1 NAME
  93
  94 SL::Presenter - presentation layer class
  95
  96 =head1 SYNOPSIS
  97
  98   use SL::Presenter;
  99   my $presenter = SL::Presenter->get;
 100
 101   # Lower-level template parsing:
 102   my $html = $presenter->render(
 103     'presenter/dir/template.html',
 104     var1 => 'value',
 105   );
 106
 107   # Higher-level rendering of certain objects:
 108   use SL::DB::Customer;
 109
 110   my $linked_customer_name = $presenter->customer($customer, display => 'table-cell');
 111
 112   # Render a list of links to sales/purchase records:
 113   use SL::DB::Order;
 114
 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);
 118
 119 =head1 CLASS FUNCTIONS
 120
 121 =over 4
 122
 123 =item C<get>
 124
 125 Returns the global presenter object and creates it if it doesn't exist
 126 already.
 127
 128 =back
 129
 130 =head1 INSTANCE FUNCTIONS
 131
 132 =over 4
 133
 134 =item C<render $template, [ $options, ] %locals>
 135
 136 Renders the template C<$template>. Provides other variables than
 137 C<Form::parse_html_template> does.
 138
 139 C<$options>, if present, must be a hash reference. All remaining
 140 parameters are slurped into C<%locals>.
 141
 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
 148 function does.
 149
 150 What is rendered and how C<$template> is interpreted is determined by
 151 the options I<type> and I<inline>.
 152
 153 If C<< $options->{inline} >> is trueish then C<$template> is a string
 154 containing the template code to interprete.
 155
 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
 161 file does not exist.
 162
 163 The template itself has access to the following variables:
 164
 165 =over 2
 166
 167 =item * C<AUTH> -- C<$::auth>
 168
 169 =item * C<FORM> -- C<$::form>
 170
 171 =item * C<LOCALE> -- C<$::locale>
 172
 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)
 177
 178 =item * C<LXDEBUG> -- C<$::lxdebug>
 179
 180 =item * C<MYCONFIG> -- C<%::myconfig>
 181
 182 =item * C<SELF> -- the controller instance
 183
 184 =item * All items from C<%locals>
 185
 186 =back
 187
 188 The function will always return the output and never send anything to
 189 the browser.
 190
 191 Example: Render a HTML template with a certain title and a few locals
 192
 193   $presenter->render('todo/list',
 194                      title      => 'List TODO items',
 195                      TODO_ITEMS => SL::DB::Manager::Todo->get_all_sorted);
 196
 197 Example: Render a string and return its content for further processing
 198 by the calling function.
 199
 200   my $content = $presenter->render(
 201     '[% USE JavaScript %][% JavaScript.replace_with("#someid", "js/something") %]',
 202     { type => 'js', inline => 1 }
 203   );
 204
 205 =item C<escape $text>
 206
 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
 209 returned.
 210
 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
 213 be returned).
 214
 215 =item C<escaped_text $text>
 216
 217 Returns an instance of L<SL::Presenter::EscapedText>. C<$text> is
 218 assumed to be a string that has already been HTML-escaped.
 219
 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
 222 be returned).
 223
 224 =item C<get_template>
 225
 226 Returns the global instance of L<Template> and creates it if it
 227 doesn't exist already.
 228
 229 =back
 230
 231 =head1 AUTHOR
 232
 233 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
 234
 235 =cut