Installation and configuration of Collective Faceted Navigation

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.

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