JavaScript 훅

서드파티 JS 라이브러리(Chart.js, Mapbox, CodeMirror 등)를 컴포넌트에 붙이는 장치다. Phoenix LiveView의 훅과 같은 모양이다.

빠른 시작#

1. 훅을 정의한다#

window.wireview.hooks.ChartHook = {
  mounted() {
    // 엘리먼트가 페이지에 들어왔을 때
    const config = JSON.parse(this.el.dataset.config);
    this.chart = new Chart(this.el, config);
  },

  updated() {
    // DOM morph가 끝난 뒤
    this.chart.update();
  },

  destroyed() {
    // 엘리먼트가 사라질 때
    this.chart.destroy();
  }
};

2. 템플릿에서 쓴다#

<div wire-hook="ChartHook" data-config='{"type": "line", "data": {...}}'>
</div>

훅 파일을 어디에 두나#

앱의 static 아래 hooks/에 둔다. 프로젝트가 <script> 태그를 쓸 필요가 없다.

myapp/
└── static/
    └── myapp/          ← 앱 라벨 (Django의 정적 파일 네임스페이스)
        └── hooks/      ← wireview의 규약
            └── chart.js

{% wireview_header %}가 설치된 앱 전부에서 이 디렉터리를 찾아 defer로 싣는다. 파일은 자기 훅 이름을 자기가 쓴다.

// myapp/static/myapp/hooks/chart.js
window.wireview.hooks.Chart = {
  mounted() { ... },
};

왜 페이지마다 전부 싣나#

수집은 페이지가 아니라 프로젝트 단위다. 그 페이지가 쓰는 훅만 실으면 boost 내비게이션에서 깨진다 — 경계 안에서 이동할 때 wireview는 body만 갈아 끼우므로 목적지 문서의 <head>에 있던 <script>는 실행되지 않는다. 첫 로드에서는 되고 이동해서 들어가면 안 되는 결함이 된다.

부수 효과로 수집이 요청과 무관해진다 — 기동 때 한 번 정해진다.

순서는 보장된다#

defer 스크립트는 문서 순서대로 실행되므로 훅 파일이 도는 시점에 window.wireview는 이미 있다. 그리고 wireview는 defer 스크립트가 전부 실행된 뒤에야 컴포넌트를 join한다 — 훅 파일이 늦게 도착해도 첫 렌더 때 훅이 자리에 있다는 뜻이다.

이 보장이 필요한 이유는 실패가 조용하기 때문이다. 등록되지 않은 훅은 오류를 내지 않고 콘솔 경고 한 줄(Hook "X" not registered)만 남기며, 컴포넌트는 정상으로 보인다. manage.py check의 wireview.W011이 그 짝을 먼저 잡는다 — 템플릿이 부르는 이름을 등록하는 파일이 없을 때.

직접 싣고 싶다면#

번들러가 있는 프로젝트는 수집을 끄고 같은 파일들을 자기 번들에 넣으면 된다.

WIREVIEW = {"COLLECT_HOOKS": False}

끄면 wireview.W011도 함께 조용해진다 — 비교할 대상이 없기 때문이다. 직접 실을 때도 번들이 wireview보다 먼저 실행되지 않게 해야 한다. 인라인 <script>는 defer가 안 되므로 window.wireview가 없는 시점에 돌아 실패한다.

동작하는 예제는 examples/hooks/에 있다.

훅 수명주기#

콜백 언제 쓰임새
mounted() 엘리먼트가 들어오고 첫 렌더가 끝난 뒤 라이브러리 초기화
beforeUpdate() DOM morph 직전 (동기) 스크롤 위치·선택 영역 저장
updated() DOM morph가 끝난 뒤 상태 복원, 라이브러리 갱신
destroyed() 엘리먼트가 DOM에서 빠질 때. 컴포넌트가 페이지를 떠날 때(부모가 그리지 않음, boost 이동)도 뿌리에 단 훅까지 모두 자원 정리
disconnected() WebSocket이 끊겼을 때 오프라인 표시
reconnected() WebSocket이 다시 붙고 컴포넌트가 다시 join할 때. 같은 훅 인스턴스다 데이터 새로고침
navigated() boost 이동이 끝난 뒤, 이동 전부터 있었고 이동 뒤에도 남은 훅에게 한 번. 주로 sticky 컴포넌트의 훅 새 <body>에 페이지 전체 효과 다시 걸기 (boost)

