==============================
Installation and configuration
==============================

Installation
============

The current trend would be to use ``easy_install``, like this::

    $ easy_install collective.facetednavigation

We can also download the product as a tarball (from `its home page`_
on `plone.org`_) and uncompress it in the ``lib/python/`` folder of
our Zope instance.

.. _its home page: http://plone.org/products/faceted-navigation

.. _plone.org: http://plone.org

Whatever the installation method we choose, we will have to "activate"
the product by dropping a file in the ``etc/package-includes/``
directory of our Zope instance. This file must be named
``collective.facetednavigation-configure.zcml`` and contain the
following code::

    <include package="collective.facetednavigation"/>

It is required that we restart the Zope instance after these steps.


Configuration
=============

Once the Zope instance is restarted, we need to go to the Plone *Site
setup* menu and install the *Faceted Navigation* product as usual (via
the *Add-on products* link).

Then we click on the new *Configuration of the faceted navigation*
link in the left column. This will bring us to a formidable and
definitely old-school properties form. Fear not, though, for the
properties are explained below.


Meta types to include
---------------------

We may want to restrict available items in the faceted navigation by
their type. To do that, we only need to list meta types in this field
(one per line).


List of facets (left and right columns)
---------------------------------------

The faceted navigation shows facets (criteria) on two columns. In each
field, we will have to list the facets (one per line) that should
appear in the corresponding column. Each line should have the
following syntax (options are separated by a semicolon)::

    <id>[;<label>[;<UID attribute>[;<widget>]]]

``<id>``
    The name of the catalog index that the facet corresponds to. A
    catalog column (brain metadata) of the same name must exist. A
    facet identifier should be unique amongst all facets defined in
    the two columns (using duplicate identifiers might lead to
    unexpected behaviour, and is not unsupported).

``<label>``
    *This attribute is optional.*

    Each facet will be displayed as a box (if we use the default
    CSS). Each box will show this label as its title.

    Default value: same as ``<id>``.


``<UID attribute>``
    *This attribute is optional.*

    In most cases, the value of the index corresponding to the facet
    will be displayed as is. However, if this value is an UID, then we
    will try to fetch an object by this UID. If found, we will try to
    get the defined attribute. It often is ``Title``, though it can be
    any catalog column (brain metadata).

``<widget>``
    *This attribute is optional and currently ignored.*

    For now, only one widget has been implemented: a list of
    checkboxes. In the future, other widgets might be implemented (for
    instance, a calendar to select dates).

    Default value: ``checkboxes``.


Sort matching items
-------------------

By default, items that match selected criteria are not sorted. With
this property, we can define the index that will be used to sort these
items, and also the order: using ``reverse`` will cause the items to
be sorted backwards.

Note that some types of index cannot be used by the catalog to sort
items. Amongst them is ``ZCTextIndex``, which is notably used by the
``Title`` index. However, we can nevertheless use indexes of these
types if there is a catalog column (brain metadata) of the same name:
the product will work around the limitation of the index and manually
sort the results.


Batch configuration
-------------------

Matching items are displayed by batch, as items in folder listings,
for instance. With these properties, we can define:

- how much items we want to display on each page;

- how much page we want to show in the batch navigation. For example,
  if we configured the number of pages to 5 and we are on page 7 of
  10, the batch will show this::

      5 6 [7] 8 9

  If we had configured the number of pages to 10, it would have shown
  this::

      1 2 3 4 5 6 [7] 8 9 10


Customization
=============

The product uses template macros to display the facet widgets and the
list of matching items. Both can be customized, as usual. See the
definition of ``faceted-navigation-macros`` in
``browser/configure.zcml`` for further details.


Enabling the user interface for anonymous users
===============================================

By default, KSS Javascript resources are not loaded for anonymous
users. That means that, by default, the faceted user interface will
not work for anonymous users. To enable it, we need to change the
condition of ``++resource++kukit.js`` in ``portal_javascripts`` to
this::

    python: here.restrictedTraverse('@@kss_devel_mode').isoff()

Or even completely remove the condition and probably reorder the
resources so that they can be better merged, depending on the use
case.
