[OPEN-ILS-DEV] prototype staff client, feedback/3

[steven]

This is some refined thinking on the use of directives in the checkin
controller. See below.

On Mon, 27 Jan 2014, steven wrote:

> 5. The focussing and blurring of the input text box is a throttling
> mechanism to prevent the user from scanning another barcode too
> quickly before the current one is finished processing...
>
> 6. Is it necessary to throttle user input?  Since barcode processing
> proceeds asynchronously...there shouldn't be a problem for the user
> to lose track of things.

In light of LP#1258318, 'One item filled two holds due to overlapping
checkin events', which I had forgotten about, it appears we do need to
throttle the barcode scan, but not as drastically as was described in 5.

The ticket (which I debugged on our end) documents a case in which an
RFID checkin station was used to scan barcodes. One was scanned twice,
inducing two checkin requests on the same barcode to occur. This
triggered two independent holds targetting processes. It so happened
that there was one holding and two patrons had active holds on it. It
also happened that the 2nd holds targetting finished ahead of the first,
giving the copy to the 2nd person.

The checkin screen can mitigate this sort of problem and still allow for
fast checkins to occur, by disallowing a barcode entry if a service
request corresponding to the same barcode value isn't finished,
otherwise allowing entry.

We would package this logic into an angularjs directive. Let's name it
'eg-safely'. We would apply it as an attribute as follows.

<input eg-safely />

If we were to write the logic using jQuery and coffeescript
notation, it would roughly be as follows.

# On change of any safely input elements of a specific form element, if the
# value corresponds to a pending promise, then show a tooltip or a
# popover and keep focus on input text box
#
$('input[eg-safely]', '#form').on 'change', scope, (event) ->
 	barcode = $(event.target).val()
 	promise = scope.history[barcode]
 	if promise?.state is 'pending'
 		# show tooltip and keep focus

The jQuery code can be translated into an angularjs directive as
follows, again using coffeescript notation because it is succinct.

aModule.directive 'egSafely', ->
     restrict: 'A'
     link: (scope, element) ->
         element.on 'change', (event) ->
             barcode = $(event.target).val()
             promise = scope.history[barcode]
             if promise?.state is 'pending'
                 # show tooltip and keep focus

Notice how direct the translation is. In the jQuery formulation, as long
as we presume a scope object is passed in as the 2nd parameter of the
the on method, there would be little change in moving the definition of
the 'change' handler to angularjs code.  The main difference is how the
event handler is bound to the DOM element. In jQuery, the binding takes
place in the js file, where DOM elements are referenced; in angularjs,
the binding takes place in the html file, where directive names are
referenced.

The key to making eg-safely work is to keep track of promises using an
associative array keyed on the barcode in a well-known place, here in a
scope.history object. We would probably want to delete entries in
history as they complete, in order to reduce the memory footprint.

In conclusion, we can list a number of general observations.

1. We shouldn't assume data entry of certain input fields are going to
be well debounced, for example, due to the nature of RFID scanners,
there will be duplicate entries.

2. We shouldn't assume service requests like checkin, checkout, and so
on, are idempotent, so that an operation done twice in a row will have
different side effects.

3. We can mitigate 1 and 2 by using eg-safely on certain input fields,
and yet allow the workflow to proceed as quickly as possible.

4. We should try to move all DOM manipulations, like what had to be done
for eg-safely, out of controllers and into directives.  If these
directives are properly written, they can be mostly reused.

-- 
steven <steven.chan at bc.libraries.coop>
bc libraries co-op/sitka