CTR Mehr Benutzerparameter aus dem POD erlauben und prüfen
[kivitendo-erp.git] / SL / Presenter / Part.pm
1 package SL::Presenter::Part;
2
3 use strict;
4
5 use SL::DB::Part;
6 use SL::DB::PartClassification;
7 use SL::Locale::String qw(t8);
8 use SL::Presenter::EscapedText qw(escape is_escaped);
9 use SL::Presenter::Tag qw(input_tag html_tag name_to_id select_tag);
10
11 use Exporter qw(import);
12 our @EXPORT_OK = qw(
13   part_picker part select_classification classification_abbreviation
14   type_abbreviation separate_abbreviation typeclass_abbreviation
15 );
16 our %EXPORT_TAGS = (ALL => \@EXPORT_OK);
17
18 use Carp;
19
20 sub part {
21   my ($part, %params) = @_;
22
23   $params{display} ||= 'inline';
24
25   croak "Unknown display type '$params{display}'" unless $params{display} =~ m/^(?:inline|table-cell)$/;
26
27   my $text = join '', (
28     $params{no_link} ? '' : '<a href="controller.pl?action=Part/edit&part.id=' . escape($part->id) . '">',
29     escape($part->partnumber),
30     $params{no_link} ? '' : '</a>',
31   );
32
33   is_escaped($text);
34 }
35
36 sub part_picker {
37   my ($name, $value, %params) = @_;
38
39   $value = SL::DB::Manager::Part->find_by(id => $value) if $value && !ref $value;
40   my $id = $params{id} || name_to_id($name);
41
42   my @classes = $params{class} ? ($params{class}) : ();
43   push @classes, 'part_autocomplete';
44
45   my $ret =
46     input_tag($name, (ref $value && $value->can('id') ? $value->id : ''), class => "@classes", type => 'hidden', id => $id,
47       'data-part-picker-data' => JSON::to_json(\%params),
48     ) .
49     input_tag("", ref $value ? $value->displayable_name : '', id => "${id}_name", %params);
50
51   $::request->layout->add_javascripts('kivi.Part.js');
52   $::request->presenter->need_reinit_widgets($id);
53
54   html_tag('span', $ret, class => 'part_picker');
55 }
56
57 sub picker { goto &part_picker }
58
59 #
60 # shortcut for article type
61 #
62 sub type_abbreviation {
63   my ($part_type) = @_;
64
65   return ''                                               if !$part_type;
66   return $::locale->text('Assembly (typeabbreviation)')   if $part_type eq 'assembly';
67   return $::locale->text('Part (typeabbreviation)')       if $part_type eq 'part';
68   return $::locale->text('Assortment (typeabbreviation)') if $part_type eq 'assortment';
69   return $::locale->text('Service (typeabbreviation)');
70 }
71
72 #
73 # Translations for Abbreviations:
74 #
75 # $::locale->text('None (typeabbreviation)')
76 # $::locale->text('Purchase (typeabbreviation)')
77 # $::locale->text('Sales (typeabbreviation)')
78 # $::locale->text('Merchandise (typeabbreviation)')
79 # $::locale->text('Production (typeabbreviation)')
80 #
81 # and for descriptions
82 # $::locale->text('Purchase')
83 # $::locale->text('Sales')
84 # $::locale->text('Merchandise')
85 # $::locale->text('Production')
86
87 #
88 # shortcut for article type
89 #
90 sub classification_abbreviation {
91   my ($id) = @_;
92
93   return '' if !$id;
94
95   SL::DB::Manager::PartClassification->cache_all();
96   my $obj = SL::DB::PartClassification->load_cached($id);
97   $obj && $obj->abbreviation ? t8($obj->abbreviation) : '';
98 }
99
100 sub typeclass_abbreviation {
101   my ($part) = @_;
102   return '' if !$part || !$part->isa('SL::DB::Part');
103   return type_abbreviation($part->part_type) . classification_abbreviation($part->classification_id);
104 }
105
106 #
107 # shortcut for article type
108 #
109 sub separate_abbreviation {
110   my ($id) = @_;
111
112   return '' if !$id;
113
114   SL::DB::Manager::PartClassification->cache_all();
115   my $obj = SL::DB::PartClassification->load_cached($id);
116   $obj && $obj->abbreviation && $obj->report_separate ? t8($obj->abbreviation) : '';
117 }
118
119 #
120 # generate selection tag
121 #
122 sub select_classification {
123   my ($name, %attributes) = @_;
124
125   $attributes{value_key} = 'id';
126   $attributes{title_key} = 'description';
127
128   my $classification_type_filter = delete $attributes{type} // [];
129
130   my $collection = SL::DB::Manager::PartClassification->get_all_sorted( where => $classification_type_filter );
131   $_->description($::locale->text($_->description)) for @{ $collection };
132   select_tag( $name, $collection, %attributes );
133 }
134
135 1;
136
137 __END__
138
139 =encoding utf-8
140
141 =head1 NAME
142
143 SL::Presenter::Part - Part related presenter stuff
144
145 =head1 SYNOPSIS
146
147   # Create an html link for editing/opening a part/service/assembly
148   my $object = SL::DB::Manager::Part->get_first;
149   my $html   = SL::Presenter->get->part($object, display => 'inline');
150
151 see also L<SL::Presenter>
152
153 =head1 DESCRIPTION
154
155 see L<SL::Presenter>
156
157 =head1 FUNCTIONS
158
159 =over 2
160
161 =item C<part, $object, %params>
162
163 Returns a rendered version (actually an instance of
164 L<SL::Presenter::EscapedText>) of the part object C<$object>
165
166 C<%params> can include:
167
168 =over 4
169
170 =item * display
171
172 Either C<inline> (the default) or C<table-cell>. At the moment both
173 representations are identical and produce the part's name linked
174 to the corresponding 'edit' action.
175
176 =back
177
178 =back
179
180 =over 2
181
182 =item C<classification_abbreviation $classification_id>
183
184 Returns the shortcut of the classification
185
186 =back
187
188 =over 2
189
190 =item C<separate_abbreviation $classification_id>
191
192 Returns the shortcut of the classification if the classification has the separate flag set.
193
194 =back
195
196 =over 2
197
198 =item C<select_classification $name,%params>
199
200 Returns an HTML select tag with all available classifications.
201
202 C<%params> can include:
203
204 =over 4
205
206 =item * default
207
208 The id of the selected item.
209
210 =back
211
212 =back
213
214 =over 2
215
216 =item C<part_picker $name, $value, %params>
217
218 All-in-one picker widget for parts. The name will be both id and name
219 of the resulting hidden C<id> input field (but the ID can be
220 overwritten with C<$params{id}>).
221
222 An additional dummy input will be generated which is used to find
223 parts. For a detailed description of its behaviour, see section
224 C<PART PICKER SPECIFICATION>.
225
226 C<$value> can be a parts id or a C<Rose::DB:Object> instance.
227
228 If C<%params> contains C<part_type> only parts of this type will be used
229 for autocompletion. You may comma separate multiple types as in
230 C<part,assembly>.
231
232 If C<%params> contains C<status> only parts of this status will be used
233 for autocompletion. C<status> can be one of the following strings:
234 C<active>, C<obsolete> or C<all>. C<active> is the default if C<status> is
235 not given.
236
237 If C<%params> contains C<unit> only parts with this unit will be used
238 for autocompletion. You may comma separate multiple units as in
239 C<h,min>.
240
241 If C<%params> contains C<convertible_unit> only parts with a unit
242 that's convertible to unit will be used for autocompletion.
243
244 If C<%params> contains C<with_makemodel> or C<with_customer_partnumber> even
245 parts will be used for autocompletion which partnumber is a vendor partnumber
246 (makemodel) or a customer partnumber.
247
248 If C<%params> contains C<multiple> an alternative popup will be opened,
249 allowing multiple items to be selected. Note however that this requires
250 an additional callback C<set_multi_items> to work.
251 Also note that you can set C<multiple> to 0 (or not set C<multiple>) on
252 creation of the picker, but can open the alternative multi select popup
253 with js like this:
254 C<$("#pp_id").data("part_picker").o.multiple=1; $("#pp_id").data("part_picker").open_dialog()'>
255 where C<pp_id> is the dom id of the part picker.
256 Or you can even do it the other way round setting C<multiple> to 1 on creation
257 and open a single selection popup with js.
258
259 If C<%params> contains C<multiple_pos_input> an input field with the dom id
260 C<multi_items_position> will be rendered in the alternative popup.
261 This can be used in the callback for C<set_multi_items> to controll the
262 input postion for the items.
263
264 If C<%params> contains C<multiple_limit> the alternative popup will not
265 show any results if there are more than C<multiple_limit> results. A warning
266 message is displayed in this case. Set C<multiple_limit> to 0 to disable
267 the limitation. The limit defaults to 100.
268
269 Obsolete parts will by default not be displayed for selection. However they are
270 accepted as default values and can persist during updates. As with other
271 selectors though, they are not selectable once overridden.
272
273 C<part_picker> will register it's javascript for inclusion in the next header
274 rendering. If you write a standard controller that only calls C<render> once, it
275 will just work. In case the header is generated in a different render call
276 (multiple blocks, ajax, old C<bin/mozilla> style controllers) you need to
277 include C<kivi.Part.js> yourself.
278
279 On pressing <enter> the picker will try to commit the current selection,
280 resulting in one of the following events, whose corresponding callbacks can be
281 set in C<params.actions>:
282
283 =over 4
284
285 =item * C<commit_one>
286
287 If exactly one element matches the input, the internal id will be set to this
288 id, the internal state will be set to C<PICKED> and the C<change> event on the
289 picker will be fired. Additionally, if C<params> contains C<fat_set_item> a
290 special event C<set_item:PartPicker> will be fired which is guaranteed to
291 contain a complete JSON representation of the part.
292
293 After that the action C<commit_one> will be executed, which defaults to
294 clicking a button with id C<update_button> for backward compatibility reasons.
295
296 =item * C<commit_many>
297
298 If more than one element matches the input, the internal state will be set to
299 undefined.
300
301 After that the action C<commit_one> will be executed, which defaults to
302 opening a popup dialog for graphical interaction.
303
304 =item * C<commit_none>
305
306 If no element matches the input, the internal state will be set to undefined.
307
308 If an action for C<commit_none> exists, it will be called with the picker
309 object and current term. The caller can then implement creation of new parts.
310
311 =back
312
313 =back
314
315 =head1 PART PICKER SPECIFICATION
316
317 The following list of design goals were applied:
318
319 =over 4
320
321 =item *
322
323 Parts should not be perceived by the user as distinct inputs of partnumber and
324 description but as a single object
325
326 =item *
327
328 Easy to use without documentation for novice users
329
330 =item *
331
332 Fast to use with keyboard for experienced users
333
334 =item *
335
336 Possible to use without any keyboard interaction for mouse (or touchscreen)
337 users
338
339 =item *
340
341 Must not leave the current page in event of ambiguity (cf. current select_item
342 mechanism)
343
344 =item *
345
346 Should be useable with hand scanners or similar alternative keyboard devices
347
348 =item *
349
350 Should not require a feedback/check loop in the common case
351
352 =item *
353
354 Should not be constrained to exact matches
355
356 =item *
357
358 Must be atomic
359
360 =item *
361
362 Action should be overridable
363
364 =back
365
366 The implementation consists of the following parts which will be referenced later:
367
368 =over 4
369
370 =item 1
371
372 A hidden input (id input), used to hold the id of the selected part. The only
373 input that gets submitted
374
375 =item 2
376
377 An input (dummy input) containing a description of the currently selected part,
378 also used by the user to search for parts
379
380 =item 3
381
382 A jquery.autocomplete mechanism attached to the dummy field
383
384 =item 4
385
386 A popup layer for both feedback and input of additional data in case of
387 ambiguity.
388
389 =item 5
390
391 An internal status of the part picker, indicating whether id input and dummy
392 input are consistent. After leaving the dummy input the part picker must
393 place itself in a consistent status.
394
395 =item 6
396
397 A clickable icon (popup trigger) attached to the dummy input, which triggers the popup layer.
398
399 =back
400
401 =head1 BUGS
402
403 None atm :)
404
405 =head1 AUTHOR
406
407 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>
408
409 Martin Helmling E<lt>martin.helmling@opendynamic.deE<gt>
410
411 =cut