SL/Presenter/Part.pm

   1 package SL::Presenter::Part;
   2
   3 use strict;
   4
   5 use SL::DB::Part;
   6
   7 use Exporter qw(import);
   8 our @EXPORT = qw(part_picker);
   9
  10 sub part_picker {
  11   my ($self, $name, $value, %params) = @_;
  12
  13   $value = SL::DB::Manager::Part->find_by(id => $value) if $value && !ref $value;
  14   my $id = delete($params{id}) || $self->name_to_id($name);
  15
  16   my $ret =
  17     $self->input_tag($name, (ref $value && $value->can('id') ? $value->id : ''), class => 'part_autocomplete', type => 'hidden', id => $id) .
  18     join('', map { $params{$_} ? $self->input_tag("", delete $params{$_}, id => "${id}_${_}", type => 'hidden') : '' } qw(column type unit convertible_unit)) .
  19     $self->input_tag("", (ref $value && $value->can('description')) ? $value->description : '', id => "${id}_name", %params);
  20
  21   $::request->presenter->need_reinit_widgets($id);
  22
  23   $self->html_tag('span', $ret, class => 'part_picker');
  24 }
  25
  26 1;
  27
  28 __END__
  29
  30 =encoding utf-8
  31
  32 =head1 NAME
  33
  34 SL::Presenter::Part - Part lelated presenter stuff
  35
  36 =head1 SYNOPSIS
  37
  38 see L<SL::Presenter>
  39
  40 =head1 DESCRIPTION
  41
  42 see L<SL::Presenter>
  43
  44 =head1 FUNCTIONS
  45
  46 =over 4
  47
  48 =item C<part_picker $name, $value, %params>
  49
  50 All-in-one picker widget for parts. The name will be both id and name
  51 of the resulting hidden C<id> input field (but the ID can be
  52 overwritten with C<$params{id}>).
  53
  54 An additional dummy input will be generated which is used to find
  55 parts. For a detailed description of it's behaviour, see section
  56 C<PART PICKER SPECIFICATION>.
  57
  58 C<$value> can be a parts id or a C<Rose::DB:Object> instance.
  59
  60 If C<%params> contains C<type> only parts of this type will be used
  61 for autocompletion. You may comma separate multiple types as in
  62 C<part,assembly>.
  63
  64 If C<%params> contains C<unit> only parts with this unit will be used
  65 for autocompletion. You may comma separate multiple units as in
  66 C<h,min>.
  67
  68 If C<%params> contains C<convertible_unit> only parts with a unit
  69 that's convertible to unit will be used for autocompletion.
  70
  71 Obsolete parts will by default not displayed for selection. However they are
  72 accepted as default values and can persist during updates. As with other
  73 selectors though, they are not selectable once overridden.
  74
  75 Currently you must include C<js/autocomplete_part.js> in your controller, the
  76 presenter can not do this from the template.
  77
  78 =back
  79
  80 =head1 PART PICKER SPECIFICATION
  81
  82 The following list of design goals were applied:
  83
  84 =over 4
  85
  86 =item *
  87
  88 Parts should not be perceived by the user as distinct inputs of partnumber and
  89 description but as a single object
  90
  91 =item *
  92
  93 Easy to use without documentation for novice users
  94
  95 =item *
  96
  97 Fast to use with keyboard for experienced users
  98
  99 =item *
 100
 101 Possible to use without any keyboard interaction for mouse (or touchscreen)
 102 users
 103
 104 =item *
 105
 106 Must not leave the current page in event of ambiguity (cf. current select_item
 107 mechanism)
 108
 109 =item *
 110
 111 Should be useable with hand scanners or similar alternative keyboard devices
 112
 113 =item *
 114
 115 Should not require a feedback/check loop in the common case
 116
 117 =item *
 118
 119 Should not be constraint to exact matches
 120
 121 =back
 122
 123 The implementation consists of the following parts which will be referenced later:
 124
 125 =over 4
 126
 127 =item 1
 128
 129 A hidden input (id input), used to hold the id of the selected part. The only
 130 input that gets submitted
 131
 132 =item 2
 133
 134 An input (dummy input) containing a description of the currently selected part,
 135 also used by the user to search for parts
 136
 137 =item 3
 138
 139 A jquery.autocomplete mechanism attached to the dummy field
 140
 141 =item 4
 142
 143 A popup layer for both feedback and input of additional data in case of
 144 ambiguity.
 145
 146 =item 5
 147
 148 An internal status of the part picker, indicating wether id input and dummy
 149 input are consistent. After leaving the dummy input the part picker must
 150 place itself in a consistent status.
 151
 152 =item 6
 153
 154 A clickable icon (popup trigger) attached to the dummy input, which triggers the popup layer.
 155
 156 =back
 157
 158 =head1 BUGS
 159
 160 None atm :)
 161
 162 =head1 AUTHOR
 163
 164 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>
 165
 166 =cut