Jinja2 템플릿 지원

Wagtail은 모든 프런트엔드 기능에 대해 Jinja2 템플릿을 지원합니다. 아래 각 템플릿 태그에 대한 자세한 정보는 템플릿 작성 문서에서 찾을 수 있습니다.

Django 구성

Django는 Jinja2 템플릿을 지원하도록 구성되어야 합니다. Wagtail 관리자(admin)는 표준 Django 템플릿을 사용하여 작성되었으므로, Django는 두 가지 템플릿 엔진을 모두 사용하도록 구성해야 합니다. 여기에 표시된 대로 Jinja2 템플릿 백엔드 구성을 앱의 TEMPLATES 설정에 추가하세요.

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        # ... the rest of the existing Django template configuration ...
    },
    {
        'BACKEND': 'django.template.backends.jinja2.Jinja2',
        'APP_DIRS': True,
        'OPTIONS': {
            'extensions': [
                'wagtail.jinja2tags.core',
                'wagtail.admin.jinja2tags.userbar',
                'wagtail.images.jinja2tags.images',
            ],
        },
    }
]

Jinja 템플릿은 앱의 jinja2/ 디렉터리에 배치해야 합니다. 예를 들어, events 앱의 EventPage 모델에 대한 표준 템플릿 위치는 events/jinja2/events/event_page.html 이 됩니다.

기본적으로 Jinja 환경에는 Django 함수나 필터가 없습니다. Django 문서는 django.template.backends.jinja2.Jinja2 (Django용 Jinja 구성)에 대한 더 많은 정보를 담고 있습니다.

템플릿의 self

Django 템플릿에서 self 는 현재 페이지, 스트림 블록 또는 필드 패널을 참조하는 데 사용될 수 있습니다. Jinja에서는 self 가 내부용으로 예약되어 있습니다. Jinja 템플릿을 작성할 때는 페이지를 참조할 때는 page 를, 스트림 블록에는 value 를, 필드 패널에는 field_panel 을 사용하세요.

템플릿 태그, 함수 & 필터

fullpageurl()

