Filters
Filters in bedework are stored internally in two forms, either the same form as CalDAV filters or as a logical expression.
Expression style filtering
An example filter expression is
Return only events
type = "event"
Events with "t" in the summary
type = "event" & summary = "t"
Currently all comparisons are caseless and CalDAV and expression filters only support "contains" matching, i.e the supplied text string is somewhere in the named property.
Restrictions on expression filters are that the "type" term must be first if present and the following operator must be "&".
If not present type="event" is assumed.
Terms may be parenthesised:
type = "event" & (categories = "arts" | categories="lectures")
The left hand side is a property name (hence "categories" rather than "category") and the right hand side is currently a quoted text string.
A property test may be of the form
name = value
or for date values
name in value to value
for date type expressions, for example
dtstart in "20081101T000000Z" to "20081130T000000Z"
Later versions will support handling of timezones and better time/dates.
CalDAV based filtering
The xml based CalDAV filters use the same code as the CalDAV server to parse and execute.
During the interim period while we figure out an external representation and a ui we will provide the means for admins to create named filters and save them.
These can be referred to in the query for events. Once we have some more infrastructure in place we can move towards possibly providing dynamically created filters.
In the meantime these are some examples of filtering which can be used and modified to create filters for your event feeds.
Return only events
<?xml version="1.0" encoding="utf-8" ?>
<C:filter xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">
<C:comp-filter name="VCALENDAR">
<C:comp-filter name="VEVENT"/>
</C:comp-filter>
</C:filter>
Filter by date
<?xml version="1.0" encoding="utf-8" ?>
<C:filter xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">
<C:comp-filter name="VCALENDAR">
<C:comp-filter name="VEVENT">
<C:time-range start="20060104T000000Z"
end="20060105T000000Z"/>
</C:comp-filter>
</C:comp-filter>
</C:filter>
Retrieval of To-Dos by Alarm Time Range
<?xml version="1.0" encoding="utf-8" ?>
<C:filter xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">
<C:comp-filter name="VCALENDAR">
<C:comp-filter name="VTODO">
<C:comp-filter name="VALARM">
<C:time-range start="20060106T100000Z"
end="20060107T100000Z"/>
</C:comp-filter>
</C:comp-filter>
</C:comp-filter>
</C:filter>
Events with "t" in the summary
<?xml version="1.0" encoding="utf-8" ?>
<C:filter xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">
<C:comp-filter name="VCALENDAR">
<C:comp-filter name="VEVENT">
<C:prop-filter name="SUMMARY">
<C:text-match>t</C:text-match>
</C:prop-filter>
</C:comp-filter>
</C:comp-filter>
</C:filter>
Filter evaluation
Filters are attached to aliases, folders or collections adn are evaluated when that entity is used as part of a retrieval. For example, if an alias is created to /public/calendar and a filter is associated with that alias, for example, category=Dance, then every time that alias is used a search term will eb created which is effectively
calendar = '/public/calendar' and category='Dance'
The situation become srather more complex when aliases are applied to aliases or folders which themselves have filters applied. For example, assume an alias "Engineering" targeted at "/public/calendar". This alias has the effective filter
calendar = '/public/calendar' and creator='agrp_eng'
Now we create an alias "Engineering Lectures" to that alias and apply a filter "category=Lectures". The result is an anding of the terms applied to the final target, e.g.
calendar = '/public/calendar' and creator='agrp_eng' and category='Lectures'
The other situation is a folder containing more than one alias. Assume a folder "Arts" containing two filters "Films" and "Dance". The Films alias has the filter "category=Films" and the Dance alias has the filter "category=Dance". A reference to the Arts folder results in the expression
calendar = '/public/calendar' and (category='Films' or category='Dance')
Putting it together we create a folder "Engineering Lectures and Arts" and put both aliases into thet folder. This results in the final expression
calendar = '/public/calendar' and ((creator='agrp_eng' and category='Lectures') or (category='Films' or category='Dance'))
