Writing Extentions for gramps
<<< Previous |  | Next >>>

# Writing Filters

Users can create their own filters and add them to `gramps`. By adding the filter to the user's private filter directory (`~/.gramps/filters`), the filter will be automatically recognized the next time that the program is started.

## Creating a filter

Each filter is a class derived from the `Filter.Filter` class. The `__init__` task may be overridden, but if so, should call the `__init__` function on the `Filter.Filter` class. The parent class provides the variable `self.text`, which contains the text string passed as the qualifier. This string provides additional information provided by the user. For example, if the filter is used to match names, the qualifier would be used to provide the name that is being compared against.

All filter classes must define a `match` function. The function takes one argument (other than `self`), which is an object of type `Person` to compare against. The function should return a 1 if the person matches the filter, or a zero if the person does not.

Each filter must be registered, so that `gramps` knows about it. This is accomplished by calling the `Filter.register_filter` function. This function takes three arguments - the filter class, a description, and flag that indicates if the qualifier string is needed. The description string appears in the pull down interface within `gramps`, and helps the user choose the appropriate filter. The qualifier flag tells `gramps` whether or not the filter needs a qualifier string. If this flag is 0, `gramps` will disable the entry of a qualifier string.

    import Filter
    import string

    # class definition

    class SubString(Filter.Filter):

        def match(self,person):
            name = person.getPrimaryName().getName()
            return string.find(name,self.text) >= 0

    Filter.register_filter(SubString,
                           description="Names that contain a substring",
    	               qualifier=1)

Figure 1. Sample filter implementation

<<< Previous | Home | Next >>>
Writing Extentions for gramps |  | Writing Reports