Django Custom Template Filter 만들기

Kangjik Kim·2025년 6월 17일

Django 템플릿에서 기본 제공하는 필터 외에도 우리만의 커스텀 필터가 필요할 때가 있습니다.

오늘은 검색어 하이라이트 기능을 예시로 커스텀 템플릿 필터를 만드는 방법을 알아보겠습니다.

1. 기본 구조 만들기

먼저 Django 앱 디렉토리 안에 templatetags 패키지를 생성해야 합니다:

myapp/
├── __init__.py
├── models.py
├── views.py
├── templatetags/      # 새로 생성
│   ├── __init__.py   # 빈 파일
│   └── custom_filters.py
└── templates/

2. 커스텀 필터 작성하기

custom_filters.py 파일에 커스텀 필터를 작성합니다:


from django import template
from django.utils.safestring import mark_safe
import re

# 템플릿 라이브러리 생성
register = template.Library()

@register.filter
def highlight(text, search):
    """
    텍스트 내의 검색어를 하이라이트 처리하는 필터

    Args:
        text: 원본 텍스트
        search: 검색어

    Returns:
        검색어가 <strong> 태그로 감싸진 텍스트
    """
    if not search or not text:
        return text
		
    # 특수문자 이스케이프 처리
    search = re.escape(search)
    # 대소문자 구분 없이 검색어 찾기
    pattern = re.compile(f'({search})', re.IGNORECASE)
    # 검색어를 <strong> 태그로 감싸기
    highlighted = pattern.sub(r'<strong>\\1</strong>', str(text))

    # HTML 안전하게 반환
    return mark_safe(highlighted)

3. 앱 등록 확인하기

커스텀 필터를 사용하려면 해당 앱이 INSTALLED_APPS에 등록되어 있어야 합니다:

# settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    ...
    'myapp',  # 여기에 앱이 등록되어 있어야 함
]

4. 템플릿에서 사용하기

이제 템플릿에서 새로운 커스텀 필터를 사용할 수 있습니다:

{% extends 'base.html' %}
{% load custom_filters %}  {# 커스텀 필터 로드 #}

{% block content %}
    <h1>{{ title|highlight:search_keyword }}</h1>
    <p>{{ content|highlight:search_keyword }}</p>
{% endblock %}

5. 다양한 필터 유형

단순 필터

@register.filter
def lower_with_underline(value):
    return f"_{str(value).lower()}_"

인자를 받는 필터

@register.filter
def replace_with(value, arg):
    return str(value).replace(arg, '***')

불리언 필터

@register.filter
def is_even(value):
    return int(value) % 2 == 0

6. 템플릿 태그와 필터의 차이

필터: 값을 변환하는 간단한 함수 ({{ value|filter }})
태그: 더 복잡한 로직 수행 가능 ({% tag %})

7. 주의사항

보안
- mark_safe()는 신중하게 사용해야 함
- XSS 공격 방지를 위해 사용자 입력은 항상 이스케이프 처리
성능
- 복잡한 연산은 뷰에서 처리하는 것이 좋음
- 템플릿 필터는 간단한 텍스트 처리에 적합
재사용성
- 여러 앱에서 공통으로 사용될 필터는 별도 유틸리티 앱으로 분리

8. 실제 사용 예시

검색 결과 페이지에서 검색어 하이라이트 적용:

{# search_results.html #}
{% load custom_filters %}

<div class="search-results">
    {% for result in results %}
        <div class="result-item">
            <h3>{{ result.title|highlight:search_query }}</h3>
            <p>{{ result.description|highlight:search_query }}</p>
        </div>
    {% endfor %}
</div>