패널¶

내장 필드 및 선택기¶

Wagtail의 패널 메커니즘은 Django 모델 필드를 자동으로 인식하고 입력에 적합한 위젯을 제공합니다. 모델 정의에서 필드를 정상적으로 정의하고 패널을 정의할 때 필드 이름을 FieldPanel(또는 적절한 패널 유형)에 전달하여 사용할 수 있습니다.

다음은 패널 정의에서 사용할 수 있는 몇 가지 내장 패널 유형입니다. 이들은 모두 기본 Panel 클래스의 서브클래스이며, 달리 명시되지 않는 한 자체 매개변수 외에 Panel 의 모든 매개변수를 허용합니다.

FieldPanel¶

class wagtail.admin.panels.FieldPanel(field_name, widget=None, disable_comments=None, permission=None, read_only=False, required_on_save=None, **kwargs)¶

이것은 기본 Django 모델 필드 유형에 사용할 패널입니다. 모델 필드 정의를 기반으로 기본 아이콘과 제목을 제공하지만, 생성자에 추가 인수를 전달하여 사용자 지정할 수 있습니다. 자세한 내용은 패널 사용자 지정 를 참조하십시오.

field_name¶: 모델 정의에 사용된 클래스 속성의 이름입니다.

widget(선택 사항)¶: 이 매개변수를 사용하면 이 필드 유형의 기본 위젯 대신 사용할 Django 폼 위젯 을 지정할 수 있습니다.

disable_comments(선택 사항)¶: True 로 설정하면 이 패널에 대한 필드 수준 주석 버튼이 표시되지 않도록 할 수 있습니다. ` 주석 생성 및 편집 <https://guide.wagtail.org/en-latest/how-to-guides/manage-pages/#create-and-edit-comments>`_을 참조하십시오.

permission(선택 사항)¶: 충분한 권한이 있는 사용자에게 필드를 선택적으로 표시할 수 있습니다. 'myapp.change_blog_category' 와 같은 권한 코드 이름을 허용합니다. 로그인한 사용자에게 해당 권한이 없으면 필드는 폼에서 생략됩니다. 권한을 설정하는 방법에 대한 자세한 내용은 Django의 :ref:` 사용자 지정 권한 <django:custom-permissions>` 에 대한 문서를 참조하십시오. 또는 필드를 슈퍼유저만 사용할 수 있도록 설정하려면 슈퍼유저는 모든 권한 테스트를 자동으로 통과하므로 코드 이름으로 임의의 문자열(예: 'superuser')을 사용할 수 있습니다.

read_only(선택 사항)¶

편집자가 모델 필드 값을 설정하거나 업데이트하는 것을 방지할 수 있습니다.

대부분의 필드 유형의 경우 필드 값은 편집자가 볼 수 있도록 폼에 렌더링되지만(필드의 레이블 및 도움말 텍스트와 함께) 폼 입력은 표시되지 않으며, 폼은 POST 데이터에서 값을 변경하려는 시도를 무시합니다. 예를 들어 제출하기 전에 폼 HTML에 숨겨진 입력을 삽입하여.

기본적으로 StreamField 또는 RichTextField 의 필드 값은 잠재적으로 안전하지 않은 HTML이 폼 중간에 렌더링되는 것을 방지하기 위해 수정됩니다. Panel.format_value_for_display() 를 재정의하여 사용자 지정 패널 유형에 대한 이 동작을 변경할 수 있습니다.

required_on_save(선택 사항)¶

초안으로 저장할 때 이 필드에 필수 제약 조건을 적용할지 여부를 지정합니다.

페이지 모델 및 DraftStateMixin 을 사용하는 스니펫의 경우, 초안으로 저장할 때 기본적으로 필수 필드의 유효성 검사를 건너뜁니다. 이를 통해 편집자는 항목이 아직 불완전한 동안에도 초안을 저장할 수 있습니다. 필수 필드의 유효성 검사는 페이지 또는 스니펫이 게시, 예약 또는 워크플로에 제출될 때 적용됩니다. 이 동작을 재정의하고 초안을 저장할 때 유효성 검사를 강제하려면 required_on_save 를 True 로 설정하십시오. 이는 모델 필드에 required_on_save 속성을 설정하여 달성할 수도 있습니다.

subtitle = models.CharField(max_length=255)
subtitle.required_on_save = True

참고: null=True 로 정의되지 않은 비텍스트 기반 필드(예: IntegerField 및 DateField)는 데이터베이스 수준에서 빈 값을 저장하는 것을 허용하지 않으므로 초안을 저장할 때 항상 필수 필드로 강제됩니다.

Added in version 7.0: 초안을 저장할 때 필수 필드를 비워 둘 수 있는 기능이 도입되었습니다.

attrs(선택 사항)¶: 렌더링된 패널에 HTML 속성을 포함하는 사전을 설정할 수 있습니다. 속성에 True 또는 False 값을 할당하면 HTML5 부울 속성으로 렌더링됩니다.

참고

패널 정의의 일반 문자열은 인수가 없는 FieldPanel과 동일합니다.

다음을 사용하십시오.

    content_panels = Page.content_panels + ["title", "body"]

대신

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

MultiFieldPanel¶

class wagtail.admin.panels.MultiFieldPanel(children=(), *args, permission=None, **kwargs)¶

이 패널은 여러 FieldPanel 또는 선택기를 list 또는 tuple 에서 단일 heading 문자열 아래로 압축합니다. 공간을 절약하기 위해 :ref:` 기본적으로 패널을 축소 <collapsible>` 할 수 있습니다.

children¶: 자식 패널의 list 또는 tuple

permission(선택 사항)¶: 충분한 권한이 있는 사용자에게 패널을 선택적으로 표시할 수 있습니다. 'myapp.change_blog_category' 와 같은 권한 코드 이름을 허용합니다. 로그인한 사용자에게 해당 권한이 없으면 패널은 폼에서 생략됩니다. FieldPanel.permission 과 유사합니다.

attrs(선택 사항)¶: 렌더링된 패널에 HTML 속성을 포함하는 사전을 설정할 수 있습니다. 속성에 True 또는 False 값을 할당하면 HTML5 부울 속성으로 렌더링됩니다.

InlinePanel¶

class wagtail.admin.panels.InlinePanel(relation_name, panels=None, label='', min_num=None, max_num=None, **kwargs)¶

이 패널은 별도의 모델에 대한 조인을 통해 관련 객체의 “클러스터”를 생성할 수 있도록 합니다. 예를 들어 관련 링크 목록 또는 이미지 캐러셀에 대한 슬라이드입니다. InlinePanel 사용에 대한 전체 설명은 인라인 모델 를 참조하십시오. 공간을 절약하기 위해 :ref:` 기본적으로 패널을 축소 <collapsible>` 할 수 있습니다.

relation_name¶: 클러스터의 ParentalKey 관계에 부여된 related_name 레이블입니다.

panels(선택 사항)¶: 자식 객체의 폼을 구성할 패널 목록입니다. 여기에 지정되지 않은 경우 자식 모델의 panels 정의가 사용됩니다.

label¶: 추가 버튼 및 자식 패널의 제목에 대한 텍스트입니다. heading 이 없는 경우 제목으로 사용됩니다.

min_num(선택 사항)¶: 사용자가 제출해야 하는 최소 폼 수입니다.

max_num(선택 사항)¶: 사용자가 제출할 수 있는 최대 폼 수입니다.

attrs(선택 사항)¶: 렌더링된 패널에 HTML 속성을 포함하는 사전을 설정할 수 있습니다. 속성에 True 또는 False 값을 할당하면 HTML5 부울 속성으로 렌더링됩니다.

참고

패널 정의의 일반 문자열은 인수가 없는 InlinePanel과 동일합니다.

다음을 사용하십시오.

    content_panels = Page.content_panels + ["gallery_images"]

대신

    content_panels = Page.content_panels + [
        InlinePanel('gallery_images'),
    ]

JavaScript DOM 이벤트¶

InlinePanel 항목이 준비되거나 추가되거나 제거될 때 일부 JavaScript를 실행해야 할 수 있습니다. w-formset:ready, w-formset:added 및 w-formset:removed 이벤트를 통해 이를 수행할 수 있습니다.

예를 들어, BlogPage 에서 블로그와 사람 간의 관계를 제공하는 자식 모델이 주어졌을 때.

class CustomInlinePanel(InlinePanel):
    class BoundPanel(InlinePanel.BoundPanel):
        class Media:
            js = ["js/inline-panel.js"]


class BlogPage(Page):
        # .. 필드

        content_panels = Page.content_panels + [
               CustomInlinePanel("blog_person_relationship"),
              # ... 기타 패널
        ]

JavaScript 사용법은 다음과 같습니다.

// static/js/inline-panel.js

document.addEventListener('w-formset:ready', function (event) {
    console.info('ready', event);
});

document.addEventListener('w-formset:added', function (event) {
    console.info('added', event);
});

document.addEventListener('w-formset:removed', function (event) {
    console.info('removed', event);
});

이벤트는 디스패치되어 사용자 지정 위젯 설정과 같은 사용자 지정 JavaScript 논리를 트리거할 수 있습니다.

MultipleChooserPanel¶

class wagtail.admin.panels.MultipleChooserPanel(relation_name, chooser_field_name=None, panels=None, label='', min_num=None, max_num=None, **kwargs)¶

이 패널은 인라인 모델에 Wagtail의 선택기 인터페이스를 구현하는 모델에 대한 ForeignKey 관계가 포함된 경우 사용할 수 있는 InlinePanel 의 변형입니다. Wagtail 이미지, 문서, 스니펫 및 페이지는 모두 이 인터페이스를 구현하며, 다른 모델은 사용자 지정 ChooserViewSet 등록을 통해 이를 수행할 수 있습니다.

“추가” 버튼이 개별적으로 채워질 새 폼을 삽입하는 대신, 해당 관련 객체에 대한 선택기 인터페이스를 즉시 열고 여러 항목을 선택할 수 있는 모드에서 엽니다. 그러면 사용자는 적절한 수의 자식 패널이 추가되고 미리 채워진 상태로 기본 편집 폼으로 돌아갑니다.

MultipleChooserPanel 은 선택기가 연결된 ForeignKey 관계의 이름을 지정하는 추가 필수 인수 chooser_field_name 을 허용합니다.

예를 들어, BlogPage 에 이미지 갤러리를 제공하는 자식 모델이 주어졌을 때:

class BlogPageGalleryImage(Orderable):
    page = ParentalKey(BlogPage, on_delete=models.CASCADE, related_name='gallery_images')
    image = models.ForeignKey(
        'wagtailimages.Image', on_delete=models.CASCADE, related_name='+'
    )
    caption = models.CharField(blank=True, max_length=250)

    panels = [
        FieldPanel('image'),
        FieldPanel('caption'),
    ]

BlogPage 의 MultipleChooserPanel 정의는 다음과 같습니다.

        MultipleChooserPanel(
            'gallery_images', label="갤러리 이미지", chooser_field_name="image"
        )

FieldRowPanel¶

class wagtail.admin.panels.FieldRowPanel(children=(), *args, permission=None, **kwargs)¶

이 패널은 편집 인터페이스에서 열 형식 레이아웃을 생성하며, 각 자식 패널이 서로 옆에 표시되고 아래에는 표시되지 않습니다.

FieldRowPanel 을 사용하면 특히 복잡한 모델의 경우 페이지에 너무 많은 필드가 표시되는 “눈가림” 효과를 줄이는 데 도움이 됩니다. 또한 유사한 특성의 필드 간의 인식된 연관성을 향상시킵니다. 예를 들어, 시작 날짜와 종료 날짜가 있는 “이벤트”를 나타내는 모델을 만든 경우 시작 및 종료 날짜를 동일한 “행”에서 찾는 것이 직관적일 수 있습니다.

기본적으로 패널은 동일한 너비의 열로 나뉘지만, FieldRowPanel의 각 자식 패널에 col* 클래스 이름을 추가하여 재정의할 수 있습니다. Wagtail 편집 인터페이스는 그리드 시스템을 사용하여 배치됩니다. col1-col12 클래스는 FieldRowPanel의 각 자식에 적용되어 총 열 수에서 몇 개의 열을 차지하는지 정의할 수 있습니다. 그리드 항목이 12열까지 합산될 때 col3 클래스는 필드가 3열 너비 또는 4분의 1 너비로 표시되도록 합니다. col4 는 필드가 4열 너비 또는 3분의 1 너비가 되도록 합니다.

children¶: 행에 표시할 자식 패널의 list 또는 tuple

permission(선택 사항)¶: 충분한 권한이 있는 사용자에게 패널을 선택적으로 표시할 수 있습니다. 'myapp.change_blog_category' 와 같은 권한 코드 이름을 허용합니다. 로그인한 사용자에게 해당 권한이 없으면 패널은 폼에서 생략됩니다. FieldPanel.permission 과 유사합니다.

attrs(선택 사항)¶: 렌더링된 패널에 HTML 속성을 포함하는 사전을 설정할 수 있습니다. 속성에 True 또는 False 값을 할당하면 HTML5 부울 속성으로 렌더링됩니다.

HelpPanel¶

class wagtail.admin.panels.HelpPanel(content='', template='wagtailadmin/panels/help_panel.html', **kwargs)¶

A panel to display helpful information to the user.

This panel does not support the help_text parameter.

content¶: 패널에 표시되는 HTML 문자열입니다.

template¶: 전체 패널 HTML을 렌더링하는 템플릿 경로입니다.

attrs(선택 사항)¶: 렌더링된 패널에 HTML 속성을 포함하는 사전을 설정할 수 있습니다. 속성에 True 또는 False 값을 할당하면 HTML5 부울 속성으로 렌더링됩니다.

PageChooserPanel¶

class wagtail.admin.panels.PageChooserPanel(field_name, page_type=None, can_choose_root=False, **kwargs)¶

FieldPanel 도 Page 모델에 대한 ForeignKey 를 지원하지만, Page 별 사용자 지정을 허용하려면 PageChooserPanel 을 명시적으로 사용할 수 있습니다.

from wagtail.models import Page
from wagtail.admin.panels import PageChooserPanel


class BookPage(Page):
    related_page = models.ForeignKey(
        'wagtailcore.Page',
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name='+',
    )

    content_panels = Page.content_panels + [
        PageChooserPanel('related_page', 'demo.PublisherPage'),
    ]

PageChooserPanel 은 하나의 필수 인수, 즉 필드 이름을 사용합니다. 선택적으로 페이지 유형("appname.modelname" 문자열 형식)을 지정하면 선택기가 해당 유형의 페이지만 표시하도록 필터링됩니다. 페이지 유형 목록 또는 튜플을 전달하여 해당 페이지 유형 중 하나와 일치하는 페이지를 선택할 수도 있습니다.

PageChooserPanel('related_page', ['demo.PublisherPage', 'demo.AuthorPage'])

can_choose_root=True 를 전달하면 편집기가 트리의 루트를 페이지로 선택할 수 있습니다. 일반적으로 트리의 루트는 사용 가능한 페이지가 아니므로 바람직하지 않지만, 일부 특수한 경우에는 적절할 수 있습니다. 예를 들어, 자동 “관련 기사” 피드가 있는 페이지는 PageChooserPanel 을 사용하여 기사를 가져올 하위 섹션을 선택할 수 있으며, 루트는 ‘모든 곳’에 해당합니다.

FormSubmissionsPanel¶

class wagtail.contrib.forms.panels.FormSubmissionsPanel(**kwargs)¶

이 패널은 wagtail.contrib.forms.models.AbstractForm 모델을 구현하는 페이지에 대한 편집 인터페이스에 단일 읽기 전용 섹션을 추가합니다. 주어진 폼에 대한 총 제출 수와 제출 목록에 대한 빠른 링크를 포함합니다.

from wagtail.contrib.forms.models import AbstractForm
from wagtail.contrib.forms.panels import FormSubmissionsPanel

class ContactFormPage(AbstractForm):
    content_panels = [
        FormSubmissionsPanel(),
    ]

TitleFieldPanel¶

class wagtail.admin.panels.TitleFieldPanel(*args, apply_if_live=False, classname='title', placeholder=True, targets=['slug'], **kwargs)¶

Prepares the default widget attributes that are used on Page title fields. Can be used outside of pages to easily enable the slug field sync functionality.

매개변수:

apply_if_live – (optional) If True, the built in slug sync behaviour will apply irrespective of the published state. The default is False, where the slug sync will only apply when the instance is not live (or does not have a live property).
classname – (optional) A CSS class name to add to the panel’s HTML element. Default is "title".
placeholder – (optional) If a value is provided, it will be used as the field’s placeholder, if False is provided no placeholder will be shown. If True, a placeholder value of "Title*" will be used or "Page Title*" if the model is a Page model. The default is True. If a widget is provided with a placeholder, the widget’s value will be used instead.
targets – (optional) This allows you to override the default target of the field named slug on the form. Accepts a list of field names, default is ["slug"]. Note that the slugify/urlify behaviour relies on usage of the wagtail.admin.widgets.slug widget on the slug field.

페이지 제목 필드 또는 다른 모델의 기본 제목에 사용할 패널입니다. 폼의 슬러그 필드와 자동 동기화를 가능하게 하는 기본 클래스 이름, 플레이스홀더 및 위젯 속성을 제공합니다. 이러한 기본값 중 많은 부분은 생성자에 추가 인수를 전달하여 사용자 지정할 수 있습니다. 사용자 지정 위젯을 포함하여 동일한 FieldPanel 인수가 모두 지원됩니다. 자세한 내용은 패널 사용자 지정 를 참조하십시오.

패널 사용자 지정¶

패널/필드 정의에 추가 매개변수를 추가하여 Wagtail 페이지 편집 인터페이스에 필드가 표시되는 방식을 많이 제어할 수 있습니다. Wagtail의 페이지 편집 인터페이스는 Django의 관리자에서 많은 동작을 가져오므로 거기에서 다루는 많은 사용자 지정 옵션을 찾을 수 있습니다. (참조: Django 모델 필드 참조).

아이콘¶

패널 생성자에 icon 인수를 사용하여 패널 제목 옆에 표시될 아이콘을 재정의합니다. 사용 가능한 아이콘 목록은 사용 가능한 아이콘를 참조하십시오.

제목¶

패널 생성자에 heading 인수를 사용하여 패널의 제목을 설정합니다. 이는 입력의 레이블로 사용되며 콘텐츠 미니맵에 표시됩니다. FieldPanel 의 경우 설정되지 않은 경우 폼 필드의 레이블(모델 필드의 verbose_name 에서 가져옴)을 사용하여 자동으로 설정됩니다.

CSS 클래스¶

패널 생성자에 classname 인수를 사용하여 패널에 CSS 클래스를 추가합니다. 클래스는 패널의 HTML <section> 요소에 적용됩니다. 이는 패널에 추가 스타일을 추가하거나 동작을 제어하는 데 사용할 수 있습니다.

title 클래스는 입력이 더 큰 글꼴 크기와 두께로 눈에 띄게 만들 수 있습니다.

collapsed 클래스는 편집기 페이지를 제목 아래에 패널이 축소된 상태로 로드합니다.

    content_panels = [
        MultiFieldPanel(
            [
                FieldPanel('cover'),
                FieldPanel('book_file'),
                FieldPanel('publisher'),
            ],
            heading="책 필드 모음",
            classname="collapsed",
        ),
    ]

도움말 텍스트¶

패널 생성자에 help_text 인수를 사용하여 입력 위에 표시될 도움말 텍스트를 사용자 지정합니다. FieldPanel 의 경우 설정되지 않은 경우 폼 필드의 help_text(모델 필드의 help_text 에서 가져옴)를 사용하여 자동으로 설정됩니다.

플레이스홀더 텍스트¶

기본적으로 Wagtail은 필드의 레이블을 플레이스홀더 텍스트로 사용합니다. 변경하려면 FieldPanel 에 원하는 텍스트로 설정된 플레이스홀더 속성이 있는 위젯을 전달합니다. Django의 폼 위젯 또는 wagtail.admin.widgets 에서 찾을 수 있는 Wagtail의 위젯에서 위젯을 선택할 수 있습니다.

예를 들어, Book 스니펫 모델의 플레이스홀더를 사용자 지정하려면:

# models.py
from django import forms            # 기본 Django 위젯은 여기에 있습니다.
from wagtail.admin import widgets   # Wagtail의 특수 datetime 위젯을 사용하려면

class Book(models.Model):
    title = models.CharField(max_length=256)
    release_date = models.DateField()
    price = models.DecimalField(max_digits=5, decimal_places=2)

    # 별도로 만들 수 있습니다.
    title_widget = forms.TextInput(
        attrs = {
            'placeholder': '전체 제목 입력'
        }
    )
    # 필드 유형 및 원하는 효과에 맞는 올바른 위젯 사용
    date_widget = widgets.AdminDateInput(
        attrs = {
            'placeholder': 'dd-mm-yyyy'
        }
    )

    panels = [
        TitleFieldPanel('title', widget=title_widget), # 그런 다음 변수로 추가
        FieldPanel('release_date', widget=date_widget),
        FieldPanel('price', widget=forms.NumberInput(attrs={'placeholder': '출시 시 소매 가격'})) # 또는 직접 인라인
    ]

필수 필드¶

필드에 대한 입력 또는 선택기 선택을 필수로 만들려면 모델 정의에 blank=False를 추가합니다.

필드 숨기기¶

최상위 패널 정의가 없으면 모델의 각 필드에 대해 FieldPanel 이 구성됩니다. Wagtail 페이지 편집기에서 필드를 숨기려면 editable=False로 필드를 정의합니다. 필드가 패널 정의에 없으면 숨겨집니다.

권한¶

대부분의 패널은 permission kwarg를 허용하며, 패널 세트 또는 특정 패널을 권한 집합으로 제한할 수 있습니다. Wagtail에서 권한 작업에 대한 자세한 내용은 권한를 참조하십시오.

이 예시에서 ‘notes’는 모든 편집자에게 표시되고, ‘cost’ 및 ‘details’는 submit 권한이 있는 사용자에게만 표시되며, ‘budget approval’은 슈퍼유저에게만 표시됩니다. 슈퍼유저는 모든 필드에 액세스할 수 있습니다.

    content_panels = [
        FieldPanel("notes"),
        MultiFieldPanel(
            [
                FieldPanel("cost"),
                FieldPanel("details"),
            ],
            heading="예산 세부 정보",
            classname="collapsed",
            permission="submit"
        ),
        FieldPanel("budget_approval", permission="superuser"),
    ]

추가 HTML 속성¶

attrs 매개변수를 사용하여 패널의 HTML 요소에 사용자 지정 속성을 추가합니다. 이를 통해 data-* 속성과 같은 추가 속성을 지정할 수 있습니다. attrs 매개변수는 키가 속성 이름인 사전을 허용하며, True 및 False 가 HTML5 부울 속성으로 처리되는 Django의 위젯 attrs 와 동일한 방식으로 렌더링됩니다.

예를 들어, attrs 매개변수를 사용하여 Stimulus 컨트롤러를 패널에 통합할 수 있습니다.

    content_panels = [
        MultiFieldPanel(
            [
                FieldPanel('cover'),
                FieldPanel('book_file'),
                FieldPanel('publisher', attrs={'data-my-controller-target': 'myTarget'}),
            ],
            heading="책 필드 모음",
            classname="collapsed",
            attrs={'data-controller': 'my-controller'},
        ),
    ]

패널 API¶

이 문서는 Wagtail의 패널을 렌더링하는 데 사용되는 기본 Panel 및 BoundPanel 클래스에 대한 참조 API를 설명합니다. 사용 가능한 패널 유형 및 사용 방법은 내장 필드 및 선택기를 참조하십시오.

`Panel`¶

class wagtail.admin.panels.Panel(heading='', classname='', help_text='', base_form_class=None, icon='', attrs=None)¶

Defines part (or all) of the edit form interface for pages and other models within the Wagtail admin. Each model has an associated top-level panel definition (also known as an edit handler), consisting of a nested structure of Panel objects. This provides methods for obtaining a ModelForm subclass, with the field list and other parameters collated from all panels in the structure. It then handles rendering that form as HTML.

The following parameters can be used to customize how the panel is displayed. For more details, see 패널 사용자 지정.