From 81e4602df0945c52dbc471c45b6fa5ae9d0aa3fa Mon Sep 17 00:00:00 2001
From: =?utf8?q?Sven=20Sch=C3=B6ling?= <s.schoeling@linet-services.de>
Date: Fri, 12 Jul 2013 15:13:04 +0200
Subject: [PATCH] part picker doku

---
 SL/Presenter/Part.pm | 82 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 2 deletions(-)

diff --git a/SL/Presenter/Part.pm b/SL/Presenter/Part.pm
index 3c1eecbb9..f32149d11 100644
--- a/SL/Presenter/Part.pm
+++ b/SL/Presenter/Part.pm
@@ -45,7 +45,7 @@ see L<SL::Presenter>
 All-in-one picker widget for parts. The name will be both id and name of the
 resulting hidden C<id> input field. An additional dummy input will be generated
 which is used to find parts. For a detailed description of it's behaviour, see
-section C<PART PICKER SPECIFICATION>.
+section L</PART PICKER SPECIFICATION>.
 
 C<VALUE> can be an id or C<Rose::DB:Object> instance.
 
@@ -61,13 +61,91 @@ presenter can not do this from the template.
 
 =back
 
+=head1 PART PICKER SPECIFICATION
+
+The following list of design goals were applied:
+
+=over 4
+
+=item *
+
+Parts should not be perceived by the user as distinct inputs of partnumber and
+description but as a single object
+
+=item *
+
+Easy to use without documentation for novice users
+
+=item *
+
+Fast to use with keyboard for experienced users
+
+=item *
+
+Possible to use without any keyboard interaction for mouse (or touchscreen)
+users
+
+=item *
+
+Must not leave the current page in event of ambiguity (cf. current select_item
+mechanism)
+
+=item *
+
+Should be useable with hand scanners or similar alternative keyboard devices
+
+=item *
+
+Should not require a feedback/check loop in the common case
+
+=item *
+
+Should not be constraint to exact matches
+
+=back
+
+The implementation consists of the following parts which will be referenced later:
+
+=over 4
+
+=item 1
+
+A hidden input (id input), used to hold the id of the selected part. The only
+input that gets submitted
+
+=item 2
+
+An input (dummy input) containing a description of the currently selected part,
+also used by the user to search for parts
+
+=item 3
+
+A jquery.autocomplete mechanism attached to the dummy field
+
+=item 4
+
+A popup layer for both feedback and input of additional data in case of
+ambiguity.
+
+=item 5
+
+An internal status of the part picker, indicating wether id input and dummy
+input are consistent. After leaving the dummy input the part picker must
+place itself in a consistent status.
+
+=item 6
+
+A clickable icon (popup trigger) attached to the dummy input, which triggers the popup layer.
+
+=back
+
 =head1 BUGS
 
 =over 4
 
 =item *
 
-Picker icons aren't displayed with css menu, because the spritemap is not loaded.
+Popup triggers are not displayed with css menu, because the spritemap is not loaded.
 
 =back
 
-- 
2.20.1