Generate an absolute URL (http://example.com/foo/bar/) for a 페이지(Page) 인스턴스:

<meta property="og:url" content="{{ fullpageurl(page) }}" />

자세한 내용은 fullpageurl 문서를 참조하세요.

pageurl()

페이지(Page) 인스턴스의 URL (/foo/bar/)을 생성합니다:

<a href="{{ pageurl(page.more_information) }}">더 많은 정보</a>

자세한 내용은 pageurl 문서를 참조하세요.

slugurl()

슬러그(slug)를 가진 페이지(Page)의 URL을 생성합니다:

<a href="{{ slugurl("about") }}">회사 소개</a>

자세한 내용은 slugurl 문서를 참조하세요.

image()

이미지(image) 크기를 조절하고 <img> 태그를 렌더링합니다:

{{ image(page.header_image, "fill-1024x200", class="header-image") }}

또는 이미지 크기를 조절하고 더 맞춤형으로 사용하기 위해 크기가 조절된 이미지 객체(rendition)를 검색합니다:

{% set background=image(page.background_image, "max-1024x1024") %}
<div class="wrapper" style="background-image: url({{ background.url }});"></div>

SVG 이미지로 작업할 때, SVG를 래스터화해야 하는 작업을 방지하려면 필터 문자열에 preserve-svg 를 사용할 수 있습니다. preserve-svg 가 존재하고 이미지가 SVG인 경우, 래스터화가 필요한 작업(예: 형식 변환)은 자동으로 필터링되어 SVG가 벡터 그래픽으로 유지되도록 합니다. 이는 래스터 이미지와 SVG를 모두 처리하는 루프에서 특히 유용합니다.

{{ image(page.svg_image, "width-400|format-webp|preserve-svg") }}

자세한 내용은 템플릿에서 이미지 사용하는 방법 문서를 참조하세요.

srcset_image()

이미지 크기를 조절하고 여러 크기의 srcset 을 포함하는 <img> 태그를 렌더링합니다. 브라우저는 반응형 이미지 규칙에 따라 로드할 가장 적절한 이미지(image)를 선택합니다. sizes 속성은 srcset_image 의 출력을 나중에 사용하기 위해 저장하지 않는 한 필수적입니다.

{{ srcset_image(page.photo, "width-{400,800}", sizes="(max-width: 600px) 400px, 80vw") }}

이것은 다음을 출력합니다:

<img srcset="/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w" src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" sizes="(max-width: 600px) 400px, 80vw" width="400" height="300">

또는 이미지 크기를 조절하고 더 맞춤형으로 사용하기 위해 렌디션(rendition)을 검색합니다:

{% set bg=srcset_image(page.background_image, "max-{512x512,1024x1024}") %}
<div class="wrapper" style="background-image: image-set(url({{ bg.renditions[0].url }}) 1x, url({{ bg.renditions[1].url }}) 2x);"></div>

SVG 이미지로 작업할 때, SVG를 래스터화해야 하는 작업을 방지하려면 필터 문자열에 preserve-svg 를 사용할 수 있습니다.

{{ srcset_image(page.svg_image, "width-400|format-webp|preserve-svg") }}

picture()

이미지(image) 크기를 조절하거나 변환하여 여러 source 형식과 여러 크기에 대한 srcset 을 포함하는 <picture> 태그와 대체 <img> 태그를 렌더링합니다. 브라우저는 첫 번째 지원되는 이미지 형식을 선택하고, 반응형 이미지 규칙에 따라 크기를 선택합니다.

picture 는 이미지를 여러 형식으로 렌더링할 수 있습니다:

{{ picture(page.photo, "format-{avif,webp,jpeg}|width-400") }}

이것은 다음을 출력합니다:

<picture>
    <source srcset="/media/images/pied-wagtail.width-400.avif" type="image/avif">
    <source srcset="/media/images/pied-wagtail.width-400.webp" type="image/webp">
    <img src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" width="400" height="300">
</picture>

또는 srcset_image 와 같이 여러 형식과 여러 크기를 렌더링합니다. picture 태그가 여러 크기의 이미지를 렌더링할 때 sizes 속성은 필수적입니다:

{{ picture(page.header_image, "format-{avif,webp,jpeg}|width-{400,800}", sizes="80vw") }}

이것은 다음을 출력합니다:

<picture>
    <source sizes="80vw" srcset="/media/images/pied-wagtail.width-400.avif 400w, /media/images/pied-wagtail.width-800.avif 800w" type="image/avif">
    <source sizes="80vw" srcset="/media/images/pied-wagtail.width-400.webp 400w, /media/images/pied-wagtail.width-800.webp 800w" type="image/webp">
    <img sizes="80vw" srcset="/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w" src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" width="400" height="300">
</picture>

또는 이미지 크기를 조절하고 더 맞춤형으로 사용하기 위해 렌디션(rendition)을 검색합니다:

{% set bg=picture(page.background_image, "format-{avif,jpeg}|max-{512x512,1024x1024}") %}
<div class="wrapper" style="background-image: image-set(url({{ bg.formats['avif'][0].url }}) 1x type('image/avif'), url({{ bg.formats['avif'][1].url }}) 2x type('image/avif'), url({{ bg.formats['jpeg'][0].url }}) 1x type('image/jpeg'), url({{ bg.formats['jpeg'][1].url }}) 2x type('image/jpeg'));"></div>

SVG 이미지의 경우, 벡터 그래픽으로 유지되도록 필터 문자열에 preserve-svg 를 사용할 수 있습니다:

{{ picture(page.header_image, "format-{avif,webp,jpeg}|width-{400,800}|preserve-svg", sizes="80vw") }}

|richtext

Wagtail의 내부 HTML 표현을 변환하여 페이지(page) 및 이미지(image)에 대한 내부 참조를 확장합니다.

{{ page.body|richtext }}

자세한 내용은 리치 텍스트 (필터) 문서를 참조하세요.

wagtail_site

현재 요청에 해당하는 사이트(Site) 객체를 반환합니다.

{{ wagtail_site().site_name }}

자세한 내용은 wagtail_site 문서를 참조하세요.

wagtailuserbar()

프런트엔드에서 페이지(page) 편집을 위한 Wagtail 상황별 플라이아웃 메뉴를 출력합니다.

{{ wagtailuserbar() }}

자세한 내용은 Wagtail 사용자 바 문서를 참조하세요.

{% include_block %}

스트림 콘텐츠 전체의 HTML 표현과 각 개별 블록의 HTML 표현을 출력합니다.

StreamField 템플릿에 (기본적으로) 템플릿 컨텍스트를 전달할 수 있습니다.

{% include_block page.body %}
{% include_block page.body with context %} {# The same as the previous #}
{% include_block page.body without context %}

자세한 내용은 StreamField 템플릿 렌더링 문서를 참조하세요.

참고

{% include_block %} 태그는 Jinja의 {% include %} 의 구문과 동작을 밀접하게 따르도록 설계되었으므로, Django 버전의 특정 변수만 컨텍스트로 전달하는 기능을 구현하지 않습니다.