List views in Horilla aren’t just columns and rows most of them ship a filter panel backed by a django-filter FilterSet. And just like columns and tabs, there’s a clean way to add a filter field, exclude one, or change how a filter behaves from a completely separate app, without touching the FilterSet you’re extending. That mechanism is _inherit_filter, living under horilla/extension/filter/.

Unlike _inherit_tab from an earlier post in this series which turned out to have no production consumer yet _inherit_filter is genuinely in use. Horilla CRM‘s own custom_fields app relies on it to inject custom-field filtering into every model that opts in, which makes it a good mechanism to trust as a pattern to copy.

What Does the Extension Mechanism Do?

_inherit_filter lets a FilterExtension subclass in a separate app:

  • Add or exclude fields on an existing FilterSet’s Meta
  • Add search fields, inserted at a specific position or appended
  • Add brand-new declared filters (django_filters.CharFilter, etc.)
  • Override any method on the target FilterSet most usefully, _build_row_q, the method that turns one filter row into a Q object using ordinary super() calls

The base class every Horilla filterset ultimately extends is HorillaFilterSet:

class HorillaFilterSet(django_filters.FilterSet):
“””
Custom FilterSet for Horilla with enhanced search and filtering capabilities.
“””

search = django_filters.CharFilter(method="filter_search", label="Search")

HorillaListView.filterset_class points to a concrete subclass of this (e.g. LeadFilter), and that’s what an extension targets.

Defining a Filter Extension

The simple, documented case — adding a field to the exclude list:

# my_lead_extensions/filters.py

from horilla.extension.filter import FilterExtension




class LeadFilterExtension(FilterExtension):
    _inherit_filter = "horilla_crm.leads.filters.LeadFilter"
    exclude_append = ["industry_code"]

As with every other extension kind in this series, the moment this class body executes, FilterExtension.__init_subclass__ notices _inherit_filter is set and registers it automatically — no manual registry call.

Registering the Extension App

Same convention again: list the module in auto_import_modules so it’s imported on startup.

# my_lead_extensions/apps.py

auto_import_modules = [
    "models",
    "forms",
    "filters",   # required — registers FilterExtension at import
    "lists",
    "kanbans",
    "details",
]

# local_settings.py
INSTALLED_APPS += [“my_lead_extensions”]

One operational detail worth calling out, straight from Horilla’s own docs: restart the dev server after changing extension modules. Filter resolution isn’t tied to the same per-request wrapper that list and tab views use (more on that below), so a running process can hold a stale composed class in its cache until it restarts.

Understanding the Configuration

  • _inherit_filter — the dotted path to the target FilterSet, as a string, e.g. “horilla_crm.leads.filters.LeadFilter”. Field names used anywhere in the extension (exclude_append, etc.) must be the real ORM field name, not a display label industry_code, not industry.
  • _inherit_filter_priority — default 0; higher runs later in mixin order, letting a later extension’s attribute win over an earlier one if there’s a conflict.
  • Layout hooks — the declarative additive attributes: exclude_append, fields_append, search_fields_append, and search_fields_insert (which takes (after_field, new_field) pairs so you can place a new search field relative to an existing one, the same positional-insert idea as _inherit_list’s columns_insert).
  • override_filters — a set of declared-filter names this extension is explicitly allowed to redefine, for when two extensions both want to own the same filter name.
  • Method overrides — anything else callable on the class body becomes a mixin method, composed with correct super() chaining.

A Real Production Example: Custom Fields

Horilla’s own custom_fields app is the real-world case, and it’s more advanced than the quick-start: instead of registering one static extension against one hardcoded FilterSet, it registers one dynamically generated extension per model that’s opted into custom fields — discovered at runtime, not hardcoded in advance.

The shared logic lives in a template class that’s never itself registered:

class _FilterMethods(FilterExtension):
    """
    Template for the methods a custom-fields FilterExtension needs.
    Never itself registered — copied by reference into each concrete
    filterset's dynamically created subclass namespace.
    """


    def _build_row_q(self, model, field, operator, i, values, start_values, end_values):
        if is_custom_field_name(field):
            try:
                return custom_field_row_q(
                    model, field, operator, i, values, start_values, end_values
                )
            except Exception:
                logger.exception("custom_fields: could not build filter Q for %s", field)
                return None
        return super()._build_row_q(
            model, field, operator, i, values, start_values, end_values
        )

And a registration function builds a concrete FilterExtension subclass for each discovered target at runtime:

def _register_filter_extension(filterset_class):
    """Create and register a FilterExtension subclass for filterset_class."""
    filterset_path = _filterset_path(filterset_class)
    if _already_registered(filterset_path):
        return False


    namespace = {
        key: value
        for key, value in _FilterMethods.__dict__.items()
        if not key.startswith("__")
    }
    namespace["_inherit_filter"] = filterset_path
    namespace["__module__"] = __name__
    type(
        f"CustomFields{filterset_class.__name__}Extension",
        (FilterExtension,),
        namespace,
    )
    return True

This is a useful pattern to borrow whenever “extend every model that opts into feature X” is the actual goal, rather than “extend this one specific FilterSet.” Because new CRM apps can register a model for custom fields after custom_fields itself has already started up, this discovery is wired into a shared pre-compose hook rather than running once at import time:

def _install_discovery_hook():
from horilla.extension._pre_compose_hooks import register_pre_compose_hook
register_pre_compose_hook(“filter”, register_discovered_filter_extensions)

That hook runs right before Horilla composes filter extensions, giving every late-registering model a chance to get its own extension built just in time.

Note the super() call inside _build_row_q works correctly even though _FilterMethods is never actually a base class of the composed filterset Horilla’s composer rebinds each copied method’s __class__ closure cell to the mixin it actually ends up in, which is exactly the same _super_rebind machinery used by _inherit_list, _inherit_tab, and _inherit_detail. The custom_fields code even says so directly in its own docstring, anticipating the question.

How Resolution Works — and Why It’s Different From List/Tab

This is the one structurally different piece worth flagging. List and tab extensions resolve per HTTP request, inside an as_view() wrapper. Filters don’t FilterSet classes aren’t views, so there’s no as_view() to hook. Instead, resolution happens wherever a view asks for its filterset class:

def get_filterset_class(self):
    """
    Return composed filterset when _inherit_filter extensions exist.
    Views keep filterset_class = UserFilter at class definition time;
    resolution runs here (same pattern as get_form_class() on form views).
    """
    base = type(self).filterset_class
    if base is None:
        return None
    from horilla.extension.filter.resolve import resolve_filterset_class
    return resolve_filterset_class(base)

HorillaListView.get_filterset_class() is what every internal call site uses instead of reaching for self.filterset_class directly so as long as your view goes through the generic machinery (which it does by default), the composed class is picked up automatically. resolve_filterset_class() itself is a plain cached lookup exact match on the target’s dotted path, same as _inherit_tab, with no MRO/base-class fallback. Registering against a shared base like HorillaFilterSet directly, hoping it cascades to every concrete filter, won’t work; each concrete FilterSet needs its own registration (or, as custom_fields shows, its own dynamically generated one).

_inherit_filter follows the same registration shape as every other extension kind in this series a small class, an _inherit_filter path, picked up via auto_import_modules but its two real differences are worth remembering: resolution happens per get_filterset_class() call rather than per request, which is why a code change here needs a server restart to take effect; and there’s no base-class fan-out, so extending “every filterset” means registering against every concrete filterset individually, dynamically if needed, the way custom_fields does it. For most cases adding one field, excluding one, overriding one method with super() the simple quick-start pattern is all you need.

Share this article