xapian-applications/omega/docs/cgiparams.rst

   1 CGI parameters to Omega
   2 =======================
   3
   4 In addition to the parameters listed here, all other parameters are
   5 retained. Arbitrary CGI parameters may be read with the $cgi{PARAM}
   6 and $cgilist{PARAM} OmegaScript commands.
   7
   8 Note that all CGI parameters are modified by Omega before they become
   9 part of $cgilist{} - see the section at the end for details.
  10
  11 Main query parameters
  12 ---------------------
  13
  14 DB
  15         database name.  If the DB parameter is specified more than once, each
  16         value is used to allow searching over multiple databases.  Also, the
  17         value of each DB parameter may be a list of database names separated by
  18         "/".  If no DB parameters are specified, then the database name
  19         defaults to ``default``.  If you want to search over a combination
  20         of databases by default then you can make the ``default`` database a
  21         stub database file - see the "Overview" document in xapian-core for
  22         details of the format.
  23
  24 xDB
  25         database(s) used for last query (separated by / if appropriate).
  26         If the database(s) used change then relevance judgements are
  27         discarded and the first page of matches is shown.  If xDB is not set,
  28         the database is assumed not to have changed, which means if you only
  29         deal with one database you don't have to pass a useless extra parameter
  30         around.
  31
  32 DEFAULTOP
  33         default operator - values recognised ``AND``, ``and``, ``OR``, ``or``.
  34         As of version 1.3.0, the default is ``AND`` (previously it was ``OR``).
  35         If you want to implement "match any words", set ``DEFAULTOP=or``.
  36
  37 P
  38         query string to parse (may occur multiple times - if so, each will be
  39         parsed and the results combined with ``OP_AND``).
  40
  41 P.\ *PREFIX*
  42         like ``P``, but parsed with the default prefix set to *PREFIX*.  For
  43         example, ``P.A`` will search the author by default.
  44
  45 xP
  46         terms from the previous parsed query - used to decide if
  47         this is a fresh query (in which case relevance judgements are
  48         discarded and the first page of matches is shown), an extended query
  49         (in which case the first page of matches is shown), or an unchanged
  50         query.
  51
  52 ADD
  53         if present, any ``X`` parameters are appended to the value of the first
  54         non-empty ``P`` parameter, or used to build a query if there are no
  55         non-empty ``P`` parameters (used for topterms support when JavaScript
  56         isn't supported or is disabled).
  57
  58 X
  59         topterms to add to query (each term in a separate ``X`` parameter).  If
  60         ``ADD`` is set, these will be appended to the value of the first
  61         non-empty ``P`` parameter, or used to build a query if there are no
  62         non-empty ``P`` parameters.
  63
  64 R
  65         relevant document(s) (multiple values separated by ".")
  66
  67 MORELIKE
  68         value is a document id to return similar pages to, or a term name
  69         (which will be looked up and the document id of the first document it
  70         indexes will be used - this allows a MORELIKE query based on the
  71         unique id from an external database)
  72
  73 RAWSEARCH
  74         when set to non-zero value, this prevents TOPDOC being snapped to a
  75         multiple of HITSPERPAGE.  Normally we snap TOPDOC like this so that
  76         things work nicely if HITSPERPAGE is in a picker or on radio buttons.
  77         If we're postprocessing the output of omega and want variable sized
  78         pages, this is unhelpful.
  79
  80 MINHITS
  81         can be set to look for more matches than would otherwise be looked for
  82         to you can be sure how many more consecutive pages will definitely be
  83         needed to show results.  By default omega asks for one hit more than
  84         the last one displayed on this page (so we know for sure if there is a
  85         next page or not).  If MINHITS is set, we ask for at least MINHITS
  86         matches from the start of the current page - you can think of MINHITS
  87         as defaulting to (HITSPERPAGE + 1).
  88
  89 Filtering parameters
  90 --------------------
  91
  92 B
  93         general boolean filter terms.
  94
  95         See the `overview document <overview.html>`_ for details of how
  96         multiple `B` and `N` parameters are handled.
  97
  98 N
  99         negated general boolean filter terms (new in Omega 1.3.5 - older
 100         versions will just ignore any `N` parameters).
 101
 102         See the `overview document <overview.html>`_ for details of how
 103         multiple `B` and `N` parameters are handled.
 104
 105 COLLAPSE
 106         value slot number to use for removing duplicate documents.
 107         Additional documents in the MSet with the same value will be
 108         removed from the MSet. $value{$cgi{COLLAPSE}} can be used to
 109         access the actual value for each hit.
 110
 111
 112 START.\ *SLOT* END.\ *SLOT* SPAN.\ *SLOT*
 113         One or more of these parameters can be specified for each *SLOT* to
 114         perform value-based date range filtering.  A document must fall into
 115         all of the specified ranges to match.
 116
 117         The values stored in the database in the specified *SLOT* need to be
 118         be in one of these formats with the format detected by looking at
 119         the length of the value bounds (each slot must use a single format,
 120         but different slots can use different formats):
 121
 122         * YYYYMMDDHHMM (e.g. 200702142359)
 123         * YYYYMMDD (e.g. 20070214)
 124         * a raw 4 byte big-endian value representing a time_t (omindex adds
 125           the last modified time in value slot 0 in this format).
 126
 127         `SPAN.`\ *SLOT* specifies the number of days either up to
 128         `END.`\ *SLOT* (if set), after `START.`\ *SLOT* (if set) or before
 129         today's date (if neither the start nor end are given) (if all three
 130         parameters are specified for the same *SLOT* then `START.`\ *SLOT*
 131         is ignored).
 132
 133         If `SPAN.`\ *SLOT* is not specified:
 134
 135         * `START.`\ *SLOT* specifies the start of the range in the
 136           format YYYY, YYYYMM, YYYYMMDD or YYYYMMDDHHMM.  Default is the start
 137           of time.
 138         * `END.`\ *SLOT* specifies the end of the range in the
 139           format YYYY, YYYYMM, YYYYMMDD or YYYYMMDDHHMM.  Default is the end of
 140           time.
 141
 142         Added in Xapian 1.4.8 - older versions will just ignore these
 143         parameters.
 144
 145 DATEVALUE
 146         This is an older way to specify a value-based date range filter, which
 147         only allows one date range filter to be applied to each query.
 148         `DATEVALUE` specifies the value slot number to use.  The format of
 149         the values stored in this slot in the database must be in one of the
 150         formats described above (YYYYMMDDHHMM, YYYYMMDD or a raw 4 byte
 151         big-endian time_t).
 152
 153         Don't mix `START.`\ *SLOT*, `END.`\ *SLOT* and/or `SPAN.`\ *SLOT* with
 154         `DATEVALUE` on the same slot number.
 155
 156         If `DATEVALUE` isn't set then `START`, `END` and `SPAN` will perform
 157         date filtering using an older approach based on D-, M-, and Y-prefixed
 158         terms.  This approach can only filter to a granularity of one day, so
 159         only the `YYYYMMDD` part of `START` and `END` are used.  Support for
 160         `YYYY` and `YYYYMM` in `START` and `END` for term-based date filtering
 161         was added in Xapian 1.4.8 - in earlier versions this failed with an
 162         error.
 163
 164         Also instead of `START`/`END` defaulting to the start and end of time,
 165         they instead default to 1st January 1970 and today's date respectively.
 166         The term-based date range filtering also includes a special `Dlatest`
 167         term, which allows flagging a document as always current.  There's no
 168         equivalent to this for value-based date range filters.
 169
 170 START END SPAN
 171         like `START.`\ *SLOT*, `END.`\ *SLOT* and `SPAN.`\ *SLOT* but for value
 172         slot `DATEVALUE`, or for term-based date range filtering if `DATEVALUE`
 173         isn't set.
 174
 175 xFILTERS
 176         used to spot when the filters have changed from the previous search.
 177         Set this to $html{$filters} in your query template ($filters is a
 178         compact serialisation of the currently set B filters, date-range
 179         filters, COLLAPSE, and DEFAULTOP).  If xFILTERS is unset, the filters
 180         are assumed not to have changed (unlike xP).  In Omega <= 1.2.21 and <=
 181         1.3.3 they were always assumed to have changed in the situation, which
 182         meant you couldn't ever go past page 1 if you failed to set xFILTERS
 183         in your template.  Now failing to set it means that the first page
 184         won't be forced in some cases where it probably should be.
 185
 186 THRESHOLD
 187         apply a percentage cut-off at the value given by this parameter
 188         (clipped to the range 0-100).
 189
 190 Reordering parameters
 191 ---------------------
 192
 193 SORT
 194         specifies one or more value slot numbers to order results by.  The
 195         comparison used is a string compare of the unsigned byte values.
 196
 197         The format of this parameter's value is a `+` or `-` specifying the
 198         direction of the sort followed by an unsigned integer value slot
 199         number.  Normally `+` means an ascending sort (so the first result has
 200         the lowest value of the sort key) and `-` means a descending sort -
 201         however `SORTREVERSE` can change this (see below).
 202
 203         The sort direction character was added in 1.3.5 - earlier versions
 204         defaulted to a descending sort (and for compatibility this is still
 205         the behaviour if you omit the `+` or `-`).
 206
 207         Earlier versions also parsed the value as a signed integer and then
 208         cast it to unsigned, so beware of using updated templates with older
 209         versions.
 210
 211         The ability to specify more than one value slot number was added
 212         in 1.4.1.  Multiple slot specifiers are separated by zero or more
 213         whitespace and/or commas - e.g. `SORT=+1-0+4`, `SORT=+1, -2`, etc.
 214
 215 SORTREVERSE
 216         if non-zero, reverses the sort order specified by `SORT`.  This
 217         parameter has no effect unless `SORT` is also specified.
 218
 219 SORTAFTER
 220         if non-zero, order results by relevance, only sorting by value to
 221         order values with the same relevance score.  This parameter has no
 222         effect unless SORT is also specified.
 223
 224 DOCIDORDER
 225         set the ordering used when a comparison ends up being by docid (i.e.
 226         two documents with equal relevance and/or values).  By default (if
 227         DOCIDORDER isn't set or is empty) this puts them in ASCENDING order
 228         (the lowest document id ranks highest).  If DOCIDORDER is specified
 229         and non-empty it can begin with "D" for DESCENDING order, "A" for
 230         ASCENDING order or any other character ("X" by convention) for
 231         DONT_CARE (the Xapian database backend will use whichever order is most
 232         efficient).  Any characters after the first are ignored.
 233
 234 Display parameters and navigation
 235 ---------------------------------
 236
 237 FMT
 238         name of page format to use (may not contain ``..``).
 239
 240 HITSPERPAGE
 241         hits per page (integer) - clipped to range 10-1000.
 242
 243 TOPDOC
 244         first document to display (snapped to multiple of HITSPERPAGE
 245         if RAWSEARCH is not set)
 246
 247 If a parameter named '<' or '>' exists, Omega will go to the previous
 248 or next results page (based on the value of TOPDOC), respectively. If
 249 not, and a parameter named '[' or '#' exists, it will jump to the page
 250 number given by that parameter (trailing junk after the number is
 251 ignored). (See the section below on modification of CGI parameters to
 252 see how this works.)
 253
 254 This means that <input type='image' .../> form buttons can have names
 255 of the form '[ 3 ]', which looks nice in lynx, for tooltips, and so
 256 on. For text-only links, you really need to write out the entire GET
 257 parameters and use a normal anchor.
 258
 259 Modification of CGI parameters
 260 ------------------------------
 261
 262 Omega does some special mangling of CGI parameter names which is intended
 263 to help with using image buttons, and also to enable providing nicer "alt" text
 264 in older browsers.
 265
 266 In the intervening decades HTML4 introduced the `alt` tag and CSS now provides
 267 cleaner ways to handle image buttons, so this mangling isn't as useful as it
 268 once was, but for now we've left it in place for compatibility.
 269
 270 Image Buttons
 271 ~~~~~~~~~~~~~
 272
 273 When the user clicks on an image button `<input type="image" name="PARAM">`,
 274 the browser passes two CGI parameters `PARAM.x` and `PARAM.y` whose values
 275 report the x and y coordinates within the image that were clicked.
 276
 277 Image buttons allow for prettier navigation within search results, but what
 278 the browser passes is unhelpful so Omega does some special mangling of
 279 parameters with a `.x` or `.y` suffix:
 280
 281  * `PARAM.y` is silently dropped
 282  * `PARAM.x` is truncated to `PARAM`
 283
 284 Then:
 285
 286  * if the parameter name contains a space or (since 1.4.4) a tab, the value
 287    becomes everything after the first space/tab and the original value is
 288    ignored. (e.g.: `[ 2 ].x=NNN` becomes `[=2 ]`).
 289  * if the parameter name doesn't contain a space or (since 1.4.4) a tab:
 290     * if the parameter name is entirely numeric, the name becomes `#` and the
 291       value becomes the parameter name. (e.g.: `2.x=NNN` becomes `#=2`)
 292     * otherwise, the value is replaced with the parameter name (e.g.:
 293       `>.x=NNN` becomes `>=>`)
 294
 295 Then general processing (as below) is applied.
 296
 297 General
 298 ~~~~~~~
 299
 300 For **ALL** CGI parameters, the name is truncated at the first space or (since
 301 1.4.4) a tab. So `[ page two ]=2` becomes `[=2`.