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;
49 sub stringify_attributes {
53 while (my ($name, $value) = each %params) {
55 next if $_valueless_attributes{$name} && !$value;
56 $value = '' if !defined($value);
57 push @result, $_valueless_attributes{$name} ? escape($name) : escape($name) . '="' . escape($value) . '"';
60 return @result ? ' ' . join(' ', @result) : '';
64 my ($tag, $content, %params) = @_;
65 my $attributes = stringify_attributes(%params);
67 return "<${tag}${attributes}>" if !defined($content) && $_singleton_tags{$tag};
68 return "<${tag}${attributes}>${content}</${tag}>";
72 my ($name, $value, %attributes) = @_;
74 _set_id_attribute(\%attributes, $name);
75 $attributes{type} ||= 'text';
77 html_tag('input', undef, %attributes, name => $name, value => $value);
81 my ($name, $value, %attributes) = @_;
82 input_tag($name, $value, %attributes, type => 'hidden');
86 my ($name, $object, %attributes) = @_;
88 my $size = delete($attributes{size}) || 5;
92 my $time_selection = input_tag("${name}_as_man_days_string", _call_on($object, "${method}_as_man_days_string"), %attributes, size => $size);
93 my $unit_selection = select_tag("${name}_as_man_days_unit", [[ 'h', $::locale->text('h') ], [ 'man_day', $::locale->text('MD') ]],
94 %attributes, default => _call_on($object, "${method}_as_man_days_unit"));
96 return $time_selection . $unit_selection;
102 $name =~ s/\[\+?\]/ _id() /ge; # give constructs with [] or [+] unique ids
103 $name =~ s/[^\w_]/_/g;
110 my ($name, $collection, %attributes) = @_;
112 _set_id_attribute(\%attributes, $name);
114 $collection = [] if defined($collection) && !ref($collection) && ($collection eq '');
116 my $with_filter = delete($attributes{with_filter});
117 my $fil_placeholder = delete($attributes{filter_placeholder});
118 my $value_key = delete($attributes{value_key}) || 'id';
119 my $title_key = delete($attributes{title_key}) || $value_key;
120 my $default_key = delete($attributes{default_key}) || 'selected';
121 my $default_val_key = delete($attributes{default_value_key});
122 my $default_coll = delete($attributes{default});
124 my $value_title_sub = delete($attributes{value_title_sub});
126 my $value_sub = delete($attributes{value_sub});
127 my $title_sub = delete($attributes{title_sub});
128 my $default_sub = delete($attributes{default_sub});
130 my $with_empty = delete($attributes{with_empty});
131 my $empty_title = delete($attributes{empty_title});
133 my $with_optgroups = delete($attributes{with_optgroups});
135 undef $default_key if $default_sub || $default_val_key;
137 my $normalize_entry = sub {
138 my ($type, $entry, $sub, $key) = @_;
140 return $sub->($entry) if $sub;
142 my $ref = ref($entry);
145 return $entry if $type eq 'value' || $type eq 'title';
149 if ( $ref eq 'ARRAY' ) {
150 return $entry->[ $type eq 'value' ? 0 : $type eq 'title' ? 1 : 2 ];
153 return $entry->{$key} if $ref eq 'HASH';
154 return $entry->$key if $type ne 'default' || $entry->can($key);
159 if (defined($default_coll) && !ref $default_coll) {
160 %selected = ($default_coll => 1);
162 } elsif (ref($default_coll) eq 'HASH') {
163 %selected = %{ $default_coll };
165 } elsif ($default_coll) {
166 $default_coll = [ $default_coll ] unless 'ARRAY' eq ref $default_coll;
168 %selected = $default_val_key ? map({ ($normalize_entry->('value', $_, undef, $default_val_key) => 1) } @{ $default_coll })
169 : map({ ($_ => 1) } @{ $default_coll });
172 my $list_to_code = sub {
173 my ($sub_collection) = @_;
175 if ('ARRAY' ne ref $sub_collection) {
176 $sub_collection = [ $sub_collection ];
180 foreach my $entry ( @{ $sub_collection } ) {
184 if ( $value_title_sub ) {
185 ($value, $title) = @{ $value_title_sub->($entry) };
188 $value = $normalize_entry->('value', $entry, $value_sub, $value_key);
189 $title = $normalize_entry->('title', $entry, $title_sub, $title_key);
192 my $default = $default_key ? $normalize_entry->('default', $entry, $default_sub, $default_key) : 0;
194 push(@options, [$value, $title, $selected{$value} || $default]);
197 return join '', map { html_tag('option', escape($_->[1]), value => $_->[0], selected => $_->[2]) } @options;
201 $code .= html_tag('option', escape($empty_title || ''), value => '') if $with_empty;
203 if (!$with_optgroups) {
204 $code .= $list_to_code->($collection);
207 $code .= join '', map {
208 my ($optgroup_title, $sub_collection) = @{ $_ };
209 html_tag('optgroup', $list_to_code->($sub_collection), label => $optgroup_title)
213 my $select_html = html_tag('select', $code, %attributes, name => $name);
218 if (($attributes{style} // '') =~ m{width: *(\d+) *px}i) {
219 $input_style = "width: " . ($1 - 22) . "px";
222 my $input_html = html_tag(
224 autocomplete => 'off',
226 id => $attributes{id} . '_filter',
227 'data-select-id' => $attributes{id},
228 (placeholder => $fil_placeholder) x !!$fil_placeholder,
229 (style => $input_style) x !!$input_style,
231 $select_html = html_tag('div', $input_html . $select_html, class => "filtered_select");
238 my ($name, %attributes) = @_;
240 _set_id_attribute(\%attributes, $name);
242 $attributes{value} = 1 unless defined $attributes{value};
243 my $label = delete $attributes{label};
244 my $checkall = delete $attributes{checkall};
245 my $for_submit = delete $attributes{for_submit};
247 if ($attributes{checked}) {
248 $attributes{checked} = 'checked';
250 delete $attributes{checked};
254 $code .= hidden_tag($name, 0, %attributes, id => $attributes{id} . '_hidden') if $for_submit;
255 $code .= html_tag('input', undef, %attributes, name => $name, type => 'checkbox');
256 $code .= html_tag('label', $label, for => $attributes{id}) if $label;
257 $code .= javascript(qq|\$('#$attributes{id}').checkall('$checkall');|) if $checkall;
262 sub radio_button_tag {
263 my ($name, %attributes) = @_;
265 $attributes{value} = 1 unless exists $attributes{value};
267 _set_id_attribute(\%attributes, $name, 1);
268 my $label = delete $attributes{label};
270 _set_id_attribute(\%attributes, $name . '_' . $attributes{value});
272 if ($attributes{checked}) {
273 $attributes{checked} = 'checked';
275 delete $attributes{checked};
278 my $code = html_tag('input', undef, %attributes, name => $name, type => 'radio');
279 $code .= html_tag('label', $label, for => $attributes{id}) if $label;
285 my ($onclick, $value, %attributes) = @_;
287 _set_id_attribute(\%attributes, $attributes{name}) if $attributes{name};
288 $attributes{type} ||= 'button';
290 $onclick = 'if (!confirm("'. _J(delete($attributes{confirm})) .'")) return false; ' . $onclick if $attributes{confirm};
292 html_tag('input', undef, %attributes, value => $value, onclick => $onclick);
296 my ($name, $value, %attributes) = @_;
298 _set_id_attribute(\%attributes, $attributes{name}) if $attributes{name};
300 if ( $attributes{confirm} ) {
301 $attributes{onclick} = 'return confirm("'. _J(delete($attributes{confirm})) .'");';
304 input_tag($name, $value, %attributes, type => 'submit', class => 'submit');
307 sub ajax_submit_tag {
308 my ($url, $form_selector, $text, %attributes) = @_;
311 $form_selector = _J($form_selector);
312 my $onclick = qq|kivi.submit_ajax_form('${url}', '${form_selector}')|;
314 button_tag($onclick, $text, %attributes);
317 sub input_number_tag {
318 my ($name, $value, %params) = @_;
320 _set_id_attribute(\%params, $name);
321 my @onchange = $params{onchange} ? (onChange => delete $params{onchange}) : ();
322 my @classes = ('numeric');
323 push @classes, delete($params{class}) if $params{class};
324 my %class = @classes ? (class => join(' ', @classes)) : ();
326 $::request->layout->add_javascripts('kivi.Validator.js');
327 $::request->presenter->need_reinit_widgets($params{id});
330 $name, $::form->format_amount(\%::myconfig, $value, $params{precision}),
331 "data-validate" => "number",
340 html_tag('script', $data, type => 'text/javascript');
343 sub _set_id_attribute {
344 my ($attributes, $name, $unique) = @_;
346 if (!delete($attributes->{no_id}) && !$attributes->{id}) {
347 $attributes->{id} = name_to_id($name);
348 $attributes->{id} .= '_' . $attributes->{value} if $unique;
356 sub restricted_html {
359 $html_restricter ||= SL::HTML::Restrict->create;
360 return $html_restricter->process($value);
364 my ($name, $content, %attributes) = @_;
366 _set_id_attribute(\%attributes, $name);
367 $attributes{rows} *= 1; # required by standard
368 $attributes{cols} *= 1; # required by standard
370 html_tag('textarea', $content, %attributes, name => $name);
374 my ($href, $content, %params) = @_;
378 html_tag('a', $content, %params, href => $href);
380 # alias for compatibility
381 sub link { goto &link_tag }
384 my ($name, $value, %params) = @_;
386 _set_id_attribute(\%params, $name);
387 my @onchange = $params{onchange} ? (onChange => delete $params{onchange}) : ();
388 my @classes = $params{no_cal} || $params{readonly} ? () : ('datepicker');
389 push @classes, delete($params{class}) if $params{class};
390 my %class = @classes ? (class => join(' ', @classes)) : ();
392 $::request->layout->add_javascripts('kivi.Validator.js');
393 $::request->presenter->need_reinit_widgets($params{id});
395 $params{'data-validate'} = join(' ', "date", grep { $_ } (delete $params{'data-validate'}));
398 $name, blessed($value) ? $value->to_lxoffice : $value,
406 my ($content, %params) = @_;
407 return html_tag('div', $content, %params);
415 return html_tag('img', undef, %params);
427 SL::Presenter::Tag - Layouting / tag generation
435 [% P.select_tag('direction', [ [ 'left', 'To the left' ], [ 'right', 'To the right', 1 ] ]) %]
437 [% P.select_tag('direction', [ { direction => 'left', display => 'To the left' },
438 { direction => 'right', display => 'To the right' } ],
439 value_key => 'direction', title_key => 'display', default => 'right') %]
441 [% P.select_tag('direction', [ { direction => 'left', display => 'To the left' },
442 { direction => 'right', display => 'To the right', selected => 1 } ],
443 value_key => 'direction', title_key => 'display') %]
445 # Use an RDBO object and its n:m relationship as the default
446 # values. For example, a user can be a member of many groups. "All
447 # groups" is therefore the full collection and "$user->groups" is a
448 # list of RDBO AuthGroup objects whose IDs must match the ones in
449 # "All groups". This could look like the following:
450 [% P.select_tag('user.groups[]', SELF.all_groups, multiple=1,
451 default=SELF.user.groups, default_value_key='id' ) %]
455 A module modeled a bit after Rails' ActionView helpers. Several small
456 functions that create HTML tags from various kinds of data sources.
458 The C<id> attribute is usually calculated automatically. This can be
459 overridden by either specifying an C<id> attribute or by setting
464 =head2 LOW-LEVEL FUNCTIONS
468 =item C<html_tag $tag_name, $content_string, %attributes>
470 Creates an opening and closing HTML tag for C<$tag_name> and puts
471 C<$content_string> between the two. If C<$content_string> is undefined
472 or empty then only a E<lt>tag/E<gt> tag will be created. Attributes
473 are key/value pairs added to the opening tag.
475 C<$content_string> is not HTML escaped.
477 =item C<name_to_id $name>
479 Converts a name to a HTML id by replacing various characters.
481 =item C<stringify_attributes %items>
483 Creates a string from all elements in C<%items> suitable for usage as
484 HTML tag attributes. Keys and values are HTML escaped even though keys
485 must not contain non-ASCII characters for browsers to accept them.
487 =item C<restricted_html $html>
489 Returns HTML stripped of unknown tags. See L<SL::HTML::Restrict>.
493 =head2 HIGH-LEVEL FUNCTIONS
497 =item C<input_tag $name, $value, %attributes>
499 Creates a HTML 'input type=text' tag named C<$name> with the value
500 C<$value> and with arbitrary HTML attributes from C<%attributes>. The
501 tag's C<id> defaults to C<name_to_id($name)>.
503 =item C<submit_tag $name, $value, %attributes>
505 Creates a HTML 'input type=submit class=submit' tag named C<$name> with the
506 value C<$value> and with arbitrary HTML attributes from C<%attributes>. The
507 tag's C<id> defaults to C<name_to_id($name)>.
509 If C<$attributes{confirm}> is set then a JavaScript popup dialog will
510 be added via the C<onclick> handler asking the question given with
511 C<$attributes{confirm}>. The request is only submitted if the user
512 clicks the dialog's ok/yes button.
514 =item C<ajax_submit_tag $url, $form_selector, $text, %attributes>
516 Creates a HTML 'input type="button"' tag with a very specific onclick
517 handler that submits the form given by the jQuery selector
518 C<$form_selector> to the URL C<$url> (the actual JavaScript function
519 called for that is C<kivi.submit_ajax_form()> in
520 C<js/client_js.js>). The button's label will be C<$text>.
522 =item C<button_tag $onclick, $text, %attributes>
524 Creates a HTML 'input type="button"' tag with an onclick handler
525 C<$onclick> and a value of C<$text>. The button does not have a name
526 nor an ID by default.
528 If C<$attributes{confirm}> is set then a JavaScript popup dialog will
529 be prepended to the C<$onclick> handler asking the question given with
530 C<$attributes{confirm}>. The request is only submitted if the user
531 clicks the dialog's "ok/yes" button.
533 =item C<man_days_tag $name, $object, %attributes>
535 Creates two HTML inputs: a text input for entering a number and a drop
536 down box for chosing the unit (either 'man days' or 'hours').
538 C<$object> must be a L<Rose::DB::Object> instance using the
539 L<SL::DB::Helper::AttrDuration> helper.
541 C<$name> is supposed to be the name of the underlying column,
542 e.g. C<time_estimation> for an instance of
543 C<SL::DB::RequirementSpecItem>. If C<$name> has the form
544 C<prefix.method> then the full C<$name> is used for the input's base
545 names while the methods called on C<$object> are only the suffix. This
546 makes it possible to write statements like e.g.
548 [% P.man_days_tag("requirement_spec_item.time_estimation", SELF.item) %]
550 The attribute C<size> can be used to set the text input's size. It
553 =item C<hidden_tag $name, $value, %attributes>
555 Creates a HTML 'input type=hidden' tag named C<$name> with the value
556 C<$value> and with arbitrary HTML attributes from C<%attributes>. The
557 tag's C<id> defaults to C<name_to_id($name)>.
559 =item C<checkbox_tag $name, %attributes>
561 Creates a HTML 'input type=checkbox' tag named C<$name> with arbitrary
562 HTML attributes from C<%attributes>. The tag's C<id> defaults to
563 C<name_to_id($name)>. The tag's C<value> defaults to C<1>.
565 If C<%attributes> contains a key C<label> then a HTML 'label' tag is
566 created with said C<label>. No attribute named C<label> is created in
569 If C<%attributes> contains a key C<checkall> then the value is taken as a
570 JQuery selector and clicking this checkbox will also toggle all checkboxes
571 matching the selector.
573 =item C<radio_button_tag $name, %attributes>
575 Creates a HTML 'input type=radio' tag named C<$name> with arbitrary
576 HTML attributes from C<%attributes>. The tag's C<value> defaults to
577 C<1>. The tag's C<id> defaults to C<name_to_id($name . "_" . $value)>.
579 If C<%attributes> contains a key C<label> then a HTML 'label' tag is
580 created with said C<label>. No attribute named C<label> is created in
583 =item C<select_tag $name, \@collection, %attributes>
585 Creates an HTML 'select' tag named C<$name> with the contents of one
586 'E<lt>optionE<gt>' tag for each element in C<\@collection> and with arbitrary
587 HTML attributes from C<%attributes>. The value
588 to use and the title to display are extracted from the elements in
589 C<\@collection>. Each element can be one of four things:
593 =item 1. An array reference with at least two elements. The first element is
594 the value, the second element is its title. The third element is optional and and should contain a boolean.
595 If it is true, than the element will be used as default.
597 =item 2. A scalar. The scalar is both the value and the title.
599 =item 3. A hash reference. In this case C<%attributes> must contain
600 I<value_key>, I<title_key> and may contain I<default_key> keys that name the keys in the element to use
601 for the value, title and default respectively.
603 =item 4. A blessed reference. In this case C<%attributes> must contain
604 I<value_key>, I<title_key> and may contain I<default_key> keys that name functions called on the blessed
605 reference whose return values are used as the value, title and default
610 For cases 3 and 4 C<$attributes{value_key}> defaults to C<id>,
611 C<$attributes{title_key}> defaults to C<$attributes{value_key}> and
612 C<$attributes{default_key}> defaults to C<selected>. Note that
613 C<$attributes{default_key}> is set to C<undef> if
614 C<$attributes{default_value_key}> is used as well (see below).
616 In addition to pure keys/method you can also provide coderefs as I<value_sub>
617 and/or I<title_sub> and/or I<default_sub>. If present, these take precedence over keys or methods,
618 and are called with the element as first argument. It must return the value, title or default.
620 Lastly a joint coderef I<value_title_sub> may be provided, which in turn takes
621 precedence over the C<value_sub> and C<title_sub> subs. It will only be called once for each
622 element and must return a list of value and title.
624 If the option C<with_empty> is set then an empty element (value
625 C<undef>) will be used as the first element. The title to display for
626 this element can be set with the option C<empty_title> and defaults to
629 The tag's C<id> defaults to C<name_to_id($name)>.
631 The option C<default> can be quite a lot of things:
635 =item 1. A scalar value. This is the value of the entry that's
638 =item 2. A hash reference for C<multiple=1>. Whether or not an entry
639 is selected by default is looked up in this hash.
641 =item 3. An array reference containing scalar values. Same as 1., just
642 for the case of C<multiple=1>.
644 =item 4. If C<default_value_key> is given: an array reference of hash
645 references. For each hash reference the value belonging to the key
646 C<default_value_key> is treated as one value to select by
647 default. Constructs a hash that's treated like 3.
649 =item 5. If C<default_value_key> is given: an array reference of
650 blessed objects. For each object the value returne from calling the
651 function named C<default_value_key> on the object is treated as one
652 value to select by default. Constructs a hash that's treated like 3.
656 5. also applies to single RDBO instances (due to 'wantarray'
657 shenanigans assigning RDBO's relationships to a hash key will result
658 in a single RDBO object being assigned instead of an array reference
659 containing that single RDBO object).
661 If the option C<with_optgroups> is set then this function expects
662 C<\@collection> to be one level deeper. The upper-most level is
663 translated into an HTML C<optgroup> tag. So the structure becomes:
667 =item 1. Array of array references. Each element in the
668 C<\@collection> is converted into an optgroup.
670 =item 2. The optgroup's C<label> attribute will be set to the
671 first element in the array element. The second array element is then
672 converted to a list of C<option> tags as described above.
676 Example for use of optgroups:
678 # First in a controller:
680 [ t8("First optgroup with three items"),
681 [ { id => 42, name => "item one" },
682 { id => 54, name => "second item" },
683 { id => 23, name => "and the third one" },
685 [ t8("Another optgroup, with a lot of items from Rose"),
686 SL::DB::Manager::Customer->get_all_sorted ],
689 # Later in the template:
690 [% L.select_tag('the_selection', COLLECTION, with_optgroups=1, title_key='name') %]
700 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>,
701 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>