How-To write a Pluggable Index for Zope 2.4

Created by . Last modified on 2003/08/01.

Zope 2.4 introduces a new interface for plugin indexes. This allows developers to write their own indexes to be used with the ZCatalog. A plugin index will appear in the list of indexes inside the ZCatalogs index view.

I assume we like to write an index ExampleIndex. I make no assumptions about the functionality and the internal implementation of the index.

Files:

• Products/ExampleIndex/__init__.py -- needed for product initialization during Zope startup
• Products/ExampleIndex/ExampleIndex.py -- contains the implementation of the index

Index API

All plugin indexes must subclass from PluggableIndex:

     class ExampleIndex(PluggableIndex.PluggableIndex, Persistent, Implicit, SimpleItem):

        __implements__ = (PluggableIndex.PluggableIndexInterface,)

        meta_type="ExampleIndex"

        manage_options= (
            {'label': 'Settings',     
            'action': 'manage_main',
            'help': ('ExampleIndex','ExampleIndex_Settings.stx')},
        )

        query_options = ["query"]

All pluggable indexes must implement the following methods:

        def getEntryForObject(self, documentId, default=None):
            """Get all information contained for a specific object by documentId"""
            pass

        def index_object(self, documentId, obj, threshold=None):
            """Index an object:

               'documentId' is the integer ID of the document

               'obj' is the object to be indexed

               'threshold' is the number of words to process between committing
               subtransactions.  If None, subtransactions are disabled"""

pass

def unindex_object(self, documentId): """Remove the documentId from the index""" pass

def uniqueValues(self, name=None, withLengths=0): """Returns the unique values for name.

If withLengths is true, returns a sequence of tuples of (value, length)"""

pass

def _apply_index(self, request, cid=''): """Apply the index to query parameters given in the argument, request.

The argument should be a mapping object.

If the request does not contain the needed parametrs, then None is

returned.

Otherwise two objects are returned. The first object is a ResultSet containing the record numbers of the matching records. The second object is a tuple containing the names of all data fields used."""

All pluggable indexes must provide the following attributes:

• "query_options" -- a list of options that are allowed to be passed with a query (the option "query" is mandatory for all indexes)

When pluggable indexes are registered with the product registry, they must declare themselves to support the PluggableIndexInterface. The most straighforward way to do this is with a class attribute:

• __implements__ = Products.PluginIndexes.common.PluggableIndex.PluggableIndexInterface

DTML files

Every index must provide at least two DTML files:

• dtml/addExampleIndex.dtml -- this form is used when you create an new index through the management interface of the ZCatalog
• dtml/manageExampleIndex.dtml -- this is the management interface for our index and might keep additional elements to modify the behaviour of the index

Registration of the index

Typically the registration of an index inside __init__.py looks like this:

    def initialize(context):

        context.registerClass( 
            ExampleIndex.ExampleIndex,
            permission='Add Pluggable Index', 
            constructors=(manage_addExampleIndexForm,
                          manage_addExampleIndex),
            icon='www/index.gif',
            visibility=None

    manage_addExampleIndexForm = ExampleIndex.manage_addExampleIndexForm
    manage_addExampleIndex     = ExampleIndex.manage_addExampleIndex

References:

• lib/python/Products/PluginIndexes/PathIndex/PathIndex.py
• Interfaces documentations.