The facets system
-----------------

Facets allow to restrict searches according to some criteria. CubicWeb
has a builtin `facet`_ system to define restrictions `filters`_ really
as easily as possible. A few base classes for facets are provided in
``cubicweb.web.facet.py``. All classes inherits from the base class
``AbstractFacet``.

Here is an overview of the facets rendering pick from the `tracker` cube:

.. image:: ../images/facet_overview.png

Facets will appear on each page presenting more than one entity.



VocabularyFacet
~~~~~~~~~~~~~~~~
The ``VocabularyFacet`` inherits from the ``AbstractFacet``.
A class which inherits from VocabularyFacets must redefine these methods:

.. automethod:: cubicweb.web.facet.VocabularyFacet.vocabulary
.. automethod:: cubicweb.web.facet.VocabularyFacet.possible_values

RelationFacet
~~~~~~~~~~~~~~

The ``RelationFacet`` inherits from the ``VocabularyFacet``. It allows to filter entities according to certain relation's values. Generally, you just have to define some class attributes like:

- rtype: the name of the relation
- role: the default value is set to `subject`
- target_attr: needed if it is not the default attribute of the entity


To illustrate this facet, let's take for example an *excerpt* of the schema of an office location search application:

.. sourcecode:: python

  class Office(WorkflowableEntityType):
      price = Int(description='euros / m2 / HC / HT')
      surface = Int(description='m2')
      description = RichString(fulltextindexed=True)
      has_address = SubjectRelation('PostalAddress',
                                    cardinality='1?',
                                    composite='subject')
      proposed_by = SubjectRelation('Agency')
      comments = ObjectRelation('Comment',
                                cardinality='1*',
                                composite='object')
      screenshots = SubjectRelation(('File', 'Image'),
                                    cardinality='*1',
                                    composite='subject')


We define a facet to filter offices according to the attribute
`postalcode` of their associated `PostalAdress`.

.. sourcecode:: python

  class PostalCodeFacet(RelationFacet):
      __regid__ = 'postalcode-facet'      # every registered class must have an id
      __select__ = implements('Office')   # this facet should only be selected when
                                          # visualizing offices
      rtype = 'has_address'               # this facet is a filter on the entity linked to
                                          # the office thrhough the relation
                                          # has_address
      target_attr = 'postalcode'          # the filter's key is the attribute "postal_code"
                                          # of the target PostalAddress entity


AttributeFacet
~~~~~~~~~~~~~~

The ``AttributeFacet`` inherits from the ``RelationFacet``. It allows to filter entities according to certain attribute's values.

The example below resumes the former schema. We define now a filter based on the `surface` attribute of the
`Office`.

.. sourcecode:: python

  class SurfaceFacet(AttributeFacet):
      __regid__ = 'surface-facet'       # every registered class must have an id
      __select__ = implements('Office') # this facet should only be selected when
                                        # visualizing offices
      rtype = 'surface'                 # the filter's key is the attribute "surface"
      comparator = '>='                 # override the default value of operator since
                                        # we want to filter according to a
                                        # minimal
                                        # value, not an exact one

      def rset_vocabulary(self, ___):
          """override the default vocabulary method since we want to hard-code
          our threshold values.
          Not overriding would generate a filter box with all existing surfaces
          defined in the database.
          """
          return [('> 200', '200'), ('> 250', '250'),
                  ('> 275', '275'), ('> 300', '300')]

RangeFacet
~~~~~~~~~~
The ``RangeFacet`` inherits from the ``AttributeFacet``. It allows to filter entities according to certain attributes of numerical type.

The ``RangeFacet`` displays a slider using `jquery`_ to choose a lower bound and an upper bound.

The example below defines a facet to filter a selection of books according to their number of pages.

.. sourcecode:: python

   class BookPagesFacet(RangeFacet):
       __regid__ = 'priority-facet'
       __select__ = RangeFacet.__select__ & implements('Book')
       rtype = 'pages'

The image below display the rendering of the ``RangeFacet``:

.. image:: ../images/facet_range.png

DateRangeFacet
~~~~~~~~~~~~~~
The ``DateRangeFacet`` inherits from the ``RangeFacet``. It allows to filter entities according to certain attributes of date type.

Here is an example of code that defines a facet to filter
musical works according to their composition date:

.. sourcecode:: python

    class CompositionDateFacet(DateRangeFacet):
        # 1. make sure this facet is displayed only on Track selection
        __select__ = DateRangeFacet.__select__ & implements('Track')
        # 2. give the facet an id required by CubicWeb)
        __regid__ = 'compdate-facet'
        # 3. specify the attribute name that actually stores the date in the DB
        rtype = 'composition_date'

With this facet, on each page displaying tracks, you'll be able to filter them
according to their composition date with a jquery slider.

The image below display the rendering of the ``DateRangeFacet``:

.. image:: ../images/facet_date_range.png


HasRelationFacet
~~~~~~~~~~~~~~~~

The ``DateRangeFacet`` inherits from the ``AbstractFacet``. It will
display a simple checkbox and lets you refine your selection in order
to get only entities that actually use this relation.

Here is an example of the rendering of the ``HasRelationFacet`` to
filter entities with image and the corresponding code:

.. image:: ../images/facet_has_image.png

.. sourcecode:: python

  class HasImageFacet(HasRelationFacet):
      __regid__ = 'hasimage-facet'
      __select__ = HasRelationFacet.__select__ & implements('Book')
      rtype = 'has_image'



To use ``HasRelationFacet`` on a reverse relation add ``role = 'object'`` in
it's definitions.

.. _facet: http://en.wikipedia.org/wiki/Faceted_browser
.. _filters: http://www.cubicweb.org/blogentry/154152
.. _jquery: http://www.jqueryui.com/