훅은 자기를 감싼 가장 가까운 컴포넌트의 것이다. 중첩된 컴포넌트 안의 훅은 바깥 컴포넌트가 아니라 안쪽 컴포넌트의 push_event를 받는다. 렌더가 엘리먼트를 옮기기만 하면(id가 같은 목록 항목의 순서가 바뀜) 훅은 그대로 살아 있고 destroyed()도 mounted()도 다시 불리지 않는다.

부모의 렌더가 새로 그린 컴포넌트(LiveComponent, 또는 {% if %}가 다시 그린 {% component %})의 훅도 그 렌더가 패치될 때 마운트된다. 그렇게 그려진 {% component %}는 그때 페이지가 join한다 — 그 joined()가 돌고, 그 안의 wire-viewport-*는 그 컴포넌트의 것으로 관찰된다. 그 LiveComponent가 joined()에서 보낸 push_event는 렌더보다 먼저 패치를 기다리지 않고 도착하지만, 페이지는 그 요소가 들어올 다음 프레임까지 붙들었다가 마운트된 훅에 전한다(전에는 훅이 아예 마운트되지 않았고 이벤트는 아무 데도 닿지 않았다). 이미 화면에 있는 컴포넌트의 핸들러가 렌더로 새 훅을 그리고 같은 핸들러에서 그 훅에 push_event를 보내도 마찬가지다 — 그 컴포넌트에 예약된 패치가 있으면 이벤트는 그 패치 뒤에 간다. 부모의 패치가 이미 join된 중첩 컴포넌트(LiveComponent 포함) 안에 그린 훅은 그 중첩 컴포넌트의 것으로 마운트되고, 그 패치가 지나간 중첩 컴포넌트의 훅도 beforeUpdate()·updated()를 받는다.

훅 컨텍스트#

콜백 안의 this가 주는 것.

속성 타입 뜻
this.el HTMLElement wire-hook 속성이 붙은 DOM 엘리먼트
메서드 뜻
this.pushEvent(event, payload, callback) 서버로 이벤트를 보낸다. 콜백이 없으면 응답의 Promise를 돌려준다
this.handleEvent(event, callback) 서버가 보내는 이벤트를 받는다. 핸들러를 떼는 함수를 돌려준다

정의 객체에서는 함수만 this로 복사된다. 위 이름(pushEvent, handleEvent)과 __로 시작하는 이름은 wireview의 것이다 — 같은 이름으로 메서드를 쓰면 내장 동작을 덮는다. this.__hookId 같은 __ 멤버는 내부이고 바뀔 수 있다.

서버와 주고받기#

서버로 보내기 (pushEvent)#

window.wireview.hooks.InfiniteScroll = {
  mounted() {
    this.observer = new IntersectionObserver(entries => {
      if (entries[0].isIntersecting) {
        this.loadMore();
      }
    });
    this.observer.observe(this.el.querySelector('.sentinel'));
  },

  loadMore() {
    // 콜백과 함께 서버로 보낸다
    this.pushEvent("load_more", { page: this.page }, (response) => {
      console.log("Server response:", response);
      if (response.hasMore) {
        this.page++;
      } else {
        this.observer.disconnect();
      }
    });
    this.page = (this.page || 1) + 1;
  },

  destroyed() {
    this.observer.disconnect();
  }
};

