The Facet API

Classes
class	Nepomuk::Utils::DateFacet
class	Nepomuk::Utils::DynamicResourceFacet
class	Nepomuk::Utils::Facet
class	Nepomuk::Utils::FacetModel
class	Nepomuk::Utils::FacetWidget
class	Nepomuk::Utils::ProxyFacet
class	Nepomuk::Utils::SimpleFacet

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.