1 package SL::Presenter::Tag;
5 use SL::HTML::Restrict;
7 use parent qw(Exporter);
9 use Exporter qw(import);
10 our @EXPORT = qw(html_tag input_tag hidden_tag javascript man_days_tag name_to_id select_tag checkbox_tag button_tag submit_tag ajax_submit_tag input_number_tag stringify_attributes restricted_html link);
14 my %_valueless_attributes = map { $_ => 1 } qw(
15 checked compact declare defer disabled ismap multiple noresize noshade nowrap
16 readonly selected hidden
20 my ($object, $method, @params) = @_;
21 return $object->$method(@params);
24 { # This will give you an id for identifying html tags and such.
25 # It's guaranteed to be unique unless you exceed 10 mio calls per request.
26 # Do not use these id's to store information across requests.
27 my $_id_sequence = int rand 1e7;
29 return ( $_id_sequence = ($_id_sequence + 1) % 1e7 );
35 $string =~ s/(\"|\'|\\)/\\$1/g;
39 sub stringify_attributes {
40 my ($self, %params) = @_;
43 while (my ($name, $value) = each %params) {
45 next if $_valueless_attributes{$name} && !$value;
46 $value = '' if !defined($value);
47 push @result, $_valueless_attributes{$name} ? $self->escape($name) : $self->escape($name) . '="' . $self->escape($value) . '"';
50 return @result ? ' ' . join(' ', @result) : '';
54 my ($self, $tag, $content, %params) = @_;
55 my $attributes = $self->stringify_attributes(%params);
57 return "<${tag}${attributes}>" unless defined($content);
58 return "<${tag}${attributes}>${content}</${tag}>";
62 my ($self, $name, $value, %attributes) = @_;
64 _set_id_attribute(\%attributes, $name);
65 $attributes{type} ||= 'text';
67 return $self->html_tag('input', undef, %attributes, name => $name, value => $value);
71 my ($self, $name, $value, %attributes) = @_;
72 return $self->input_tag($name, $value, %attributes, type => 'hidden');
76 my ($self, $name, $object, %attributes) = @_;
78 my $size = delete($attributes{size}) || 5;
82 my $time_selection = $self->input_tag( "${name}_as_man_days_string", _call_on($object, "${method}_as_man_days_string"), %attributes, size => $size);
83 my $unit_selection = $self->select_tag("${name}_as_man_days_unit", [[ 'h', $::locale->text('h') ], [ 'man_day', $::locale->text('MD') ]],
84 %attributes, default => _call_on($object, "${method}_as_man_days_unit"));
86 return $time_selection . $unit_selection;
90 my ($self, $name) = @_;
92 $name =~ s/\[\+?\]/ _id() /ge; # give constructs with [] or [+] unique ids
93 $name =~ s/[^\w_]/_/g;
100 my ($self, $name, $collection, %attributes) = @_;
102 _set_id_attribute(\%attributes, $name);
104 my $value_key = delete($attributes{value_key}) || 'id';
105 my $title_key = delete($attributes{title_key}) || $value_key;
106 my $default_key = delete($attributes{default_key}) || 'selected';
107 my $default_val_key = delete($attributes{default_value_key});
108 my $default_coll = delete($attributes{default});
110 my $value_title_sub = delete($attributes{value_title_sub});
112 my $value_sub = delete($attributes{value_sub});
113 my $title_sub = delete($attributes{title_sub});
114 my $default_sub = delete($attributes{default_sub});
116 my $with_empty = delete($attributes{with_empty});
117 my $empty_title = delete($attributes{empty_title});
119 my $with_optgroups = delete($attributes{with_optgroups});
121 undef $default_key if $default_sub || $default_val_key;
123 my $normalize_entry = sub {
124 my ($type, $entry, $sub, $key) = @_;
126 return $sub->($entry) if $sub;
128 my $ref = ref($entry);
131 return $entry if $type eq 'value' || $type eq 'title';
135 if ( $ref eq 'ARRAY' ) {
136 return $entry->[ $type eq 'value' ? 0 : $type eq 'title' ? 1 : 2 ];
139 return $entry->{$key} if $ref eq 'HASH';
140 return $entry->$key if $type ne 'default' || $entry->can($key);
145 if (defined($default_coll) && !ref $default_coll) {
146 %selected = ($default_coll => 1);
148 } elsif (ref($default_coll) eq 'HASH') {
149 %selected = %{ $default_coll };
151 } elsif ($default_coll) {
152 $default_coll = [ $default_coll ] unless 'ARRAY' eq ref $default_coll;
154 %selected = $default_val_key ? map({ ($normalize_entry->('value', $_, undef, $default_val_key) => 1) } @{ $default_coll })
155 : map({ ($_ => 1) } @{ $default_coll });
158 my $list_to_code = sub {
159 my ($sub_collection) = @_;
161 if ('ARRAY' ne ref $sub_collection) {
162 $sub_collection = [ $sub_collection ];
166 foreach my $entry ( @{ $sub_collection } ) {
170 if ( $value_title_sub ) {
171 ($value, $title) = @{ $value_title_sub->($entry) };
174 $value = $normalize_entry->('value', $entry, $value_sub, $value_key);
175 $title = $normalize_entry->('title', $entry, $title_sub, $title_key);
178 my $default = $default_key ? $normalize_entry->('default', $entry, $default_sub, $default_key) : 0;
180 push(@options, [$value, $title, $selected{$value} || $default]);
183 return join '', map { $self->html_tag('option', $self->escape($_->[1]), value => $_->[0], selected => $_->[2]) } @options;
187 $code .= $self->html_tag('option', $self->escape($empty_title || ''), value => '') if $with_empty;
189 if (!$with_optgroups) {
190 $code .= $list_to_code->($collection);
193 $code .= join '', map {
194 my ($optgroup_title, $sub_collection) = @{ $_ };
195 $self->html_tag('optgroup', $list_to_code->($sub_collection), label => $optgroup_title)
199 return $self->html_tag('select', $code, %attributes, name => $name);
203 my ($self, $name, %attributes) = @_;
205 _set_id_attribute(\%attributes, $name);
207 $attributes{value} = 1 unless defined $attributes{value};
208 my $label = delete $attributes{label};
209 my $checkall = delete $attributes{checkall};
210 my $for_submit = delete $attributes{for_submit};
212 if ($attributes{checked}) {
213 $attributes{checked} = 'checked';
215 delete $attributes{checked};
219 $code .= $self->hidden_tag($name, 0, %attributes, id => $attributes{id} . '_hidden') if $for_submit;
220 $code .= $self->html_tag('input', undef, %attributes, name => $name, type => 'checkbox');
221 $code .= $self->html_tag('label', $label, for => $attributes{id}) if $label;
222 $code .= $self->javascript(qq|\$('#$attributes{id}').checkall('$checkall');|) if $checkall;
228 my ($self, $onclick, $value, %attributes) = @_;
230 _set_id_attribute(\%attributes, $attributes{name}) if $attributes{name};
231 $attributes{type} ||= 'button';
233 $onclick = 'if (!confirm("'. _J(delete($attributes{confirm})) .'")) return false; ' . $onclick if $attributes{confirm};
235 return $self->html_tag('input', undef, %attributes, value => $value, onclick => $onclick);
239 my ($self, $name, $value, %attributes) = @_;
241 _set_id_attribute(\%attributes, $attributes{name}) if $attributes{name};
243 if ( $attributes{confirm} ) {
244 $attributes{onclick} = 'return confirm("'. _J(delete($attributes{confirm})) .'");';
247 return $self->input_tag($name, $value, %attributes, type => 'submit', class => 'submit');
250 sub ajax_submit_tag {
251 my ($self, $url, $form_selector, $text, %attributes) = @_;
254 $form_selector = _J($form_selector);
255 my $onclick = qq|kivi.submit_ajax_form('${url}', '${form_selector}')|;
257 return $self->button_tag($onclick, $text, %attributes);
260 sub input_number_tag {
261 my ($self, $name, $value, %params) = @_;
263 _set_id_attribute(\%params, $name);
264 my @onchange = $params{onchange} ? (onChange => delete $params{onchange}) : ();
265 my @classes = ('numeric');
266 push @classes, delete($params{class}) if $params{class};
267 my %class = @classes ? (class => join(' ', @classes)) : ();
269 $::request->layout->add_javascripts('kivi.Validator.js');
270 $::request->presenter->need_reinit_widgets($params{id});
272 return $self->input_tag(
273 $name, $::form->foramt_amount(\%::myconfig, $value),
274 "data-validate" => "number",
282 my ($self, $data) = @_;
283 return $self->html_tag('script', $data, type => 'text/javascript');
286 sub _set_id_attribute {
287 my ($attributes, $name, $unique) = @_;
289 if (!delete($attributes->{no_id}) && !$attributes->{id}) {
290 $attributes->{id} = name_to_id(undef, $name);
291 $attributes->{id} .= '_' . $attributes->{value} if $unique;
294 return %{ $attributes };
299 sub restricted_html {
300 my ($self, $value) = @_;
302 $html_restricter ||= SL::HTML::Restrict->create;
303 return $html_restricter->process($value);
307 my ($self, $href, $content, %params) = @_;
311 return $self->html_tag('a', $content, %params, href => $href);
323 SL::Presenter::Tag - Layouting / tag generation
331 [% P.select_tag('direction', [ [ 'left', 'To the left' ], [ 'right', 'To the right', 1 ] ]) %]
333 [% P.select_tag('direction', [ { direction => 'left', display => 'To the left' },
334 { direction => 'right', display => 'To the right' } ],
335 value_key => 'direction', title_key => 'display', default => 'right') %]
337 [% P.select_tag('direction', [ { direction => 'left', display => 'To the left' },
338 { direction => 'right', display => 'To the right', selected => 1 } ],
339 value_key => 'direction', title_key => 'display') %]
341 # Use an RDBO object and its n:m relationship as the default
342 # values. For example, a user can be a member of many groups. "All
343 # groups" is therefore the full collection and "$user->groups" is a
344 # list of RDBO AuthGroup objects whose IDs must match the ones in
345 # "All groups". This could look like the following:
346 [% P.select_tag('user.groups[]', SELF.all_groups, multiple=1,
347 default=SELF.user.groups, default_value_key='id' ) %]
351 A module modeled a bit after Rails' ActionView helpers. Several small
352 functions that create HTML tags from various kinds of data sources.
354 The C<id> attribute is usually calculated automatically. This can be
355 overridden by either specifying an C<id> attribute or by setting
360 =head2 LOW-LEVEL FUNCTIONS
364 =item C<html_tag $tag_name, $content_string, %attributes>
366 Creates an opening and closing HTML tag for C<$tag_name> and puts
367 C<$content_string> between the two. If C<$content_string> is undefined
368 or empty then only a E<lt>tag/E<gt> tag will be created. Attributes
369 are key/value pairs added to the opening tag.
371 C<$content_string> is not HTML escaped.
373 =item C<name_to_id $name>
375 Converts a name to a HTML id by replacing various characters.
377 =item C<stringify_attributes %items>
379 Creates a string from all elements in C<%items> suitable for usage as
380 HTML tag attributes. Keys and values are HTML escaped even though keys
381 must not contain non-ASCII characters for browsers to accept them.
383 =item C<restricted_html $html>
385 Returns HTML stripped of unknown tags. See L<SL::HTML::Restrict>.
389 =head2 HIGH-LEVEL FUNCTIONS
393 =item C<input_tag $name, $value, %attributes>
395 Creates a HTML 'input type=text' tag named C<$name> with the value
396 C<$value> and with arbitrary HTML attributes from C<%attributes>. The
397 tag's C<id> defaults to C<name_to_id($name)>.
399 =item C<submit_tag $name, $value, %attributes>
401 Creates a HTML 'input type=submit class=submit' tag named C<$name> with the
402 value C<$value> and with arbitrary HTML attributes from C<%attributes>. The
403 tag's C<id> defaults to C<name_to_id($name)>.
405 If C<$attributes{confirm}> is set then a JavaScript popup dialog will
406 be added via the C<onclick> handler asking the question given with
407 C<$attributes{confirm}>. The request is only submitted if the user
408 clicks the dialog's ok/yes button.
410 =item C<ajax_submit_tag $url, $form_selector, $text, %attributes>
412 Creates a HTML 'input type="button"' tag with a very specific onclick
413 handler that submits the form given by the jQuery selector
414 C<$form_selector> to the URL C<$url> (the actual JavaScript function
415 called for that is C<kivi.submit_ajax_form()> in
416 C<js/client_js.js>). The button's label will be C<$text>.
418 =item C<button_tag $onclick, $text, %attributes>
420 Creates a HTML 'input type="button"' tag with an onclick handler
421 C<$onclick> and a value of C<$text>. The button does not have a name
422 nor an ID by default.
424 If C<$attributes{confirm}> is set then a JavaScript popup dialog will
425 be prepended to the C<$onclick> handler asking the question given with
426 C<$attributes{confirm}>. The request is only submitted if the user
427 clicks the dialog's "ok/yes" button.
429 =item C<man_days_tag $name, $object, %attributes>
431 Creates two HTML inputs: a text input for entering a number and a drop
432 down box for chosing the unit (either 'man days' or 'hours').
434 C<$object> must be a L<Rose::DB::Object> instance using the
435 L<SL::DB::Helper::AttrDuration> helper.
437 C<$name> is supposed to be the name of the underlying column,
438 e.g. C<time_estimation> for an instance of
439 C<SL::DB::RequirementSpecItem>. If C<$name> has the form
440 C<prefix.method> then the full C<$name> is used for the input's base
441 names while the methods called on C<$object> are only the suffix. This
442 makes it possible to write statements like e.g.
444 [% P.man_days_tag("requirement_spec_item.time_estimation", SELF.item) %]
446 The attribute C<size> can be used to set the text input's size. It
449 =item C<hidden_tag $name, $value, %attributes>
451 Creates a HTML 'input type=hidden' tag named C<$name> with the value
452 C<$value> and with arbitrary HTML attributes from C<%attributes>. The
453 tag's C<id> defaults to C<name_to_id($name)>.
455 =item C<checkbox_tag $name, %attributes>
457 Creates a HTML 'input type=checkbox' tag named C<$name> with arbitrary
458 HTML attributes from C<%attributes>. The tag's C<id> defaults to
459 C<name_to_id($name)>. The tag's C<value> defaults to C<1>.
461 If C<%attributes> contains a key C<label> then a HTML 'label' tag is
462 created with said C<label>. No attribute named C<label> is created in
465 If C<%attributes> contains a key C<checkall> then the value is taken as a
466 JQuery selector and clicking this checkbox will also toggle all checkboxes
467 matching the selector.
469 =item C<select_tag $name, \@collection, %attributes>
471 Creates an HTML 'select' tag named C<$name> with the contents of one
472 'E<lt>optionE<gt>' tag for each element in C<\@collection> and with arbitrary
473 HTML attributes from C<%attributes>. The value
474 to use and the title to display are extracted from the elements in
475 C<\@collection>. Each element can be one of four things:
479 =item 1. An array reference with at least two elements. The first element is
480 the value, the second element is its title. The third element is optional and and should contain a boolean.
481 If it is true, than the element will be used as default.
483 =item 2. A scalar. The scalar is both the value and the title.
485 =item 3. A hash reference. In this case C<%attributes> must contain
486 I<value_key>, I<title_key> and may contain I<default_key> keys that name the keys in the element to use
487 for the value, title and default respectively.
489 =item 4. A blessed reference. In this case C<%attributes> must contain
490 I<value_key>, I<title_key> and may contain I<default_key> keys that name functions called on the blessed
491 reference whose return values are used as the value, title and default
496 For cases 3 and 4 C<$attributes{value_key}> defaults to C<id>,
497 C<$attributes{title_key}> defaults to C<$attributes{value_key}> and
498 C<$attributes{default_key}> defaults to C<selected>. Note that
499 C<$attributes{default_key}> is set to C<undef> if
500 C<$attributes{default_value_key}> is used as well (see below).
502 In addition to pure keys/method you can also provide coderefs as I<value_sub>
503 and/or I<title_sub> and/or I<default_sub>. If present, these take precedence over keys or methods,
504 and are called with the element as first argument. It must return the value, title or default.
506 Lastly a joint coderef I<value_title_sub> may be provided, which in turn takes
507 precedence over the C<value_sub> and C<title_sub> subs. It will only be called once for each
508 element and must return a list of value and title.
510 If the option C<with_empty> is set then an empty element (value
511 C<undef>) will be used as the first element. The title to display for
512 this element can be set with the option C<empty_title> and defaults to
515 The tag's C<id> defaults to C<name_to_id($name)>.
517 The option C<default> can be quite a lot of things:
521 =item 1. A scalar value. This is the value of the entry that's
524 =item 2. A hash reference for C<multiple=1>. Whether or not an entry
525 is selected by default is looked up in this hash.
527 =item 3. An array reference containing scalar values. Same as 1., just
528 for the case of C<multiple=1>.
530 =item 4. If C<default_value_key> is given: an array reference of hash
531 references. For each hash reference the value belonging to the key
532 C<default_value_key> is treated as one value to select by
533 default. Constructs a hash that's treated like 3.
535 =item 5. If C<default_value_key> is given: an array reference of
536 blessed objects. For each object the value returne from calling the
537 function named C<default_value_key> on the object is treated as one
538 value to select by default. Constructs a hash that's treated like 3.
542 5. also applies to single RDBO instances (due to 'wantarray'
543 shenanigans assigning RDBO's relationships to a hash key will result
544 in a single RDBO object being assigned instead of an array reference
545 containing that single RDBO object).
547 If the option C<with_optgroups> is set then this function expects
548 C<\@collection> to be one level deeper. The upper-most level is
549 translated into an HTML C<optgroup> tag. So the structure becomes:
553 =item 1. Array of array references. Each element in the
554 C<\@collection> is converted into an optgroup.
556 =item 2. The optgroup's C<label> attribute will be set to the
557 first element in the array element. The second array element is then
558 converted to a list of C<option> tags as described above.
562 Example for use of optgroups:
564 # First in a controller:
566 [ t8("First optgroup with three items"),
567 [ { id => 42, name => "item one" },
568 { id => 54, name => "second item" },
569 { id => 23, name => "and the third one" },
571 [ t8("Another optgroup, with a lot of items from Rose"),
572 SL::DB::Manager::Customer->get_all_sorted ],
575 # Later in the template:
576 [% L.select_tag('the_selection', COLLECTION, with_optgroups=1, title_key='name') %]
586 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>,
587 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>