(streamfield_widget_api)=

# 폼 위젯 클라이언트 측 API

StreamField 편집 인터페이스가 폼 필드를 동적으로 생성하려면 StreamField 블록 내에서 사용되는 모든 Django 폼 위젯에 위젯이 클라이언트 측에서 렌더링되고 데이터로 채워지는 방법과 해당 필드에서 데이터를 추출하는 방법을 정의하는 JavaScript 구현이 함께 제공되어야 합니다. Wagtail은 `django.forms.widgets.Input`, `django.forms.Textarea`, `django.forms.Select` 및 `django.forms.RadioSelect` 에서 상속하는 위젯에 대해 이 구현을 제공합니다. 다른 위젯 유형 또는 사용자 지정 클라이언트 측 동작이 필요한 위젯 유형의 경우 자체 구현을 제공해야 합니다.

이 구현은 [Stimulus](extending_client_side_stimulus)에 의해 구동되거나 더 깊은 통합을 위해 telepath를 활용할 수 있습니다.

[telepath](https://wagtail.github.io/telepath/) 라이브러리는 Python 위젯 클래스와 해당 JavaScript 구현 간의 매핑을 설정하는 데 사용됩니다. 매핑을 만들려면 `wagtail.widget_adapters.WidgetAdapter` 의 서브클래스를 정의하고 `wagtail.telepath.register` 로 등록합니다.

```python
from wagtail.telepath import register
from wagtail.widget_adapters import WidgetAdapter

class FancyInputAdapter(WidgetAdapter):
    # 클라이언트 측에 등록된 것과 일치하는 식별자
    js_constructor = 'myapp.widgets.FancyInput'

    # 클라이언트 측 객체에 전달되는 인수
    def js_args(self, widget):
        return [
            # 일반적으로 위젯의 HTML 표현을 포함하는 인수
            # 및 __NAME__ 및 __ID__ 플레이스홀더로 렌더링된 레이블 ID,
            # 클라이언트 측 render() 메서드에서 사용
            widget.render('__NAME__', None, attrs={'id': '__ID__'}),
            widget.id_for_label('__ID__'),
            widget.extra_options,
        ]

    class Media:
        # 위젯 자체 미디어 외에 필요한 JS / CSS 포함;
        # 일반적으로 클라이언트 측 어댑터 정의를 포함합니다.
        js = ['myapp/js/fancy-input-adapter.js']


register(FancyInputAdapter(), FancyInput)
```

위젯 인스턴스와 연결된 JavaScript 객체는 단일 메서드를 제공해야 합니다.

```{eval-rst}
.. js:function:: render(placeholder, name, id, initialState)

   이 위젯의 복사본을 현재 페이지에 렌더링하고 필요한 초기화를 수행합니다.

   :param placeholder: 위젯의 HTML로 대체될 HTML DOM 요소입니다.
   :param name: 입력 요소의 ``name`` 속성으로 사용될 문자열입니다. 여러 입력 요소를 사용하는 위젯(및 최종 값으로 다시 정렬하기 위한 서버 측 논리가 있는 위젯)의 경우, 접두사로 처리될 수 있으며, 추가 요소는 대시로 구분됩니다. (예를 들어, ``name`` 이 ``'person-0'`` 인 경우 위젯은 ``person-0-first_name`` 및 ``person-0-surname`` 이름의 요소를 생성할 수 있으며, 폼의 다른 필드 이름과 충돌할 위험이 없습니다.)
   :param id: 입력 요소의 ``id`` 속성으로 사용될 문자열입니다. ``name`` 과 마찬가지로 추가 식별자의 접두사로 처리될 수 있습니다.
   :param initialState: 위젯을 채울 초기 데이터입니다.

위젯의 상태는 종종 폼 필드의 값과 동일하지만, 폼 제출에서 처리되는 것 이상의 추가 데이터를 포함할 수 있습니다. 예를 들어, 페이지 선택기 위젯은 페이지 ID를 포함하는 숨겨진 폼 필드와 페이지 제목을 표시하는 읽기 전용 레이블로 구성됩니다. 이 경우 페이지 ID만으로는 위젯을 렌더링하기에 충분한 정보를 제공하지 않으므로 상태는 ``id`` 및 ``title`` 항목이 있는 사전으로 정의됩니다.

``render`` 에서 반환된 값은 이 위젯 인스턴스의 데이터에 액세스할 수 있는 '바인딩된 위젯' 객체입니다. 이 객체는 다음 속성 및 메서드를 구현해야 합니다.

.. js:attribute:: idForLabel

   이 위젯을 참조하는 레이블의 ``for`` 속성으로 사용할 HTML ID 또는 적절한 HTML 요소가 없는 경우 null입니다.

.. js:function:: getValue()

   이 위젯의 제출 가능한 값(일반적으로 입력 요소의 값과 동일)을 반환합니다.

.. js:function:: getState()

   이 위젯의 내부 상태를 ``render`` 메서드의 ``initialState`` 인수로 전달하기에 적합한 값으로 반환합니다.

.. js:function:: setState(newState)

   선택 사항: 이 위젯의 내부 상태를 전달된 값으로 업데이트합니다.

.. js:function:: focus(soft)

   이 위젯에 브라우저의 포커스를 설정하여 입력 이벤트를 수신하도록 합니다. 포커스 개념이 없는 위젯은 아무것도 하지 않아야 합니다. ``soft`` 가 true인 경우, 이는 포커스 이벤트가 사용자 작업에 의해 명시적으로 트리거되지 않았음을 나타냅니다(예: 새 블록이 삽입되고 사용자의 편의를 위해 첫 번째 필드에 포커스가 맞춰질 때). 이 경우 위젯은 모달 열기와 같은 방해적인 UI 작업을 수행하지 않아야 합니다.
```