콜백은 그 이벤트의 렌더가 DOM에 반영된 뒤에 돈다(#223). 서버는 handle_hook_event()가 바꾼 상태의 렌더를 먼저 보내고 응답을 그 뒤에 보내며, 페이지는 그 렌더가 예약한 패치가 끝날 때까지 응답을 붙잡는다 (이벤트가 LiveComponent만 바꿨으면 그 LiveComponent의 패치). 그래서 콜백에서 로딩 표시를 끄면 새 값이 이미 화면에 있다. 한 프레임 안에 렌더가 여럿 오면 하나의 패치로 접히므로, 콜백이 보는 DOM은 적어도 자기 이벤트의 렌더까지이고 뒤의 이벤트 것이 함께 보일 수 있다. Phoenix LiveView도 diff를 적용한 뒤 reply 콜백을 부른다.

Promise로 받기#

콜백을 넘기지 않으면 pushEvent는 응답의 Promise를 돌려준다(#222). 콜백과 같은 때 — 렌더가 DOM에 반영된 뒤 — 풀린다.

window.wireview.hooks.SaveButton = {
  mounted() {
    this.el.addEventListener("click", async () => {
      this.el.classList.add("saving");
      try {
        const { saved } = await this.pushEvent("save", { draft: this.el.dataset.draft });
        // 렌더가 이미 화면에 있다
      } catch (error) {
        // error.reason: "disconnected" | "destroyed" | "error" | "gone"
      } finally {
        this.el.classList.remove("saving");
      }
    });
  },
};

응답이 오지 않을 것이 확실해지면 Promise는 WireviewPushError로 거절된다. error.reason이 이유다.

reason 언제
disconnected 보낼 때 연결이 끊겨 있었다, 또는 응답 전에 끊겼다. 끊긴 동안의 이벤트는 버려지고(#97) 재연결은 새 인스턴스에 join하므로 그 응답은 없다
destroyed 훅이나 그 컴포넌트가 페이지를 떠났다
error 서버 코드가 그 컴포넌트에서 예외를 던져 인스턴스를 버렸다. 페이지는 다시 join하고, 그 전에 보낸 이벤트는 처리되지 않는다
gone 서버에 그 id의 인스턴스가 없다 — join이 실패했거나, 그린 쪽이 더는 그리지 않아 은퇴했다

응답이 일단 도착하면 그 뒤의 일(다른 이벤트의 error, 연결 끊김)은 그것을 거절로 바꾸지 않는다 — 서버가 이미 처리했다. handle_hook_event()가 push_event로 보낸 이벤트는 그 응답 뒤에 온다. 세션이 이벤트를 다 처리한 다음에 보낸다. 기다리지 않고 보내기만 해도 된다 — 아무도 받지 않은 거절은 "unhandled rejection"으로 보고되지 않는다. 콜백 방식은 이전과 같다. 실패를 듣지 않고, 훅이 떠난 뒤 온 응답도 받는다(컴포넌트가 떠나면 받지 않는다).

서버에서 받기 (handleEvent)#

window.wireview.hooks.Notification = {
  mounted() {
    // 서버가 push하는 이벤트의 핸들러를 등록한다
    this.handleEvent("show_toast", ({ message, type }) => {
      this.showToast(message, type);
    });

    this.handleEvent("highlight", ({ color }) => {
      this.el.style.backgroundColor = color;
      setTimeout(() => {
        this.el.style.backgroundColor = '';
      }, 1000);
    });
  },

  showToast(message, type) {
    // 토스트 구현
  }
};

handleEvent는 그 핸들러를 떼는 함수를 돌려준다(#222). 훅이 떠나면 핸들러는 모두 함께 지워지므로, 훅이 살아 있는 동안 듣기를 멈출 때만 쓴다. 같은 함수를 두 번 등록했으면 그 반환값마다 하나씩 뗀다.

const off = this.handleEvent("progress", ({ percent }) => this.render(percent));
// ...
off();

서버 쪽 핸들러#

from wireview import Component


class Dashboard(Component):
    class Meta:
        template_name = "dashboard.html"

    items: list = []
    page: int = 1

    async def handle_hook_event(self, hook_id: str, event: str, payload: dict):
        """Handle events from JavaScript hooks.

        Args:
            hook_id: Unique identifier of the hook instance
            event: Event name sent by the hook
            payload: Event data from the hook

        Returns:
            Response data sent to the hook's callback (or None)
        """
        if event == "load_more":
            page = payload.get("page", 1)
            new_items = await self._fetch_items(page)
            self.items.extend(new_items)

            return {
                "hasMore": len(new_items) == 20,
                "count": len(new_items)
            }

        return None

    async def _notify_user(self, message: str):
        """Push an event to every hook in this component (a helper, so ``_``)."""
        await self.push_event("show_toast", {
            "message": message,
            "type": "success"
        })

    async def _highlight_item(self, hook_id: str):
        """Push an event to one specific hook."""
        await self.push_event(
            "highlight",
            {"color": "yellow"},
            hook_id=hook_id
        )

렌더가 건드리지 않게 (wire-update="ignore")#

훅이나 서드파티 위젯이 엘리먼트를 바꿔도, 그 컴포넌트가 다시 렌더되면 morph가 템플릿 모양으로 되돌린다. updated()에서 다시 입히면 대부분 가려지지만, 재연결 때처럼 훅이 늦게 마운트되는 사이에는 틈이 보인다. wire-update="ignore"를 단 엘리먼트는 첫 렌더 뒤로 어떤 렌더도 건드리지 않는다. 속성, 자식, 텍스트 모두다. Phoenix의 phx-update="ignore"는 data-* 속성을 서버 값으로 병합하지만, wireview는 그 속성까지 보존한다. 서버가 보낸 새 데이터를 무시된 요소의 dataset에서 읽으려 하지 않는다 — 서버 상태를 넘겨받는 외부 위젯은 섬으로 둔다. 섬은 props를 바깥 요소에 싣고 안쪽만 지킨다.

<div wire-hook="Banner" wire-update="ignore" hidden></div>

서버는 그 자리를 모른 채 계속 렌더하고 diff도 보낸다. 브라우저가 그 부분만 적용하지 않는다. 그래서 그 안에 서버가 바꿔야 하는 값을 두지 않는다. 엘리먼트가 템플릿에서 빠지면({% if %}) 페이지에서도 빠진다.

그 안에 {% component %}를 그리면 id를 준다. id 없이 그린 컴포넌트는 그린 쪽이 렌더할 때마다 새 인스턴스이고, 서버는 페이지가 붙든 옛 것을 그 렌더와 함께 은퇴시킨다(#204). 그 요소의 다음 이벤트는 옛 인스턴스가 남아 있으면 그 핸들러를 돌리되 그 렌더는 화면에 오지 않고, 남아 있지 않으면 핸들러 없이 답받는다(gone). 옛 인스턴스는 은퇴하고 10초가 지난 뒤 끝나는 첫 렌더가 정리한다 — 렌더가 없으면 연결의 끝까지 남는다. 어느 쪽이든 로딩 표시가 풀리고, 페이지가 그 요소를 그 상태로 다시 join한다 — 옛 인스턴스의 leaving()과 새 인스턴스의 joined()가 돈다. id를 주면 매 렌더가 같은 인스턴스를 그리므로 그 요소가 계속 답한다.

한 엘리먼트에 훅 여러 개#

이름을 공백으로 나열한다.

<div wire-hook="Sortable Draggable Tooltip">
  <!-- 내용 -->
</div>

각 훅은 자기 인스턴스와 수명주기를 갖는다.

예제#

Chart.js#

window.wireview.hooks.Chart = {
  mounted() {
    const config = JSON.parse(this.el.dataset.config);
    this.chart = new Chart(this.el, config);

    // 서버가 보내는 데이터 갱신을 받는다
    this.handleEvent("update_data", ({ datasets }) => {
      this.chart.data.datasets = datasets;
      this.chart.update();
    });
  },

  beforeUpdate() {
    // morph 전에 차트 상태를 저장한다
    this.chartState = {
      animation: this.chart.options.animation
    };
  },

  updated() {
    // morph 후에 애니메이션을 복원한다
    this.chart.options.animation = this.chartState.animation;
  },

  destroyed() {
    this.chart.destroy();
  }
};

CodeMirror#

window.wireview.hooks.CodeEditor = {
  mounted() {
    this.editor = CodeMirror(this.el, {
      mode: this.el.dataset.mode || "javascript",
      lineNumbers: true
    });

    // 변경을 디바운스해서 서버로 보낸다
    let timeout;
    this.editor.on("change", () => {
      clearTimeout(timeout);
      timeout = setTimeout(() => {
        this.pushEvent("content_changed", {
          content: this.editor.getValue()
        });
      }, 300);
    });

    // 서버가 보내는 내용을 받는다
    this.handleEvent("set_content", ({ content }) => {
      this.editor.setValue(content);
    });
  },

  destroyed() {
    this.editor.toTextArea();
  }
};

스크롤 위치 보존#

window.wireview.hooks.PreserveScroll = {
  beforeUpdate() {
    // morph 전에 저장
    this.scrollTop = this.el.scrollTop;
  },

  updated() {
    // morph 후에 복원
    this.el.scrollTop = this.scrollTop;
  }
};

오프라인 표시#

window.wireview.hooks.ConnectionStatus = {
  mounted() {
    this.updateStatus(true);
  },

  disconnected() {
    this.updateStatus(false);
  },

  reconnected() {
    this.updateStatus(true);
  },

  updateStatus(connected) {
    this.el.classList.toggle('connected', connected);
    this.el.classList.toggle('disconnected', !connected);
    this.el.textContent = connected ? '연결됨' : '다시 연결하는 중...';
  }
};

권장 사항#

  1. destroyed()에서 반드시 정리한다. observer 해제, 라이브러리 인스턴스 파괴, 이벤트 리스너 제거.
  2. 상태 보존은 beforeUpdate()에서. 스크롤 위치·포커스·선택 영역을 morph 전에 저장한다.
  3. 초기화는 mounted()에서. 엘리먼트가 페이지에 올라오기 전에 초기화하지 않는다.
  4. 재연결을 다룬다. 끊긴 동안 바뀌었을 데이터를 reconnected()에서 새로 읽는다. 끊긴 동안의 pushEvent는 버려지므로(#97) 서버가 꼭 알아야 하는 것은 reconnected()에서 다시 보낸다.
  5. 폴링 대신 handleEvent()를 쓴다. 데이터가 바뀌면 서버가 밀어 준다.
  6. 훅 하나는 한 가지만 한다. 필요하면 한 엘리먼트에 여러 개를 붙인다.

API#

Component.handle_hook_event()#

async def handle_hook_event(
    self,
    hook_id: str,
    event: str,
    payload: dict[str, Any],
) -> Any: ...

클라이언트 훅이 pushEvent()로 보낸 이벤트를 받는다.

  • hook_id — 훅 인스턴스의 고유 식별자
  • event — 훅이 보낸 이벤트 이름
  • payload — 훅이 보낸 데이터
  • 반환 — 훅의 콜백으로 돌아갈 응답 데이터 (없으면 None)

Component.push_event()#

async def push_event(
    self,
    event: str,
    payload: dict[str, Any] | None = None,
    hook_id: str | None = None,
) -> None: ...

클라이언트 훅으로 이벤트를 보낸다.

  • event — 보낼 이벤트 이름
  • payload — 데이터 (기본: 빈 dict)
  • hook_id — 특정 훅 인스턴스만 (None이면 전체)

DOM morph 콜백#

wireview.dom.onBeforeElUpdated()#

갱신 중 엘리먼트가 morph되기 직전에 실행되는 콜백을 더한다. 서버 렌더 결과가 덮어써 버릴 클라이언트 쪽 속성이나 상태를 지키는 데 쓴다. 여러 번 부르면 콜백이 모두 더해져 더한 순서대로 돌고, 돌려받은 함수를 부르면 그 콜백만 빠진다.

const remove = wireview.dom.onBeforeElUpdated((fromEl, toEl) => {
  // fromEl: 지금 DOM에 있는 엘리먼트
  // toEl: 그것을 대체할 새 엘리먼트
});
remove();  // 더 이상 필요 없을 때

JS가 붙인 속성 지키기

// data-js-* 속성을 보존한다
wireview.dom.onBeforeElUpdated((fromEl, toEl) => {
  for (const attr of fromEl.attributes) {
    if (attr.name.startsWith('data-js-')) {
      toEl.setAttribute(attr.name, attr.value);
    }
  }
});

Alpine.js 상태 보존

wireview.dom.onBeforeElUpdated((fromEl, toEl) => {
  if (fromEl._x_dataStack) {
    window.Alpine.clone(fromEl, toEl);
  }
});

CSS 트랜지션 유지

wireview.dom.onBeforeElUpdated((fromEl, toEl) => {
  if (fromEl.hasAttribute('data-transitioning')) {
    toEl.setAttribute('data-transitioning', fromEl.getAttribute('data-transitioning'));
  }
});

Phoenix LiveView 대응#

기능 Phoenix LiveView django-wireview
설정 위치 LiveSocket 생성자 옵션 wireview.dom.onBeforeElUpdated()
콜백 시그니처 (fromEl, toEl) (fromEl, toEl)
반환값 무시 무시
호출 대상 모든 노드 엘리먼트 노드만

Phoenix LiveView와 다른 점#

Phoenix 1.2.12 훅 API와 비교하면, 수명주기 콜백과 el·pushEvent·handleEvent는 있지만 컨텍스트의 전체 API가 같지는 않다.

  • pushEvent는 콜백을 받거나, 콜백 없이 부르면 응답의 Promise를 돌려준다(Promise로 받기). 콜백이 받는 것은 응답 하나이고 Phoenix처럼 ref를 함께 받지 않는다. 응답이 오지 않을 때 Promise는 거절되지만 콜백은 불리지 않는다. 다른 컴포넌트를 겨냥하는 pushEventTo는 없다.
  • handleEvent는 ref 대신 핸들러를 떼는 함수를 돌려주고, removeHandleEvent는 없다. 남은 핸들러는 훅 파괴 때 함께 지워진다.
  • 훅의 js()·liveSocket·upload()·uploadTo()는 없다. 공개 전역 API인 wireview.exec(element, commands)와 wireview.addFiles(element, name, files)를 사용한다. 전자는 wireview 명령 배열을 받으며 Phoenix의 인코딩과 호환되지 않는다.
  • push_event는 해당 컴포넌트의 훅에 전달한다. Phoenix처럼 모든 서버 이벤트를 window 이벤트로도 내보내거나, dispatch: :before로 패치 전 실행을 선택하는 옵션은 없다.
  • wireview.dom.onBeforeElUpdated는 지원한다. 그러나 LiveSocket 생성자의 metadata·연결 params· bindingPrefix·사용자 uploaders를 받는 공통 설정 API는 없다.
  • 훅 등록은 함수 멤버를 가진 객체 방식이다. Phoenix의 ViewHook 클래스, 컴포넌트 밖 정적 페이지의 훅, HEEx ColocatedHook·ColocatedJS 추출은 지원하지 않는다. static/<app>/hooks/ 자동 수집은 외부 파일 로딩 규약이다.

Phoenix 1.2.12의 훅 beforeUpdate(toEl)와 달리 wireview는 인자 없이 컴포넌트의 훅들을 호출한다. 요소별 다음 DOM은 전역 onBeforeElUpdated에서 볼 수 있다. 같은 요소의 wire-hook 이름을 바꾸어도 기존 훅을 새 정의로 교체하는 규약은 없다.

연결 재시도 설정은 Django 설정으로 제공하지만 LiveSocket의 수동 connect/disconnect·getSocket, 주입 가능한 storage/logger·로딩 지연·IME 전송 옵션을 한 객체에서 제어하는 API는 없다. DOM 설정도 onBeforeElUpdated만 공개하며 onDocumentPatch·onPatchStart/End·onNodeAdded· jsQuerySelectorAll에 해당하는 등록 API는 없다.