ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / 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.