1 CGI parameters to Omega
2 =======================
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.
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.
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.
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
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``.
38 query string to parse (may occur multiple times - if so, each will be
39 parsed and the results combined with ``OP_AND``).
42 like ``P``, but parsed with the default prefix set to *PREFIX*. For
43 example, ``P.A`` will search the author by default.
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
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).
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.
65 relevant document(s) (multiple values separated by ".")
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)
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.
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).
93 general boolean filter terms.
95 See the `overview document <overview.html>`_ for details of how
96 multiple `B` and `N` parameters are handled.
99 negated general boolean filter terms (new in Omega 1.3.5 - older
100 versions will just ignore any `N` parameters).
102 See the `overview document <overview.html>`_ for details of how
103 multiple `B` and `N` parameters are handled.
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.
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.
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):
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).
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*
133 If `SPAN.`\ *SLOT* is not specified:
135 * `START.`\ *SLOT* specifies the start of the range in the
136 format YYYY, YYYYMM, YYYYMMDD or YYYYMMDDHHMM. Default is the start
138 * `END.`\ *SLOT* specifies the end of the range in the
139 format YYYY, YYYYMM, YYYYMMDD or YYYYMMDDHHMM. Default is the end of
142 Added in Xapian 1.4.8 - older versions will just ignore these
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
153 Don't mix `START.`\ *SLOT*, `END.`\ *SLOT* and/or `SPAN.`\ *SLOT* with
154 `DATEVALUE` on the same slot number.
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
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.
171 like `START.`\ *SLOT*, `END.`\ *SLOT* and `SPAN.`\ *SLOT* but for value
172 slot `DATEVALUE`, or for term-based date range filtering if `DATEVALUE`
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.
187 apply a percentage cut-off at the value given by this parameter
188 (clipped to the range 0-100).
190 Reordering parameters
191 ---------------------
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.
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).
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 `-`).
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
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.
216 if non-zero, reverses the sort order specified by `SORT`. This
217 parameter has no effect unless `SORT` is also specified.
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.
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.
234 Display parameters and navigation
235 ---------------------------------
238 name of page format to use (may not contain ``..``).
241 hits per page (integer) - clipped to range 10-1000.
244 first document to display (snapped to multiple of HITSPERPAGE
245 if RAWSEARCH is not set)
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
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.
259 Modification of CGI parameters
260 ------------------------------
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
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.
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.
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:
281 * `PARAM.y` is silently dropped
282 * `PARAM.x` is truncated to `PARAM`
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 `>=>`)
295 Then general processing (as below) is applied.
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`.