(documents_overview)=

# 문서 개요

이 페이지는 Wagtail 프로젝트에서 `'wagtail.documents'` 앱을 사용하는 기본 사항에 대한 개요를 제공합니다.

## `INSTALLED_APPS` 에 `'wagtail.documents'` 포함

`wagtail.documents` 앱을 사용하려면 Django 프로젝트 설정의 `INSTALLED_APPS` 목록에 포함해야 합니다. 다음과 같이 목록에 추가하기만 하면 됩니다.

```python
# settings.py

INSTALLED_APPS = [
    # ...
    'wagtail.documents',
    # ...
]
```

## URL 설정

다음으로 `wagtail.documents` 앱에 대한 URL을 설정해야 합니다. 이 URL을 프로젝트의 기본 urls.py 파일에 포함할 수 있습니다. 이렇게 하려면 다음 줄을 추가하십시오.

```python
# urls.py

from wagtail.documents import urls as wagtaildocs_urls

urlpatterns = [
    # ...
    path('documents/', include(wagtaildocs_urls)),
    # ...
]
```

새로 저장된 문서는 기본적으로 [참조 인덱스](managing_the_reference_index)에 저장됩니다.

## 페이지에서 문서 사용

Wagtail 페이지에 문서 파일을 포함하려면 페이지 모델에서 `FieldPanel` 을 사용할 수 있습니다.

다음은 예시입니다.

```python
# models.py

from wagtail.admin.panels import FieldPanel
from wagtail.documents import get_document_model


class YourPage(Page):
    # ...
    document = models.ForeignKey(
        get_document_model(),
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
    )

    content_panels = Page.content_panels + [
        # ...
        FieldPanel('document'),
    ]

```

이를 통해 페이지를 생성하거나 편집할 때 문서 파일을 선택하고 페이지 템플릿에서 링크할 수 있습니다.

다음은 문서 필드에 액세스하고 렌더링하는 예제 템플릿입니다.

```html+django
{% extends "base.html" %}
{% block content %}
    {% if page.document %}
        <h2>문서: {{ page.document.title }}</h2>
        <p>파일 유형: {{ page.document.file_extension }}</p>
        <a href="{{ page.document.url }}" target="_blank">문서 보기</a>
    {% else %}
        <p>이 페이지에 첨부된 문서가 없습니다.</p>
    {% endif %}
    <div>{{ page.body }}</div>
{% endblock %}
```

## `RichTextFields` 내에서 문서 사용

문서 링크는 [`RichTextField`](rich_text_field)를 사용하여 페이지에서 만들 수 있습니다. 기본적으로 Wagtail은 문서에 링크를 추가하는 기능을 포함합니다. [](rich_text_features)를 참조하십시오.

`features` 를 `RichTextField` 에 전달하여 이를 제외하거나 포함할 수 있습니다. 아래 예제에서는 문서와 기본 서식만 포함하는 `RichTextField` 를 생성합니다.

```python
# models.py
from wagtail.fields import RichTextField

class BlogPage(Page):
    # ...다른 필드
    document_footnotes = RichTextField(
        blank=True,
        features=["bold", "italic", "ol", "document-link"]
    )

    panels = [
        # ...다른 패널
        FieldPanel("document_footnotes"),
    ]
```

## `StreamField` 내에서 문서 사용

`StreamField` 는 고정된 구조를 따르지 않는 페이지에 적합한 콘텐츠 편집 모델을 제공합니다. `StreamField` 를 사용하여 문서에 링크를 추가하려면 모델에 포함하고 `DocumentChooserBlock` 도 포함하십시오.

`doc` 이라는 `StreamField` 와 필드 내에 `doc_link` 라는 `DocumentChooserBlock` 이 있는 `Page` 모델을 생성합니다.

```python
# models.py

from wagtail.fields import StreamField
from wagtail.documents.blocks import DocumentChooserBlock


class BlogPage(Page):
    # ... 다른 필드

    documents = StreamField([
            ('document', DocumentChooserBlock())
        ],
        null=True,
        blank=True,
        use_json_field=True,
    )

    panels = [
        # ... 다른 패널
        FieldPanel("documents"),
    ]
```

In `blog_page.html`, add the following block of code to display the document link in the page:

```html+django
{% for block in page.documents %}
    <a href="{{ block.value.url }}">{{ block.value.title }}</a>
{% endfor %}
```

## 문서 및 컬렉션 작업

Wagtail의 문서는 [컬렉션](https://guide.wagtail.org/en-latest/how-to-guides/manage-collections/) 내에서 구성할 수 있습니다. 컬렉션은 관련 문서를 그룹화하는 방법을 제공합니다. 컬렉션 간에 문서를 교차 연결하고 사이트의 다른 부분을 통해 액세스할 수 있습니다.

다음은 예시입니다.

```python
from wagtail.documents import get_document_model

class PageWithCollection(Page):
    collection = models.ForeignKey(
        "wagtailcore.Collection",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name='+',
        verbose_name='문서 컬렉션',
    )

    content_panels = Page.content_panels + [
        FieldPanel("collection"),
    ]

    def get_context(self, request):
        context = super().get_context(request)
        documents = get_document_model().objects.filter(collection=self.collection)
        context['documents'] = documents
        return context

```

다음은 문서 컬렉션에 액세스하고 렌더링하는 예제 템플릿입니다.

```html+django
{% extends "base.html" %}
{% load wagtailcore_tags %}

{% block content %}
    {% if documents %}
    <h3>문서:</h3>
    <ul>
        {% for document in documents %}
        <li>
            <a href="{{ document.url }}" target="_blank">{{ document.title }}</a>
        </li>
        {% endfor %}
    </ul>
    {% endif %}
{% endblock %}
```

## 문서 비공개 설정

특정 문서에 대한 액세스를 제한하려면 적절한 개인 정보 설정이 있는 컬렉션에 배치하여 비공개로 만들 수 있습니다(참조: [](image_document_permissions)).

비공개 컬렉션은 공개적으로 액세스할 수 없으며, 해당 콘텐츠는 적절한 권한이 있는 사용자만 사용할 수 있습니다.

## API 액세스

Wagtail의 문서는 `wagtail.documents.api.v2.views.DocumentsAPIViewSet` 를 통해 API로 액세스할 수 있습니다. 이를 통해 문서를 프로그래밍 방식으로 상호 작용하고, 세부 정보를 검색하고, 다양한 작업을 수행할 수 있습니다.

자세한 내용은 추가 정보 및 사용 예제를 제공하는 [API 섹션](api_v2_configure_endpoints)을 참조하십시오.