TPAC / unapi: Overhaul copy and located URI display

TPAC / unapi: Overhaul copy and located URI display

In unauthenticated mode, sort returned copies in the following order:

1. Search library proximity
2. Search library name
3. (Search results only) Call number, by most available copy status
4. Call number label
5. Copy status availability

Also return & display the copy counts ("x of y copies are available")
for the search library and each of its parents.

We can also determine "preferred library" as follows, taking the first
match:

1. A new GET param, "plib", specifying the number of the OU
2. If authenticated, the user's "search library" preference setting;
3. If authenticated, the user's home library;
4. Physical location in which the search is being issued (if any)

Given a preferred library:

1. Promote the copies (if any) for the preferred library to the top of
   the copy display list.
2. Include the copy count for the preferred library if it is outside of
   the scope of the search library;
3. In record details, give users the ability to jump to their preferred
   library scope via "Show preferred library" beside the preferred
   library copy count, if applicable. If your search library is located
   beneath your pref library in the org hierarchy, then you'll get just
   the "copy depth" link instead.

Also, untangle the located URIs from physical call numbers in
in-database unapi.

We had been facing the limitation of URIs being limited by the maximum
number of call numbers, with the result that URIs may or may not have
been displayed. Now, we take the bold tack of returning all URIs that
are in scope for both the search library and the preferred library. No
limiting is currently possible, but in the realistic worst case scenario
of both search lib and pref lib being set to an OU at depth 4, we'll get
a maximum of 8 different URIs back to display. (More realistically, it's
unlikely that a different URI will be set for each level of the
hierarchy.)

Some of the more granular code changes are as follows:

* Add attributes to in-db unapi acp, sunit, holdings_xml

This gives us more flexibility in displaying due dates within search
results or other contexts in which holdings are displayed. The
age_protect, copy_id, and vol_id attributes are required by the record
summary display.

* Enable TPAC to display records via HSTORE-based unapi

Now that unapi requires HSTORE-based LIMIT and OFFSET arguments, take
the simplest possible approach to get get_records_and_facets() working
again.

In search results, we want to limit both the number of copies we get
back (defaulting to a maximum of 5 copies per call number) and the
number of call numbers we get back (defaulting to a maximum of 5 call
numbers), so that we don't get 50 call numbers each with 5 copies back
and wind up grinding Evergreen's performance down to a halt.

Rough thought is that the caller can filter through the (maximum) 25
hits that are returned to present their preferred results. For example,
a site could opt to show 5 different call numbers with just one copy per
call number, or 5 different copies for a single call number, or all 25.

* Avoid deleted call numbers, copies, and sunits

The rewrite of unapi removed the filters for deleted call numbers that
were added to master in LP# 893315 / commit hash 47a16f516d. Fix this
to prevent returning pages of results that would show nothing in the
TPAC because all of the call numbers were deleted.

* Display multiple URIs correctly

We weren't clearing the hash each time that we added it to the list of
URIs, and that ended up duplicating the URI rather than adding distinct
URIs.

* Take copy availability into account for copy order

This is most important in the LIMITed list of copies returned to the
TPAC search results page, but also useful on the record details page.

This commit adds "copy status ranking" into the result ordering, such
that more available copies will be returned first in the list (and thus,
in the case of search results where call numbers and copies are
typically limited (currently to 5 of 5), ensuring that the most
available copies are likely to be seen by users).

The "availability" ranking for a copy is defined by a new function,
evergreen.rank_cp_status(), that takes criteria from the
config.copy_status table and ranks it in three tiers, as follows:

1. Most available =  opac_visible and copy_active are both TRUE
2. Almost available = holdable and opac_visible are TRUE, but
   copy_active is FALSE, or status ID = 1 ("Checked out")
3. Unavailable = anything else.

Thus, changing copy availability ranking (such as demoting "On holds
shelf" from the "most available" status to "almost available"), is
simply a matter of tweaking the evergreen.rank_cp_status() function.

* unapi database functions: mark STABLE

Thomas Berezansky suggested marking one of the new database functions in
the in-database unapi suite as STABLE to help the optimizer, which lead
to us realizing that everything can be marked as stable. This should
enable the planner to generate better plans than if left to the default
pessimistic level of VOLATILE.

Signed-off-by: Dan Scott <dan@coffeecode.net>
Signed-off-by: Jason Stephenson <jstephenson@mvlc.org>
Signed-off-by: Mike Rylander <mrylander@gmail.com>