(jinja2)=

# Jinja2 템플릿 지원

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

## Django 구성

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

```python
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 문서는 {class}`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) 인스턴스:

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

자세한 내용은 [](fullpageurl_tag) 문서를 참조하세요.

### `pageurl()`

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

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

자세한 내용은 [](pageurl_tag) 문서를 참조하세요.

### `slugurl()`

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

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

자세한 내용은 [](slugurl_tag) 문서를 참조하세요.

### `image()`

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

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

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

```html+jinja
{% 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를 모두 처리하는 루프에서 특히 유용합니다.

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

자세한 내용은 [](image_tag) 문서를 참조하세요.

### `srcset_image()`

이미지 크기를 조절하고 여러 크기의 `srcset` 을 포함하는 `<img>` 태그를 렌더링합니다.
브라우저는 [반응형 이미지 규칙](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)에 따라 로드할 가장 적절한 이미지(image)를 선택합니다.
[`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes) 속성은 `srcset_image` 의 출력을 나중에 사용하기 위해 저장하지 않는 한 필수적입니다.

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

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

```html
<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)을 검색합니다:

```html+jinja
{% 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` 를 사용할 수 있습니다.

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

### `picture()`

이미지(image) 크기를 조절하거나 변환하여 여러 `source` 형식과 여러 크기에 대한 `srcset` 을 포함하는 `<picture>` 태그와 대체 `<img>` 태그를 렌더링합니다.
브라우저는 [첫 번째 지원되는 이미지 형식](https://web.dev/learn/design/picture-element/#image_formats)을 선택하고, [반응형 이미지 규칙](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)에 따라 크기를 선택합니다.

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

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

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

```html
<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`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes) 속성은 필수적입니다:

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

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

```html
<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)을 검색합니다:

```html+jinja
{% 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` 를 사용할 수 있습니다:

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

### `|richtext`

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

```html+jinja
{{ page.body|richtext }}
```

자세한 내용은 [](rich_text_filter) 문서를 참조하세요.

### `wagtail_site`

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

```html+jinja
{{ wagtail_site().site_name }}
```

자세한 내용은 [](wagtail_site_tag) 문서를 참조하세요.

### `wagtailuserbar()`

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

```html+jinja
{{ wagtailuserbar() }}
```

자세한 내용은 [](wagtailuserbar_tag) 문서를 참조하세요.

### `{% include_block %}`

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

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

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

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

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