혼합 콘텐츠에 StreamField 사용하는 방법¶

StreamField 사용¶

StreamField 는 다른 필드와 마찬가지로 페이지 모델 내에 정의할 수 있는 모델 필드입니다.

from django.db import models

from wagtail.models import Page
from wagtail.fields import StreamField
from wagtail import blocks
from wagtail.admin.panels import FieldPanel
from wagtail.images.blocks import ImageBlock

class BlogPage(Page):
    author = models.CharField(max_length=255)
    date = models.DateField("게시 날짜")
    body = StreamField([
        ('heading', blocks.CharBlock(form_classname="title")),
        ('paragraph', blocks.RichTextBlock()),
        ('image', ImageBlock()),
    ])

    content_panels = Page.content_panels + [
        FieldPanel('author'),
        FieldPanel('date'),
        FieldPanel('body'),
    ]

이 예시에서 BlogPage 의 본문 필드는 StreamField 로 정의되며, 작성자는 제목, 단락, 이미지의 세 가지 블록 유형에서 콘텐츠를 구성할 수 있으며, 원하는 순서로 사용하고 반복할 수 있습니다. 작성자가 사용할 수 있는 블록 유형은 (name, block_type) 튜플 목록으로 정의됩니다. ‘name’은 템플릿 내에서 블록 유형을 식별하는 데 사용되며, 변수 이름에 대한 표준 Python 규칙(소문자 및 밑줄, 공백 없음)을 따라야 합니다.

사용 가능한 블록 유형의 전체 목록은 StreamField 블록 참조에서 찾을 수 있습니다.

템플릿 렌더링¶

StreamField는 스트림 콘텐츠 전체와 각 개별 블록에 대한 HTML 표현을 제공합니다. 이 HTML을 페이지에 포함하려면 {% include_block %} 태그를 사용하십시오.

{% load wagtailcore_tags %}

    ...

{% include_block page.body %}

기본 렌더링에서 스트림의 각 블록은 <div class="block-my_block_name"> 요소로 래핑됩니다(여기서 my_block_name 은 StreamField 정의에 지정된 블록 이름입니다). 자체 HTML 마크업을 제공하려면 필드의 값을 반복하고 각 블록에 대해 {% include_block %} 을 호출할 수 있습니다.

{% load wagtailcore_tags %}

    ...

<article>
    {% for block in page.body %}
        <section>{% include_block block %}</section>
    {% endfor %}
</article>

특정 블록 유형의 렌더링을 더 세밀하게 제어하려면 각 블록 객체는 block_type 및 value 속성을 제공합니다.

{% load wagtailcore_tags %}

    ...

<article>
    {% for block in page.body %}
        {% if block.block_type == 'heading' %}
            <h1>{{ block.value }}</h1>
        {% else %}
            <section class="block-{{ block.block_type }}">
                {% include_block block %}
            </section>
        {% endif %}
    {% endfor %}
</article>

블록 결합¶

StreamField 내에서 내장 블록 유형을 직접 사용하는 것 외에도 다양한 방식으로 하위 블록을 결합하여 새 블록 유형을 구성할 수 있습니다. 이에 대한 예시는 다음과 같습니다.

• 이미지 선택기와 텍스트 필드로 구성된 “캡션이 있는 이미지” 블록

• 콘텐츠 작성자가 다른 페이지에 대한 링크를 원하는 만큼 제공할 수 있는 “관련 링크” 섹션

• 각 슬라이드가 이미지, 텍스트 또는 비디오일 수 있고 원하는 순서로 정렬될 수 있는 슬라이드쇼 블록

새 블록 유형이 이러한 방식으로 구축되면 내장 블록 유형이 사용되는 모든 곳에서 사용할 수 있습니다. 다른 블록 유형의 구성 요소로 사용하는 것을 포함합니다. 예를 들어, 각 항목이 “캡션이 있는 이미지” 블록인 이미지 갤러리 블록을 정의할 수 있습니다.

body = StreamField([
    ('person', blocks.StructBlock([
        ('first_name', blocks.CharBlock()),
        ('surname', blocks.CharBlock()),
        ('photo', ImageBlock(required=False)),
        ('biography', blocks.RichTextBlock()),
    ])),
    ('heading', blocks.CharBlock(form_classname="title")),
    ('paragraph', blocks.RichTextBlock()),
    ('image', ImageBlock()),
])

