This page is also available in

Documentation

Below documentation is part of the BeeBase dictribution and is also available in PDF.

[ << ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10. Filter

Filters can be used to hide records. This chapter describes what types of filters are available and how to use them.

BeeBase knows two types of filters, record filters and reference filters.

10.1 Record filter		Using a Boolean expression as filter.
10.2 Reference filter		Using a record reference as filter.

10.1 Record Filter

A record filter can be installed into a table to filter out records that are not of interest to you. Records that are filtered out are excluded in the table mask and thus the user can't see or browse to them.

10.1.1 Filter expression		How a filter looks like.
10.1.2 Changing filters		How to specify filter expressions.
10.1.3 Filter examples		Some examples.

10.1.1 Filter Expression

A filter is defined by specifying a Boolean expression that may contain calls to BeeBase programming functions. For each record of the table the filter is specified for, this expression is evaluated. If it returns NIL then the record is filtered out, otherwise it is included in the table mask.

Each table can have its own filter expression.

10.1.2 Changing Filters

To change the filter of the current table select menu item `Table - Change filter'. This will open a window containing

the name of the table you install the filter for in the window title.
a list of all fields of the table that can be used in the filter expression. This list is placed in the left part of the window. If you double click a name then the name will be inserted into the filter expression at the current cursor position.
a table of buttons displaying BeeBase programming functions and operators placed in the right part of the window. Click on one of the buttons to enter the corresponding function in the filter expression. Please note that the presented list of functions and operators is not complete. Other BeeBase functions not shown in one of the buttons must be entered manually. Only those BeeBase functions can be used that don't have side effects, e.g. it is not possible to write data to a file within a filter expression.
a string input field to enter the filter expression. The field and function/operator names are inserted here. You can also directly input your filter expression.
two buttons `Ok' and `Cancel' to leave the window.

After you are done with the specification of the filter expression click on the `Ok' button to leave the window. The entered expression is now compiled and on successful compilation, the expression is evaluated for all records. Those records for which the Boolean expression doesn't hold are then discarded in the table mask.

In case the expression doesn't compile you will get an error message displayed in the window title bar.

A filter can be turned on and off by clicking on the `F' button in the table's panel (if it is installed). After you have specified a filter expression for a table the filter for this table is turned on automatically.

If you (re-)activate a filter then all records of the table are checked whether they match the filter or not.

If a filter is currently active and you change a (filter relevant) field in a record of this table then the match-filter state of this record is not recomputed and stays unchanged.

If you allocate a new record in a table with an activated filter then there is no check if the new record matches the filter and the new record has its match-filter state set to TRUE.

10.1.3 Filter Examples

Here are some examples for valid filter expressions:

`NIL' filters out all records.
`TRUE' doesn't filter out any record.
`0' has the same effect as `TRUE' because for BeeBase all expressions not equal to NIL are considered as TRUE.
`(> Amount 100.0)' only displays records where the `Amount' field is greater than 100.0 (we assume here that the table has a field `Amount' of type real).
`(NOT (LIKE Name "*x*"))' filters out all records that have the letter `x' in the `Name' field (a string field).

Please note that BeeBase' programming language uses a lisp-like syntax. For more information about the programming language, see Programming BeeBase.

10.2 Reference Filter

Reference fields can also have a filter behavior. This is useful e.g. for building a hierarchy of tables. As an example see the project `Albums'.

If the filter of a reference field is turned on then the following features are activated:

The user can only access records in the field's table that have the reference set to the current record of the referenced table.
If the referenced table changes its current record then also a new current record is searched and set for the field's table.
When allocating a new record the reference is automatically set to the current record of the referenced table.

Note: Cascading delete has to be implemented manually (by using a delete trigger function).

Do not use the reference filter on cyclic graphs, e.g. self-referencing tables, as it doesn't make much sense.