doc/plugins/contrib/ikiwiki/directive/jssearchfield.mdwn

   1 The `jssearchfield` directive is supplied by the [[!iki plugins/contrib/jssearchfield desc=jssearchfield]] plugin.
   2
   3 This enables one to search the structured data ("field" values) of
   4 multiple pages.  A search form is constructed, and the searching is
   5 done with Javascript, which means that the entire thing is self-contained.
   6 This depends on the [[!iki plugins/contrib/field]] plugin.
   7
   8 The pages to search are selected by a PageSpec given by the "pages"
   9 parameter.
  10 The fields to search are given by the "fields" parameter.  By default,
  11 the field name is given, and the user can type the search parameter for
  12 that field into a text input field.
  13
  14 ## OPTIONS
  15
  16 **pages**: A PageSpec to determine the pages to search through.
  17
  18 **fields**: The fields to put into the search form, and to display
  19 in the results.
  20
  21 **tagfields**: Display the given fields as a list of tags that can
  22 be selected from, rather than having a text input field.  Every distinct
  23 value of that field will be listed, so it is best used for things with
  24 short values, like "Author" rather than long ones like "Description".
  25 Note that "tagfields" must be a subset of "fields".
  26
  27 **sort**: A SortSpec to determine how the matching pages should be sorted; this is the "default" sort order that the results will be displayed in.
  28 The search form also gives the option of "random" sort, which will
  29 display the search results in random order.
  30
  31 ## SEARCHING
  32
  33 The search form that is created by this directive contains the following:
  34
  35 * for each search field, a label, plus either a text input field, or a list of checkboxes with values next to them if the field is also a tagfield.  Note that the lists of checkboxes are initially hidden; one must click on the triangle next to the label to display them.
  36 * a "sort" toggle. One can select either "default" or "random".
  37 * A "Search!" button, to trigger the search if needed (see below)
  38 * A "Reset" button, which will clear all the values.
  39
  40 The searching is dynamic.  As soon as a value is changed, either by tabbing out of the text field, or by selecting or de-selecting a checkbox, the search
  41 results are updated.  Furthermore, for tagfields, the tagfield lists
  42 themselves are updated to reflect the current search results.