<article>
    {% for block in page.body %}
        {% if block.block_type == 'person' %}
            <div class="person">
                {% image block.value.photo width-400 %}
                <h2>{{ block.value.first_name }} {{ block.value.surname }}</h2>
                {{ block.value.biography }}
            </div>
        {% else %}
            (다른 블록 유형에 대한 렌더링)
        {% endif %}
    {% endfor %}
</article>

class PersonBlock(blocks.StructBlock):
    first_name = blocks.CharBlock()
    surname = blocks.CharBlock()
    photo = ImageBlock(required=False)
    biography = blocks.RichTextBlock()

body = StreamField([
    ('person', PersonBlock()),
    ('heading', blocks.CharBlock(form_classname="title")),
    ('paragraph', blocks.RichTextBlock()),
    ('image', ImageBlock()),
])

body = StreamField([
    ('person', blocks.StructBlock([
        ('first_name', blocks.CharBlock()),
        ('surname', blocks.CharBlock()),
        ('photo', ImageBlock(required=False)),
        ('biography', blocks.RichTextBlock()),
    ], icon='user')),
    ('heading', blocks.CharBlock(form_classname="title")),
    ('paragraph', blocks.RichTextBlock()),
    ('image', ImageBlock()),
])

class PersonBlock(blocks.StructBlock):
    first_name = blocks.CharBlock()
    surname = blocks.CharBlock()
    photo = ImageBlock(required=False)
    biography = blocks.RichTextBlock()

    class Meta:
        icon = 'user'

body = StreamField([
    ('gallery', blocks.ListBlock(ImageBlock())),
    ('heading', blocks.CharBlock(form_classname="title")),
    ('paragraph', blocks.RichTextBlock()),
    ('image', ImageBlock()),
])

<article>
    {% for block in page.body %}
        {% if block.block_type == 'gallery' %}
            <ul class="gallery">
                {% for img in block.value %}
                    <li>{% image img width-400 %}</li>
                {% endfor %}
            </ul>
        {% else %}
            (다른 블록 유형에 대한 렌더링)
        {% endif %}
    {% endfor %}
</article>

body = StreamField([
    ('carousel', blocks.StreamBlock([
        ('image', ImageBlock()),
        ('video', EmbedBlock()),
    ])),
    ('heading', blocks.CharBlock(form_classname="title")),
    ('paragraph', blocks.RichTextBlock()),
    ('image', ImageBlock()),
])

class CarouselBlock(blocks.StreamBlock):
    image = ImageBlock()
    video = EmbedBlock()

    class Meta:
        icon = 'image'

class CommonContentBlock(blocks.StreamBlock):
    heading = blocks.CharBlock(form_classname="title")
    paragraph = blocks.RichTextBlock()
    image = ImageBlock()


class BlogPage(Page):
    body = StreamField(CommonContentBlock())

<article>
    {% for block in page.body %}
        {% if block.block_type == 'carousel' %}
            <ul class="carousel">
                {% for slide in block.value %}
                    {% if slide.block_type == 'image' %}
                        <li class="image">{% image slide.value width-200 %}</li>
                    {% else %}
                        <li class="video">{% include_block slide %}</li>
                    {% endif %}
                {% endfor %}
            </ul>
        {% else %}
            (다른 블록 유형에 대한 렌더링)
        {% endif %}
    {% endfor %}
</article>

body = StreamField([
    ('heading', blocks.CharBlock(form_classname="title")),
    ('paragraph', blocks.RichTextBlock()),
    ('image', ImageBlock()),
], min_num=2, max_num=5)

class CommonContentBlock(blocks.StreamBlock):
    heading = blocks.CharBlock(form_classname="title")
    paragraph = blocks.RichTextBlock()
    image = ImageBlock()

    class Meta:
        min_num = 2
        max_num = 5

body = StreamField([
    ('heading', blocks.CharBlock(form_classname="title")),
    ('paragraph', blocks.RichTextBlock()),
    ('image', ImageBlock()),
], block_counts={
    'heading': {'min_num': 1, 'max_num': 3},
})

class CommonContentBlock(blocks.StreamBlock):
    heading = blocks.CharBlock(form_classname="title")
    paragraph = blocks.RichTextBlock()
    image = ImageBlock()

    class Meta:
        block_counts = {
            'heading': {'min_num': 1, 'max_num': 3},
        }

