The Query Fragments window

The Query Fragments window can be used to control filtering query language elements modifying the current query, simply by clicking a button. This can be useful to save typing, or avoid memorizing, simple clauses of common usage (e.g. selecting only standalone documents or attachments, or filtering out WEB results, selecting a file system subtree, a file type, etc.).

Selecting the ToolsQuery Fragments menu entry will open the dialog.

The contents of the window are entirely customizable, and defined by the contents of a XML text file, named fragment-buttons.xml and which will be looked for in the current index configuration directory. The sample file distributed with Recoll contains a number of example filters. This will be automatically copied to the configuration directory if the file does not exist in there (e.g. ~/.recoll/fragment-buttons.xml under Linux and MacOS, $HOME/AppData/Local/Recoll/fragment-buttons.xml for Windows). Editing the copy will allow you to configure the tool for your needs .

Note

The fragment-buttons.xml file was named fragbuts.xml up to Recoll version 1.31.0. This was deemed too close to offensive for native English speakers, so that the file was renamed. An existing fragbuts.xml will still be used if fragment-buttons.xml does not exist. No automatic renaming will be performed.

Here follows an example window:

And the corresponding configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<fragbuttons version="1.0">

  <radiobuttons>
    <!-- Toggle WEB queue results inclusion -->
    <fragbutton>
      <label>Include Web Results</label>
      <frag></frag>
    </fragbutton>
    <fragbutton>
      <label>Exclude Web Results</label>
      <frag>-rclbes:BGL</frag>
    </fragbutton>
    <fragbutton>
      <label>Only Web Results</label>
      <frag>rclbes:BGL</frag>
    </fragbutton>
  </radiobuttons>

  <radiobuttons>
    <!-- Standalone vs embedded switch -->
    <fragbutton>
      <label>Include embedded documents</label>
      <frag></frag>
    </fragbutton>
    <fragbutton>
      <label>Only standalone documents</label>
      <frag>issub:0</frag>
    </fragbutton>
    <fragbutton>
      <label>Only embedded documents</label>
      <frag>issub:1</frag>
    </fragbutton>
  </radiobuttons>

  <buttons>
    <fragbutton>
      <label>Example: Year 2010</label>
      <frag>date:2010-01-01/2010-12-31</frag>
    </fragbutton>
    <fragbutton>
      <label>Example: c++ files</label>
      <frag>ext:cpp OR ext:cxx</frag>
    </fragbutton>
    <fragbutton>
      <label>Example: My Great Directory</label>
      <frag>dir:/my/great/directory</frag>
    </fragbutton>
  </buttons>
</fragbuttons>
        

There are two types of groupings radiobuttons and buttons, each defining a line of checkbuttons or radiobuttons inside the window. Any number of buttons can be selected, but the radiobuttons in a line are exclusive.

Buttons are defined by a fragbutton section, which provides the label for a button, and the Query Language fragment which will be added (as an AND filter) before performing the query if the button is active.

    <fragbutton>
      <label>Example: My Great Directory</label>
      <frag>dir:/my/great/directory</frag>
    </fragbutton>
  

It is also possible to add message elements inside the groups, for documenting the behaviour. message elements have a label but no frag element. Example:

  <buttons>
    <message>
      <label>This is a message</label> 
    </message>
  </buttons>
  

The label contents are interpreted as HTML. Take care to replace opening < characters with the &lt; entity if you use tags.

The only thing that you need to know about XML for editing this file is that any opening tag like <label> needs to be matched by a closing tag after the value: </label>.

You will normally edit the file with a regular text editor, like, e.g. vi or notepad. Double-clicking the file in a file manager may not work, because this usually opens it in a WEB browser, which will not let you modify the contents.