The Facet API

A set of classes which allow for easy filter-based search interfaces. More...

Classes
class	Nepomuk::Utils::DateFacet
	A Facet that provides a set of date ranges. More...
class	Nepomuk::Utils::DynamicResourceFacet
	A facet that presents a dynamic lists of resources with the possibility to search for more. More...
class	Nepomuk::Utils::Facet
	The base class for all facets used to create query filters. More...
class	Nepomuk::Utils::FacetModel
	A FacetModel contains a list of facets that are provided in a tree structure. More...
class	Nepomuk::Utils::FacetWidget
	A widget providing a list of facets to add filters to a query. More...
class	Nepomuk::Utils::ProxyFacet
	A facet forwarding the filtered choices from another facet. More...
class	Nepomuk::Utils::SimpleFacet
	A simple facet using a list of terms. More...

---

Detailed Description

A set of classes which allow for easy filter-based search interfaces.

The Facet API which was introduced in KDE SC 4.6 provides a set of classes that allow the integration of a filter-based search interface into applications. It consists of the abstract Nepomuk::Utils::Facet class which has to be subclassed to implement a facet of a query and a convenient GUI element Nepomuk::Utils::FacetWidget which provides all the necessary user interaction.

If Nepomuk::Utils::FacetWidget does not suit the particular use case in an application Nepomuk::Utils::FacetModel is provided as a more advanced approach to handling facets. If even that is too constrained one can always handle the facets manually.

For convenience Nepomuk::Utils::SimpleFacet and Nepomuk::Utils::DynamicResourceFacet as well as a set of static factory methods in Nepomuk::Utils::Facet are provided to make facet creation as simple as possible.

Facet Examples

Nepomuk::Utils::ProxyFacet comes with a nice feature which allows to set a condition for the facet (Nepomuk::Utils::ProxyFacet::setFacetCondition()). The condition is a simple query term and means that the facet will not provide any choices unless the condition is met. This is best illustrated with a small example:

Imagine a facet that filters on image sizes:

Nepomuk::Utils::SimpleFacet* imageSizeFacet = new Nepomuk::Utils::SimpleFacet();
imageSizeFacet->addTerm( i18n("Small"), Vocabulary::NFO::width() <= Nepomuk::Query::LiteralTerm(300));
imageSizeFacet->addTerm( i18n("Medium"), (Vocabulary::NFO::width() > Nepomuk::Query::LiteralTerm(300)) &&
                                         (Vocabulary::NFO::width() <= Nepomuk::Query::LiteralTerm(800)));
imageSizeFacet->addTerm( i18n("Large"), Vocabulary::NFO::width() > Nepomuk::Query::LiteralTerm(800));

So far so good. However, this facet does only make sense for images. Thus, we want the choices to be hidden when the query shows other kinds of resources. What is the width of a project or an event? The solution is the facet condition:

Nepomuk::Utils::ProxyFacet* proxy = new Nepomuk::Utils::ProxyFacet();
proxy->setSourceFacet(imageSizeFacet);
proxy->setFacetCondition(Nepomuk::Query::ResourceTypeTerm(Vocabulary::NFO::Image()));

Now the proxy facet will only show any choices if the query contains the condition term, ie. if only images are queried. Be aware though that this feature does only work if the client uses Nepomuk::Utils::Facet::setClientQuery().

The same approach could be used to filter a Nepomuk::Utils::DynamicResourceFacet which filters on artists only when looking for audio files.

Note:

The Vocabulary namespace can be generated via the onto2vocabularyclass tool provided by Soprano. The best way to do that is through the provided cmake macro:

soprano_add_ontology(my_SRC ${SHAREDDESKTOPONTOLOGIES_ROOT_DIR}/nie/nfo.trig "NFO" "Nepomuk::Vocabulary" "trig")

Here both Soprano and SharedDesktopOntologies have been found through the cmake macros provided by the packages and kdelibs.