블록별 템플릿¶

기본적으로 각 블록은 간단하고 최소한의 HTML 마크업으로 렌더링되거나 전혀 마크업되지 않습니다. 예를 들어, CharBlock 값은 일반 텍스트로 렌더링되는 반면, ListBlock은 자식 블록을 <ul> 래퍼로 출력합니다. 이를 사용자 지정 HTML 렌더링으로 재정의하려면 블록에 template 인수를 전달하여 렌더링할 템플릿 파일의 파일 이름을 지정할 수 있습니다. 이는 StructBlock에서 파생된 사용자 지정 블록 유형에 특히 유용합니다.

('person', blocks.StructBlock(
    [
        ('first_name', blocks.CharBlock()),
        ('surname', blocks.CharBlock()),
        ('photo', ImageBlock(required=False)),
        ('biography', blocks.RichTextBlock()),
    ],
    template='myapp/blocks/person.html',
    icon='user'
))

또는 StructBlock의 서브클래스로 정의된 경우:

class PersonBlock(blocks.StructBlock):
    first_name = blocks.CharBlock()
    surname = blocks.CharBlock()
    photo = ImageBlock(required=False)
    biography = blocks.RichTextBlock()

    class Meta:
        template = 'myapp/blocks/person.html'
        icon = 'user'

템플릿 내에서 블록 값은 value 변수로 액세스할 수 있습니다.

{% load wagtailimages_tags %}

<div class="person">
    {% image value.photo width-400 %}
    <h2>{{ value.first_name }} {{ value.surname }}</h2>
    {{ value.biography }}
</div>

first_name, surname, photo, biography 는 자체적으로 블록으로 정의되어 있으므로 다음과 같이 작성할 수도 있습니다.

{% load wagtailcore_tags wagtailimages_tags %}

<div class="person">
    {% image value.photo width-400 %}
    <h2>{% include_block value.first_name %} {% include_block value.surname %}</h2>
    {% include_block value.biography %}
</div>

{{ my_block }} 을 작성하는 것은 {% include_block my_block %} 과 거의 동일하지만, 짧은 형식은 더 제한적입니다. request 또는 page 와 같은 호출 템플릿의 변수를 전달하지 않기 때문입니다. 이러한 이유로 자체 HTML을 렌더링하지 않는 간단한 값에만 사용하는 것이 좋습니다. 예를 들어, PersonBlock이 다음 템플릿을 사용했다면:

{% load wagtailimages_tags %}

<div class="person">
    {% image value.photo width-400 %}
    <h2>{{ value.first_name }} {{ value.surname }}</h2>

    {% if request.user.is_authenticated %}
        <a href="#">이 사람에게 연락하기</a>
    {% endif %}

    {{ value.biography }}
</div>

request.user.is_authenticated 테스트는 {{ ... }} 태그를 통해 블록을 렌더링할 때 올바르게 작동하지 않습니다.

