Part: doku update

[mfinanz.git] / SL / Presenter / Part.pm

diff --git a/SL/Presenter/Part.pm b/SL/Presenter/Part.pm
index 4bd45ca41130d841e87b60f2ab7cbb5756f5634b..26f296c7c80c65bd5b4f06524885470004ba25d7 100644 (file)
--- a/SL/Presenter/Part.pm
+++ b/SL/Presenter/Part.pm
@@ -30,19 +30,18 @@ sub part_picker {
   my ($self, $name, $value, %params) = @_;
 
   $value = SL::DB::Manager::Part->find_by(id => $value) if $value && !ref $value;
-  my $id = delete($params{id}) || $self->name_to_id($name);
-  my $fat_set_item = delete $params{fat_set_item};
+  my $id = $params{id} || $self->name_to_id($name);
 
   my @classes = $params{class} ? ($params{class}) : ();
   push @classes, 'part_autocomplete';
-  push @classes, 'partpicker_fat_set_item' if $fat_set_item;
 
   my $ret =
-    $self->input_tag($name, (ref $value && $value->can('id') ? $value->id : ''), class => "@classes", type => 'hidden', id => $id) .
-    join('', map { $params{$_} ? $self->input_tag("", delete $params{$_}, id => "${id}_${_}", type => 'hidden') : '' } qw(part_type classification_id unit convertible_unit)) .
+    $self->input_tag($name, (ref $value && $value->can('id') ? $value->id : ''), class => "@classes", type => 'hidden', id => $id,
+      'data-part-picker-data' => JSON::to_json(\%params),
+    ) .
     $self->input_tag("", ref $value ? $value->displayable_name : '', id => "${id}_name", %params);
 
-  $::request->layout->add_javascripts('autocomplete_part.js');
+  $::request->layout->add_javascripts('kivi.Part.js');
   $::request->presenter->need_reinit_widgets($id);
 
   $self->html_tag('span', $ret, class => 'part_picker');
@@ -221,10 +220,47 @@ accepted as default values and can persist during updates. As with other
 selectors though, they are not selectable once overridden.
 
 C<part_picker> will register it's javascript for inclusion in the next header
-rendering. If you write a standard controller that only call C<render> once, it
-will just work.  In case the header is generated in a different render call
+rendering. If you write a standard controller that only calls C<render> once, it
+will just work. In case the header is generated in a different render call
 (multiple blocks, ajax, old C<bin/mozilla> style controllers) you need to
-include C<js/autocomplete_part.js> yourself.
+include C<kivi.Part.js> yourself.
+
+On pressing <enter> the picker will try to commit the current selection,
+resulting in one of the following events, whose corresponding callbacks can be
+set in C<params.actions>:
+
+=over 4
+
+=item * C<commit_one>
+
+If exactly one element matches the input, the internal id will set to this id,
+the internal state will be set to C<PICKED> and the C<change> even on the
+picker will be fired. Additionally, if C<params> contain C<fat_set_item>
+a special event C<set_item:PartPicker> will be fired which is guaranteed to
+contain a complete JSON representation of the part.
+
+After that the action C<commit_one> will be executed, which defaults to
+clicking a button with id C<update_button> for backward compatibility reasons.
+
+=item * C<commit_many>
+
+If more than one element matches the input, the internal state will be set to
+undefined.
+
+After that the action C<commit_one> will be executed, which defaults to
+opening a popup dialog for graphical interaction. If C<params> contain
+C<multiple> an alternative popup will be opened, allowing multiple items to be
+selected. Note however that this requires an additional callback
+C<set_multi_items> to work.
+
+=item * C<commit_none>
+
+If no element matches the input, the internal state will be set to undefined.
+
+If an action for C<commit_none> exists, it will be called with the picker
+object and current term. The caller can then implement creation of new parts.
+
+=back
 
 =back
 
@@ -269,6 +305,14 @@ Should not require a feedback/check loop in the common case
 
 Should not be constrained to exact matches
 
+=item *
+
+Must be atomic
+
+=item *
+
+Action should be overridable
+
 =back
 
 The implementation consists of the following parts which will be referenced later: