==============================
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 decompress 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 of the dedicated catalog
======================================

For performance reasons, Faceted Navigation uses a dedicated catalog
that we can find at the root of the Plone site under the
``portal_facets_catalog`` name.


Registration of this catalog
----------------------------

First, we need to register Faceted Navigation catalog for the content
types that are involved by the product. To do that, we will visit
``archetypes_tool`` (via the ZMI) and select **both**
``portal_facets_catalog`` and ``portal_catalog`` (unless we do not
need the latter to catalog our items, which is quite an uncommon
configuration) for each content type that we want to display in the
faceted navigation.


Creating indexes and metadata
-----------------------------

Once the catalog is registered, we need to add our indexes and columns
(metadata). We must have an index and a column of the same name for
each facet. For example, if a facet is the subject of our items, we
will add a ``Subject`` index and a ``Subject`` column.

Indexed value(s) could virtually be of any type, though there are some
restrictions, considering the widget that is used to display each
facet.

For further details about facet configuration, see `List of facets
(left and right columns)`_ below.


Reindexing the dedicated catalog
--------------------------------

If we had items in our portal before installing Faceted Navigation, we
must reindex them so that they are taken in account in the dedicated
catalog. To do that, we could use the following code::

    for brain in portal.portal_catalog():
        brain.getObject().reindex_object()

Of course, we might reindex only the items that we want to display in
the faceted navigation.


Configuration of the Faceted Navigation
=======================================

We first 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 content 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 list of facets (using duplicate identifiers might lead to
    the end of the world, and this is not supported). See
    `Configuration of the dedicated catalog`_ above for further
    details.

``<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). See `Configuration of the
    dedicated catalog`_ above for further details.

``<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``.


Sorting 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. It has to be noted that this is probably slower than
a regular catalog sort (in other words: use with care).


Cache policy
------------

Different cache policies are provided. It is important to understand
how they work to select the right one for our site:

``extreme``
    With this cache policy, the first search result will be cached and
    then served for **every** user. This might not be a problem if all
    users have access to the same items or if, at least, the set of
    items that are shown by the faceted navigation does not depend on
    users roles. Naturally, the default criteria configuration can
    help in this: we could restrict the faceted navigation to
    published items. In any other case, this policy should not be
    used.

``roles``
    This is a variation on the above policy, where search results are
    cached depending on the roles of the users. It is important to
    note that only global roles are taken in account; local roles are
    **not** taken in account. If local roles are used in our site and
    some items shown by the faceted navigation are affected by them,
    this policy should not be used.

``user``
    *This is the default cache policy.*

    With this policy, there is one cache per user. There is also a
    global cache for all anonymous users.


``none``
    When set to this value, the cache is disabled. This might be of
    some use when testing.


Note that for special use-cases, developers might want to look at the
code to provide their own cache key selection method.



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.