{# 잘못됨: #}

{% for block in page.body %}
    {% if block.block_type == 'person' %}
        <div>
            {{ block }}
        </div>
    {% endif %}
{% endfor %}

{# 올바름: #}

{% for block in page.body %}
    {% if block.block_type == 'person' %}
        <div>
            {% include_block block %}
        </div>
    {% endif %}
{% endfor %}

Django의 {% include %} 태그와 마찬가지로 {% include_block %} 도 {% include_block my_block with foo="bar" %} 구문을 통해 포함된 템플릿에 추가 변수를 전달할 수 있습니다.

{# 페이지 템플릿에서: #}

{% for block in page.body %}
    {% if block.block_type == 'person' %}
        {% include_block block with classname="important" %}
    {% endif %}
{% endfor %}

{# PersonBlock 템플릿에서: #}

<div class="{{ classname }}">
    ...
</div>

{% include_block my_block with foo="bar" only %} 구문도 지원되며, foo 를 제외한 부모 템플릿의 변수는 자식 템플릿에 전달되지 않도록 지정합니다.

부모 템플릿에서 변수를 전달하는 것 외에도 블록 서브클래스는 get_context 메서드를 재정의하여 자체 추가 템플릿 변수를 전달할 수 있습니다.

import datetime

class EventBlock(blocks.StructBlock):
    title = blocks.CharBlock()
    date = blocks.DateBlock()

    def get_context(self, value, parent_context=None):
        context = super().get_context(value, parent_context=parent_context)
        context['is_happening_today'] = (value['date'] == datetime.date.today())
        return context

    class Meta:
        template = 'myapp/blocks/event.html'

이 예시에서 is_happening_today 변수는 블록 템플릿 내에서 사용할 수 있게 됩니다. parent_context 키워드 인수는 블록이 {% include_block %} 태그를 통해 렌더링될 때 사용할 수 있으며, 호출 템플릿에서 전달된 변수 사전입니다.

마찬가지로 get_template 메서드를 정의하여 블록 값에 따라 템플릿을 동적으로 선택할 수 있습니다.

import datetime

class EventBlock(blocks.StructBlock):
    title = blocks.CharBlock()
    date = blocks.DateBlock()

    def get_template(self, value, context=None):
        if value["date"] > datetime.date.today():
            return "myapp/blocks/future_event.html"
        else:
            return "myapp/blocks/event.html"

StructBlock 뿐만 아니라 모든 블록 유형은 template 속성을 지원합니다. 그러나 CharBlock 및 IntegerBlock 과 같은 기본 Python 데이터 유형을 처리하는 블록의 경우 템플릿이 적용될 수 있는 위치에 몇 가지 제한이 있습니다. 자세한 내용은 StreamField BoundBlocks와 값에 관하여를 참조하십시오.

블록 미리 보기 구성¶

StreamField 블록은 편집기에서 블록 선택기 내에 표시될 미리 보기를 가질 수 있습니다. 이 기능을 활성화하려면 미리 보기 값과 템플릿을 구성해야 합니다. 사용자가 콘텐츠에 적합한 블록을 선택하는 데 도움이 되도록 설명을 추가할 수도 있습니다.

블록을 인스턴스화할 때 preview_value, preview_template, description 키워드 인수를 전달하여 이를 수행할 수 있습니다.

("quote", blocks.StructBlock(
    [
        ("text", blocks.TextBlock()),
        ("source", blocks.CharBlock()),
    ],
    preview_value={"text": "이것은 역사상 가장 멋진 CMS입니다.", "source": "윌리 왜그테일"},
    preview_template="myapp/previews/blocks/quote.html",
    description="출처를 밝힌 인용구로, 인용 블록으로 렌더링됩니다.",
))

블록의 Meta 클래스에 preview_value, preview_template, description 을 속성으로 설정할 수도 있습니다. 예를 들어:

class QuoteBlock(blocks.StructBlock):
    text = blocks.TextBlock()
    source = blocks.CharBlock()

    class Meta:
        preview_value={"text": "이것은 역사상 가장 멋진 CMS입니다.", "source": "윌리 왜그테일"}
        preview_template="myapp/previews/blocks/quote.html"
        description="출처를 밝힌 인용구로, 인용 블록으로 렌더링됩니다."

미리 보기 옵션에 대한 자세한 내용은 해당 get_preview_value(), get_preview_template() 및 get_description() 메서드와 get_preview_context() 메서드를 참조하십시오.

특히 get_preview_value() 메서드는 데이터베이스에서와 같이 동적 미리 보기 값을 제공하도록 재정의할 수 있습니다.

from myapp.models import Quote


class QuoteBlock(blocks.StructBlock):
    ...

    def get_preview_value(self, value):
        quote = Quote.objects.first()
        return {"text": quote.text, "source": quote.source}

{% extends "wagtailcore/shared/block_preview.html" %}
{% load static %}

{% block css %}
    {{ block.super }}
    <link rel="stylesheet" href="{% static 'css/my-styles.css' %}">
{% endblock %}

{% block js %}
    {{ block.super }}
    <script src="{% static 'js/my-script.js' %}"></script>
{% endblock %}

class ConfigBlock(blocks.StructBlock):
    ...
    is_previewable = False

사용자 지정¶

모든 블록 유형은 프런트엔드 및 폼 표현을 렌더링하고 데이터베이스에서 값을 저장하고 검색하기 위한 공통 API를 구현합니다. 다양한 블록 클래스를 서브클래스화하고 이러한 메서드를 재정의하여 StructBlock 폼 필드의 레이아웃을 수정하는 것부터 블록을 결합하는 완전히 새로운 방법을 구현하는 것까지 모든 종류의 사용자 지정이 가능합니다. 자세한 내용은 사용자 정의 StreamField 블록을 만드는 방법를 참조하십시오.

StreamField 데이터 수정¶

StreamField의 값은 목록처럼 동작하며, 인스턴스를 데이터베이스에 다시 저장하기 전에 블록을 삽입, 덮어쓰기 및 삭제할 수 있습니다. 새 항목은 (블록 유형, 값) 튜플로 목록에 작성할 수 있습니다. 다시 읽을 때 BoundBlock 객체로 반환됩니다.

# 첫 번째 블록을 'heading' 유형의 새 블록으로 바꿉니다.
my_page.body[0] = ('heading', "내 이야기")

# 마지막 블록 삭제
del my_page.body[-1]

# 스트림에 리치 텍스트 블록 추가
my_page.body.append(('paragraph', "<p>그리고 그들은 모두 행복하게 살았습니다.</p>"))

# 업데이트된 데이터를 데이터베이스에 다시 저장
my_page.save()

StructBlock을 확장하는 블록이 StreamField의 값 내에서 사용될 경우, 이 블록의 값은 Python 사전(블록의 .to_python 메서드에서 허용하는 것과 유사)으로 제공될 수 있습니다.

from wagtail import blocks

class UrlWithTextBlock(blocks.StructBlock):
   url = blocks.URLBlock()
   text = blocks.TextBlock()

# 콘텐츠 내에서 이 블록 사용

data = {
    'url': 'https://github.com/wagtail/',
    'text': '매우 흥미롭고 유용한 저장소'
}

# 정의된 이 블록 유형의 인덱스와 함께 새 블록을 스트림에 튜플로 추가
my_page.body.append(('url', data))
my_page.save()

이름으로 블록 검색¶

StreamField 값은 주어진 이름의 모든 블록을 검색하기 위한 blocks_by_name 메서드를 제공합니다.

my_page.body.blocks_by_name('heading')  # 'heading' 블록 목록 반환

인수 없이 blocks_by_name 을 호출하면 블록 이름을 해당 이름의 블록 목록에 매핑하는 사전과 유사한 객체가 반환됩니다. 이는 인수를 전달할 수 없는 템플릿 코드에서 특히 유용합니다.

<h2>목차</h2>
<ol>
    {% for heading_block in page.body.blocks_by_name.heading %}
        <li>{{ heading_block.value }}</li>
    {% endfor %}
</ol>

first_block_by_name 메서드는 스트림에서 주어진 이름의 첫 번째 블록을 반환하거나 일치하는 블록이 없으면 None 을 반환합니다.

hero_image = my_page.body.first_block_by_name('image')

first_block_by_name 은 인수 없이 호출하여 사전과 유사한 매핑을 반환할 수도 있습니다.

<div class="hero-image">{{ page.body.first_block_by_name.image }}</div>

검색 고려 사항¶

다른 필드와 마찬가지로 StreamField의 콘텐츠는 모델의 search_fields 정의에 필드를 추가하여 검색 가능하게 만들 수 있습니다. 추가 필드 색인화 를 참조하십시오. 기본적으로 스트림의 모든 텍스트 콘텐츠는 검색 색인에 추가됩니다. 특정 블록 유형을 색인에서 제외하려면 블록 정의의 일부로 search_index=False 키워드 인수를 전달합니다. 예를 들어:

body = StreamField([
    ('normal_text', blocks.RichTextBlock()),
    ('pull_quote', blocks.RichTextBlock(search_index=False)),
    ('footnotes', blocks.ListBlock(blocks.CharBlock(), search_index=False)),
])

사용자 지정 유효성 검사¶

블록에 사용자 지정 유효성 검사 논리를 추가하려면 블록의 clean 메서드를 재정의합니다. 자세한 내용은 StreamField 유효성 검사을 참조하십시오.

마이그레이션¶

StreamField 데이터는 단일 JSON 필드로 저장되며, 공식적인 데이터베이스 구조로 정렬되지 않으므로 StreamField의 데이터 구조를 변경하거나 다른 필드 유형으로 변환할 때 데이터 마이그레이션을 작성해야 하는 경우가 많습니다. StreamField가 Django의 마이그레이션 시스템과 상호 작용하는 방법과 리치 텍스트를 StreamField로 마이그레이션하는 방법에 대한 자세한 내용은 StreamField 마이그레이션를 참조하십시오.