docs/TechRef/AutoSuggest/README

   1 AutoSuggest
   2
   3 Get an autocompleting dialog underneath basic search boxes.
   4
   5 If activated, the dialog appears in both the JavaScript OPAC and the Template
   6 Toolkit OPAC.
   7
   8 Mike Rylander and Bill Erickson largely designed and spec'ed out this
   9 feature, especially at the database level.  Lebbeous Fogle-Weekley and
  10 Mike Rylander did the programming.
  11
  12 How it works, for site administrators
  13 -------------------------------------
  14
  15 Once the code is installed, including database stored procedures,
  16 (re)ingesting your bibliographic records will populate two new tables
  17 needed by AutoSuggest: metabib.browse_entry and metabib.browse_entry_def_map.
  18
  19 Yes, for now this means that the size of your database in per-record terms
  20 will be greater.  The browse_entry data we generate is extremely similar to
  21 facet data, so it's possible that in the future we can blend them into the
  22 same thing at the database level, and save some space.
  23
  24 To control what gets indexed in the metabib.browse_* tables, set the
  25 boolean 'browse_field' column for each row in config.metabib_field as desired
  26 Numbers 15 (keyword|keyword) and 16 (subject|complete) should generally be set
  27 to false.
  28
  29 The config.metabib_class  table has a new 'buoyant'
  30 column.  Setting this to true means that when a user is typing in the OPAC
  31 search box with a search class selector set to, say, 'Subject', and the cmc row
  32 for 'Subject' has 'buoyant' set to true, the top suggestions will definitely
  33 come from the Subject fields of MARC records (if any).  'restrict' is like
  34 'buoyant', only stronger.  In that case suggestions /only/ come from the
  35 selected class.
  36
  37 This is the idea behind the 'restrict' column (in both the
  38 config.metabib_class table and the config.metabib_field table):
  39 For any given class or field, if restrict is true AND the user at the OPAC
  40 has selected that same class or field from the search class dropdown, then
  41 autosuggestions will only come from that class or field in the record.
  42
  43 You never want this column to be true for keyword, because we don't index
  44 keywords for browse/autosuggest purposes (we would get giant blobs of
  45 information as autosuggestions, and you don't want that (really)).
  46
  47 You don't really want it to be true for most classes and fields.
  48 If the user sets the dropdown to "subject" and start typing "harry potter",
  49 the user really wants matches from the "title" class too (although other
  50 things being equal, matches from the "subject" class will rise to the top).
  51
  52 If you have a speciality index, you *may* want to set restrict to true
  53 for that particular field.  For a song title index, for example.  To take
  54 advantage of this, you would also have to customize your OPAC to have an
  55 entry in the search class dropdown for 'title|songtitle' (or whatever's
  56 appropriate for your specialty index).  This is easy to do and should be
  57 covered somewhere in documentation for both the JSPAC and the TPAC.
  58
  59 The order of suggestions otherwise has mostly to do with how well what users
  60 have typed matches what's in your bib records, and the value of the weight
  61 column of the relevant config.metabib_field row.  Examine the code if you're
  62 curious to know more or want to make adjustments.
  63
  64 The master on/off switch for AutoSuggest is a new row in in config.global_flag
  65 named 'opac.use_autosuggest'.  Set its 'enabled' column to false to turn
  66 off AutoSuggest.  If you don't want your suggestions to be limited to whatever's
  67 OPAC visible at the search org, set the 'value' column to anything that
  68 does not contain the string 'opac_visible'.  This could be a good idea
  69 if AutoSuggest seems slow on a large site.
  70
  71 Turning this on means introducing Dojo in your TPAC.  I tried to
  72 keep it minimal, for load time's sake.  There's no fieldmapper or IDL stuff
  73 play.  For now, turning this feature off will avoid loading Dojo in your
  74 TPAC.
  75
  76 Managing the little stuff
  77 -------------------------
  78 CSS classes that affect the look of suggestions are in this file for the TPAC:
  79     Open-ILS/web/css/skin/default/opac/style.css
  80
  81 and in this file for the JSPAC:
  82     Open-ILS/web/opac/skin/default/css/layout.css
  83
  84 At bottom, autosuggest is shaped by PostgreSQL's Full Text Search features.
  85 Some of the arguments that are passed to TS_RANK_CD() and TS_HEADLINE() are
  86 exposed via options to the openils.widget.AutoSuggest and
  87 openils.AutoSuggestStore modules, which have comments.  You can customize your
  88 OPAC files to invoke these with your desired options without touching much
  89 actual code.