1 package SL::Presenter::Tag;
5 use SL::HTML::Restrict;
6 use SL::Presenter::EscapedText qw(escape);
7 use Scalar::Util qw(blessed);
9 use Exporter qw(import);
11 html_tag input_tag hidden_tag javascript man_days_tag name_to_id select_tag
12 checkbox_tag button_tag submit_tag ajax_submit_tag input_number_tag
13 stringify_attributes restricted_html textarea_tag link_tag date_tag
14 div_tag radio_button_tag img_tag);
15 our %EXPORT_TAGS = (ALL => \@EXPORT_OK);
19 my %_valueless_attributes = map { $_ => 1 } qw(
20 checked compact declare defer disabled ismap multiple noresize noshade nowrap
21 readonly selected hidden
24 my %_singleton_tags = map { $_ => 1 } qw(
25 area base br col command embed hr img input keygen link meta param source
30 my ($object, $method, @params) = @_;
31 return $object->$method(@params);
34 { # This will give you an id for identifying html tags and such.
35 # It's guaranteed to be unique unless you exceed 10 mio calls per request.
36 # Do not use these id's to store information across requests.
37 my $_id_sequence = int rand 1e7;
39 return ( $_id_sequence = ($_id_sequence + 1) % 1e7 );
45 $string =~ s/(\"|\'|\\)/\\$1/g;
50 my ($name, $value) = @_;
51 my $spacer = $name eq 'class' ? ' ' : ''; # join classes with spaces, everything else as is
53 ref $value && 'ARRAY' eq ref $value
54 ? join $spacer, map { join_values($name, $_) } @$value
58 sub stringify_attributes {
62 while (my ($name, $value) = each %params) {
64 next if $_valueless_attributes{$name} && !$value;
65 $value = '' if !defined($value);
66 $value = join_values($name, $value) if ref $value && 'ARRAY' eq ref $value;
67 push @result, $_valueless_attributes{$name} ? escape($name) : escape($name) . '="' . escape($value) . '"';
70 return @result ? ' ' . join(' ', @result) : '';
74 my ($tag, $content, %params) = @_;
75 my $attributes = stringify_attributes(%params);
77 return "<${tag}${attributes}>" if !defined($content) && $_singleton_tags{$tag};
78 return "<${tag}${attributes}>${content}</${tag}>";
82 my ($name, $value, %attributes) = @_;
84 _set_id_attribute(\%attributes, $name);
85 $attributes{type} ||= 'text';
87 html_tag('input', undef, %attributes, name => $name, value => $value);
91 my ($name, $value, %attributes) = @_;
92 input_tag($name, $value, %attributes, type => 'hidden');
96 my ($name, $object, %attributes) = @_;
98 my $size = delete($attributes{size}) || 5;
100 $method =~ s/^.*\.//;
102 my $time_selection = input_tag("${name}_as_man_days_string", _call_on($object, "${method}_as_man_days_string"), %attributes, size => $size);
103 my $unit_selection = select_tag("${name}_as_man_days_unit", [[ 'h', $::locale->text('h') ], [ 'man_day', $::locale->text('MD') ]],
104 %attributes, default => _call_on($object, "${method}_as_man_days_unit"));
106 return $time_selection . $unit_selection;
112 $name =~ s/\[\+?\]/ _id() /ge; # give constructs with [] or [+] unique ids
113 $name =~ s/[^\w_]/_/g;
120 my ($name, $collection, %attributes) = @_;
122 _set_id_attribute(\%attributes, $name);
124 $collection = [] if defined($collection) && !ref($collection) && ($collection eq '');
126 my $with_filter = delete($attributes{with_filter});
127 my $fil_placeholder = delete($attributes{filter_placeholder});
128 my $value_key = delete($attributes{value_key}) || 'id';
129 my $title_key = delete($attributes{title_key}) || $value_key;
130 my $default_key = delete($attributes{default_key}) || 'selected';
131 my $default_val_key = delete($attributes{default_value_key});
132 my $default_coll = delete($attributes{default});
134 my $value_title_sub = delete($attributes{value_title_sub});
136 my $value_sub = delete($attributes{value_sub});
137 my $title_sub = delete($attributes{title_sub});
138 my $default_sub = delete($attributes{default_sub});
140 my $with_empty = delete($attributes{with_empty});
141 my $empty_title = delete($attributes{empty_title});
143 my $with_optgroups = delete($attributes{with_optgroups});
145 undef $default_key if $default_sub || $default_val_key;
147 my $normalize_entry = sub {
148 my ($type, $entry, $sub, $key) = @_;
150 return $sub->($entry) if $sub;
152 my $ref = ref($entry);
155 return $entry if $type eq 'value' || $type eq 'title';
159 if ( $ref eq 'ARRAY' ) {
160 return $entry->[ $type eq 'value' ? 0 : $type eq 'title' ? 1 : 2 ];
163 return $entry->{$key} if $ref eq 'HASH';
164 return $entry->$key if $type ne 'default' || $entry->can($key);
169 if (defined($default_coll) && !ref $default_coll) {
170 %selected = ($default_coll => 1);
172 } elsif (ref($default_coll) eq 'HASH') {
173 %selected = %{ $default_coll };
175 } elsif ($default_coll) {
176 $default_coll = [ $default_coll ] unless 'ARRAY' eq ref $default_coll;
178 %selected = $default_val_key ? map({ ($normalize_entry->('value', $_, undef, $default_val_key) => 1) } @{ $default_coll })
179 : map({ ($_ => 1) } @{ $default_coll });
182 my $list_to_code = sub {
183 my ($sub_collection) = @_;
185 if ('ARRAY' ne ref $sub_collection) {
186 $sub_collection = [ $sub_collection ];
190 foreach my $entry ( @{ $sub_collection } ) {
194 if ( $value_title_sub ) {
195 ($value, $title) = @{ $value_title_sub->($entry) };
198 $value = $normalize_entry->('value', $entry, $value_sub, $value_key);
199 $title = $normalize_entry->('title', $entry, $title_sub, $title_key);
202 my $default = $default_key ? $normalize_entry->('default', $entry, $default_sub, $default_key) : 0;
204 push(@options, [$value, $title, $selected{$value} || $default]);
207 return join '', map { html_tag('option', escape($_->[1]), value => $_->[0], selected => $_->[2]) } @options;
211 $code .= html_tag('option', escape($empty_title || ''), value => '') if $with_empty;
213 if (!$with_optgroups) {
214 $code .= $list_to_code->($collection);
217 $code .= join '', map {
218 my ($optgroup_title, $sub_collection) = @{ $_ };
219 html_tag('optgroup', $list_to_code->($sub_collection), label => $optgroup_title)
223 my $select_html = html_tag('select', $code, %attributes, name => $name);
228 if (($attributes{style} // '') =~ m{width: *(\d+) *px}i) {
229 $input_style = "width: " . ($1 - 22) . "px";
232 my $input_html = html_tag(
234 autocomplete => 'off',
236 id => $attributes{id} . '_filter',
237 'data-select-id' => $attributes{id},
238 (placeholder => $fil_placeholder) x !!$fil_placeholder,
239 (style => $input_style) x !!$input_style,
241 $select_html = html_tag('div', $input_html . $select_html, class => "filtered_select");
248 my ($name, %attributes) = @_;
250 my %label_attributes = map { (substr($_, 6) => $attributes{$_}) } grep { m{^label_} } keys %attributes;
251 delete @attributes{grep { m{^label_} } keys %attributes};
253 _set_id_attribute(\%attributes, $name);
255 $attributes{value} = 1 unless defined $attributes{value};
256 my $label = delete $attributes{label};
257 my $checkall = delete $attributes{checkall};
258 my $for_submit = delete $attributes{for_submit};
260 if ($attributes{checked}) {
261 $attributes{checked} = 'checked';
263 delete $attributes{checked};
267 $code .= hidden_tag($name, 0, %attributes, id => $attributes{id} . '_hidden') if $for_submit;
268 $code .= html_tag('input', undef, %attributes, name => $name, type => 'checkbox');
269 $code .= html_tag('label', $label, for => $attributes{id}, %label_attributes) if $label;
270 $code .= javascript(qq|\$('#$attributes{id}').checkall('$checkall');|) if $checkall;
275 sub radio_button_tag {
276 my ($name, %attributes) = @_;
278 my %label_attributes = map { (substr($_, 6) => $attributes{$_}) } grep { m{^label_} } keys %attributes;
279 delete @attributes{grep { m{^label_} } keys %attributes};
281 $attributes{value} = 1 unless exists $attributes{value};
283 _set_id_attribute(\%attributes, $name, 1);
284 my $label = delete $attributes{label};
286 _set_id_attribute(\%attributes, $name . '_' . $attributes{value});
288 if ($attributes{checked}) {
289 $attributes{checked} = 'checked';
291 delete $attributes{checked};
294 my $code = html_tag('input', undef, %attributes, name => $name, type => 'radio');
295 $code .= html_tag('label', $label, for => $attributes{id}, %label_attributes) if $label;
301 my ($onclick, $value, %attributes) = @_;
303 _set_id_attribute(\%attributes, $attributes{name}) if $attributes{name};
304 $attributes{type} ||= 'button';
306 $onclick = 'if (!confirm("'. _J(delete($attributes{confirm})) .'")) return false; ' . $onclick if $attributes{confirm};
308 html_tag('input', undef, %attributes, value => $value, (onclick => $onclick)x!!$onclick);
312 my ($name, $value, %attributes) = @_;
314 _set_id_attribute(\%attributes, $attributes{name}) if $attributes{name};
316 if ( $attributes{confirm} ) {
317 $attributes{onclick} = 'return confirm("'. _J(delete($attributes{confirm})) .'");';
320 input_tag($name, $value, %attributes, type => 'submit', class => 'submit');
323 sub ajax_submit_tag {
324 my ($url, $form_selector, $text, %attributes) = @_;
327 $form_selector = _J($form_selector);
328 my $onclick = qq|kivi.submit_ajax_form('${url}', '${form_selector}')|;
330 button_tag($onclick, $text, %attributes);
333 sub input_number_tag {
334 my ($name, $value, %params) = @_;
336 _set_id_attribute(\%params, $name);
337 my @onchange = $params{onchange} ? (onChange => delete $params{onchange}) : ();
338 my @classes = ('numeric');
339 push @classes, delete($params{class}) if $params{class};
340 my %class = @classes ? (class => join(' ', @classes)) : ();
342 $::request->layout->add_javascripts('kivi.Validator.js');
343 $::request->presenter->need_reinit_widgets($params{id});
346 $name, $::form->format_amount(\%::myconfig, $value, $params{precision}),
347 "data-validate" => "number",
356 html_tag('script', $data, type => 'text/javascript');
359 sub _set_id_attribute {
360 my ($attributes, $name, $unique) = @_;
362 if (!delete($attributes->{no_id}) && !$attributes->{id}) {
363 $attributes->{id} = name_to_id($name);
364 $attributes->{id} .= '_' . $attributes->{value} if $unique;
372 sub restricted_html {
375 $html_restricter ||= SL::HTML::Restrict->create;
376 return $html_restricter->process($value);
380 my ($name, $content, %attributes) = @_;
382 _set_id_attribute(\%attributes, $name);
383 $attributes{rows} *= 1; # required by standard
384 $attributes{cols} *= 1; # required by standard
386 html_tag('textarea', $content, %attributes, name => $name);
390 my ($href, $content, %params) = @_;
394 html_tag('a', $content, %params, href => $href);
396 # alias for compatibility
397 sub link { goto &link_tag }
400 my ($name, $value, %params) = @_;
402 _set_id_attribute(\%params, $name);
403 my @onchange = $params{onchange} ? (onChange => delete $params{onchange}) : ();
404 my @classes = $params{no_cal} || $params{readonly} ? () : ('datepicker');
405 push @classes, delete($params{class}) if $params{class};
406 my %class = @classes ? (class => join(' ', @classes)) : ();
408 $::request->layout->add_javascripts('kivi.Validator.js');
409 $::request->presenter->need_reinit_widgets($params{id});
411 $params{'data-validate'} = join(' ', "date", grep { $_ } (delete $params{'data-validate'}));
414 $name, blessed($value) ? $value->to_lxoffice : $value,
422 my ($content, %params) = @_;
423 return html_tag('div', $content, %params);
431 return html_tag('img', undef, %params);
443 SL::Presenter::Tag - Layouting / tag generation
451 [% P.select_tag('direction', [ [ 'left', 'To the left' ], [ 'right', 'To the right', 1 ] ]) %]
453 [% P.select_tag('direction', [ { direction => 'left', display => 'To the left' },
454 { direction => 'right', display => 'To the right' } ],
455 value_key => 'direction', title_key => 'display', default => 'right') %]
457 [% P.select_tag('direction', [ { direction => 'left', display => 'To the left' },
458 { direction => 'right', display => 'To the right', selected => 1 } ],
459 value_key => 'direction', title_key => 'display') %]
461 # Use an RDBO object and its n:m relationship as the default
462 # values. For example, a user can be a member of many groups. "All
463 # groups" is therefore the full collection and "$user->groups" is a
464 # list of RDBO AuthGroup objects whose IDs must match the ones in
465 # "All groups". This could look like the following:
466 [% P.select_tag('user.groups[]', SELF.all_groups, multiple=1,
467 default=SELF.user.groups, default_value_key='id' ) %]
471 A module modeled a bit after Rails' ActionView helpers. Several small
472 functions that create HTML tags from various kinds of data sources.
474 The C<id> attribute is usually calculated automatically. This can be
475 overridden by either specifying an C<id> attribute or by setting
480 =head2 LOW-LEVEL FUNCTIONS
484 =item C<html_tag $tag_name, $content_string, %attributes>
486 Creates an opening and closing HTML tag for C<$tag_name> and puts
487 C<$content_string> between the two. If C<$content_string> is undefined
488 or empty then only a E<lt>tag/E<gt> tag will be created. Attributes
489 are key/value pairs added to the opening tag.
491 C<$content_string> is not HTML escaped.
493 =item C<name_to_id $name>
495 Converts a name to a HTML id by replacing various characters.
497 =item C<stringify_attributes %items>
499 Creates a string from all elements in C<%items> suitable for usage as
500 HTML tag attributes. Keys and values are HTML escaped even though keys
501 must not contain non-ASCII characters for browsers to accept them.
503 =item C<restricted_html $html>
505 Returns HTML stripped of unknown tags. See L<SL::HTML::Restrict>.
509 =head2 HIGH-LEVEL FUNCTIONS
513 =item C<input_tag $name, $value, %attributes>
515 Creates a HTML 'input type=text' tag named C<$name> with the value
516 C<$value> and with arbitrary HTML attributes from C<%attributes>. The
517 tag's C<id> defaults to C<name_to_id($name)>.
519 =item C<submit_tag $name, $value, %attributes>
521 Creates a HTML 'input type=submit class=submit' tag named C<$name> with the
522 value C<$value> and with arbitrary HTML attributes from C<%attributes>. The
523 tag's C<id> defaults to C<name_to_id($name)>.
525 If C<$attributes{confirm}> is set then a JavaScript popup dialog will
526 be added via the C<onclick> handler asking the question given with
527 C<$attributes{confirm}>. The request is only submitted if the user
528 clicks the dialog's ok/yes button.
530 =item C<ajax_submit_tag $url, $form_selector, $text, %attributes>
532 Creates a HTML 'input type="button"' tag with a very specific onclick
533 handler that submits the form given by the jQuery selector
534 C<$form_selector> to the URL C<$url> (the actual JavaScript function
535 called for that is C<kivi.submit_ajax_form()> in
536 C<js/client_js.js>). The button's label will be C<$text>.
538 =item C<button_tag $onclick, $text, %attributes>
540 Creates a HTML 'input type="button"' tag with an onclick handler
541 C<$onclick> and a value of C<$text>. The button does not have a name
542 nor an ID by default.
544 If C<$attributes{confirm}> is set then a JavaScript popup dialog will
545 be prepended to the C<$onclick> handler asking the question given with
546 C<$attributes{confirm}>. The request is only submitted if the user
547 clicks the dialog's "ok/yes" button.
549 =item C<man_days_tag $name, $object, %attributes>
551 Creates two HTML inputs: a text input for entering a number and a drop
552 down box for chosing the unit (either 'man days' or 'hours').
554 C<$object> must be a L<Rose::DB::Object> instance using the
555 L<SL::DB::Helper::AttrDuration> helper.
557 C<$name> is supposed to be the name of the underlying column,
558 e.g. C<time_estimation> for an instance of
559 C<SL::DB::RequirementSpecItem>. If C<$name> has the form
560 C<prefix.method> then the full C<$name> is used for the input's base
561 names while the methods called on C<$object> are only the suffix. This
562 makes it possible to write statements like e.g.
564 [% P.man_days_tag("requirement_spec_item.time_estimation", SELF.item) %]
566 The attribute C<size> can be used to set the text input's size. It
569 =item C<hidden_tag $name, $value, %attributes>
571 Creates a HTML 'input type=hidden' tag named C<$name> with the value
572 C<$value> and with arbitrary HTML attributes from C<%attributes>. The
573 tag's C<id> defaults to C<name_to_id($name)>.
575 =item C<checkbox_tag $name, %attributes>
577 Creates a HTML 'input type=checkbox' tag named C<$name> with arbitrary
578 HTML attributes from C<%attributes>. The tag's C<id> defaults to
579 C<name_to_id($name)>. The tag's C<value> defaults to C<1>.
581 If C<%attributes> contains a key C<label> then a HTML 'label' tag is
582 created with said C<label>. No attribute named C<label> is created in
583 that case. Furthermore, all attributes whose names start with
584 C<label_> become attributes on the label tag without the C<label_>
585 prefix. For example, C<label_style='#ff0000'> will be turned into
586 C<style='#ff0000'> on the label tag, causing the text to become red.
588 If C<%attributes> contains a key C<checkall> then the value is taken as a
589 JQuery selector and clicking this checkbox will also toggle all checkboxes
590 matching the selector.
592 =item C<radio_button_tag $name, %attributes>
594 Creates a HTML 'input type=radio' tag named C<$name> with arbitrary
595 HTML attributes from C<%attributes>. The tag's C<value> defaults to
596 C<1>. The tag's C<id> defaults to C<name_to_id($name . "_" . $value)>.
598 If C<%attributes> contains a key C<label> then a HTML 'label' tag is
599 created with said C<label>. No attribute named C<label> is created in
600 that case. Furthermore, all attributes whose names start with
601 C<label_> become attributes on the label tag without the C<label_>
602 prefix. For example, C<label_style='#ff0000'> will be turned into
603 C<style='#ff0000'> on the label tag, causing the text to become red.
605 =item C<select_tag $name, \@collection, %attributes>
607 Creates an HTML 'select' tag named C<$name> with the contents of one
608 'E<lt>optionE<gt>' tag for each element in C<\@collection> and with arbitrary
609 HTML attributes from C<%attributes>. The value
610 to use and the title to display are extracted from the elements in
611 C<\@collection>. Each element can be one of four things:
615 =item 1. An array reference with at least two elements. The first element is
616 the value, the second element is its title. The third element is optional and and should contain a boolean.
617 If it is true, than the element will be used as default.
619 =item 2. A scalar. The scalar is both the value and the title.
621 =item 3. A hash reference. In this case C<%attributes> must contain
622 I<value_key>, I<title_key> and may contain I<default_key> keys that name the keys in the element to use
623 for the value, title and default respectively.
625 =item 4. A blessed reference. In this case C<%attributes> must contain
626 I<value_key>, I<title_key> and may contain I<default_key> keys that name functions called on the blessed
627 reference whose return values are used as the value, title and default
632 For cases 3 and 4 C<$attributes{value_key}> defaults to C<id>,
633 C<$attributes{title_key}> defaults to C<$attributes{value_key}> and
634 C<$attributes{default_key}> defaults to C<selected>. Note that
635 C<$attributes{default_key}> is set to C<undef> if
636 C<$attributes{default_value_key}> is used as well (see below).
638 In addition to pure keys/method you can also provide coderefs as I<value_sub>
639 and/or I<title_sub> and/or I<default_sub>. If present, these take precedence over keys or methods,
640 and are called with the element as first argument. It must return the value, title or default.
642 Lastly a joint coderef I<value_title_sub> may be provided, which in turn takes
643 precedence over the C<value_sub> and C<title_sub> subs. It will only be called once for each
644 element and must return a list of value and title.
646 If the option C<with_empty> is set then an empty element (value
647 C<undef>) will be used as the first element. The title to display for
648 this element can be set with the option C<empty_title> and defaults to
651 The tag's C<id> defaults to C<name_to_id($name)>.
653 The option C<default> can be quite a lot of things:
657 =item 1. A scalar value. This is the value of the entry that's
660 =item 2. A hash reference for C<multiple=1>. Whether or not an entry
661 is selected by default is looked up in this hash.
663 =item 3. An array reference containing scalar values. Same as 1., just
664 for the case of C<multiple=1>.
666 =item 4. If C<default_value_key> is given: an array reference of hash
667 references. For each hash reference the value belonging to the key
668 C<default_value_key> is treated as one value to select by
669 default. Constructs a hash that's treated like 3.
671 =item 5. If C<default_value_key> is given: an array reference of
672 blessed objects. For each object the value returne from calling the
673 function named C<default_value_key> on the object is treated as one
674 value to select by default. Constructs a hash that's treated like 3.
678 5. also applies to single RDBO instances (due to 'wantarray'
679 shenanigans assigning RDBO's relationships to a hash key will result
680 in a single RDBO object being assigned instead of an array reference
681 containing that single RDBO object).
683 If the option C<with_optgroups> is set then this function expects
684 C<\@collection> to be one level deeper. The upper-most level is
685 translated into an HTML C<optgroup> tag. So the structure becomes:
689 =item 1. Array of array references. Each element in the
690 C<\@collection> is converted into an optgroup.
692 =item 2. The optgroup's C<label> attribute will be set to the
693 first element in the array element. The second array element is then
694 converted to a list of C<option> tags as described above.
698 Example for use of optgroups:
700 # First in a controller:
702 [ t8("First optgroup with three items"),
703 [ { id => 42, name => "item one" },
704 { id => 54, name => "second item" },
705 { id => 23, name => "and the third one" },
707 [ t8("Another optgroup, with a lot of items from Rose"),
708 SL::DB::Manager::Customer->get_all_sorted ],
711 # Later in the template:
712 [% L.select_tag('the_selection', COLLECTION, with_optgroups=1, title_key='name') %]
722 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>,
723 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>