Base facet to filter some entities according to other entities to which
they are related. Create concrete facet by inheriting from this class an then
configuring it by setting class attribute described below.

The relation is defined by the rtype and role attributes.

The no_relation boolean flag tells if a special ‘no relation’ value should be
added (allowing to filter on entities which do not have the relation set).
Default is computed according the relation’s cardinality.

The values displayed for related entities will be:

result of calling their label_vid view if specified

else their target_attr attribute value if specified

else their eid (you usually want something nicer…)

When no label_vid is set, you will get translated value if i18nable is
set. By default, i18nable will be set according to the schema, but you can
force its value by setting it has a class attribute.

You can filter out target entity types by specifying target_type.

By default, vocabulary will be displayed sorted on target_attr value in an
ascending way. You can control sorting with:

sortfunc: set this to a stored procedure name if you want to sort on the
result of this function’s result instead of direct value

sortasc: boolean flag to control ascendant/descendant sorting

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

We can simply define a facet to filter offices according to the agency
proposing it:

classAgencyFacet(RelationFacet):__regid__='agency'# this facet should only be selected when visualizing offices__select__=RelationFacet.__select__&is_instance('Office')# this facet is a filter on the 'Agency' entities linked to the office# through the 'proposed_by' relation, where the office is the subject# of the relationrtype='has_address'# 'subject' is the default but setting it explicitly doesn't hurt...role='subject'# we want to display the agency's nametarget_attr='name'

Base facet to filter some entities according to an attribute of other
entities to which they are related. Most things work similarly as
RelationFacet, except that:

label_vid doesn’t make sense here

you should specify the attribute type using target_attr_type if it’s not a
String

you can specify a comparison operator using comparator

Back to our example… if you want to search office by postal code and that
you use a RelationFacet for that, you won’t get the expected
behaviour: if two offices have the same postal code, they’ve however two
different addresses. So you’ll see in the facet the same postal code twice,
though linked to a different address entity. There is a great chance your
users won’t understand that…

That’s where this class come in! It’s used to said that you want to filter
according to the attribute value of a relatied entity, not to the entity
itself. Now here is the source code for the facet:

classPostalCodeFacet(RelationAttributeFacet):__regid__='postalcode'# this facet should only be selected when visualizing offices__select__=RelationAttributeFacet.__select__&is_instance('Office')# this facet is a filter on the PostalAddress entities linked to the# office through the 'has_address' relation, where the office is the# subject of the relationrtype='has_address'role='subject'# we want to search according to address 'postal_code' attributetarget_attr='postalcode'

This class simply filter according to the presence of a relation
(whatever the entity at the other end). It display a simple checkbox that
lets you refine your selection in order to get only entities that actually
have this relation. You simply have to define which relation using the
rtype and role attributes.

Here is an example of the rendering of thos facet to filter book with image
and the corresponding code:

So, suppose that in our office search example you want to refine search according
to the office’s surface. Here is a code snippet achieving this:

classSurfaceFacet(AttributeFacet):__regid__='surface'__select__=AttributeFacet.__select__&is_instance('Office')# this facet is a filter on the office'surfacertype='surface'# override the default value of operator since we want to filter# according to a minimal value, not an exact onecomparator='>='defvocabulary(self):'''override the default vocabulary method since we want to hard-code our threshold values. Not overriding would generate a filter containing all existing surfaces defined in the database. '''return[('> 200','200'),('> 250','250'),('> 275','275'),('> 300','300')]

Base facet to filter some entities according to an arbitrary rql
path. Path should be specified as a list of 3-uples or triplet string, where
‘X’ represent the filtered variable. You should specify using
filter_variable the snippet variable that will be used to filter out
results. You may also specify a label_variable. If you want to filter on
an attribute value, you usually don’t want to specify the later since it’s
the same as the filter variable, though you may have to specify the attribute
type using restr_attr_type if there are some type ambiguity in the schema
for the attribute.

Using this facet, we can rewrite facets we defined previously:

classAgencyFacet(RQLPathFacet):__regid__='agency'# this facet should only be selected when visualizing offices__select__=is_instance('Office')# this facet is a filter on the 'Agency' entities linked to the office# through the 'proposed_by' relation, where the office is the subject# of the relationpath=['X has_address O','O name N']filter_variable='O'label_variable='N'classPostalCodeFacet(RQLPathFacet):__regid__='postalcode'# this facet should only be selected when visualizing offices__select__=is_instance('Office')# this facet is a filter on the PostalAddress entities linked to the# office through the 'has_address' relation, where the office is the# subject of the relationpath=['X has_address O','O postal_code PC']filter_variable='PC'

Though some features, such as ‘no value’ or automatic internationalization,
won’t work. This facet class is designed to be used for cases where
RelationFacet or RelationAttributeFacet can’t do the trick
(e.g when you want to filter on entities where are not directly linked to
the filtered entities).

The AbstractRangeRQLPathFacet is the base class for
RQLPathFacet-type facets allowing the use of RangeWidgets-like
widgets (such as (FacetRangeWidget,
class:DateFacetRangeWidget) on the parent RQLPathFacet
target attribute.

When some facet criteria has been updated, this method is called to
add restriction for this facet into the rql syntax tree. It should get
back its value in form parameters, and modify the syntax tree
(self.select) accordingly.

Facets will have the following attributes set (beside the standard
AppObject ones):

select, the rql.stmts.Select node of the rql syntax tree being
filtered

filtered_variable, the variable node in this rql syntax tree that we’re
interested in filtering

Facets implementors may also be interested in the following properties /
methods: