플러그인 개발 단계
- 설계: 새 플러그인을 개발하기 전에 어떤 기능을 제공할지 명확히 정의하고, 기존 플러그인과 중복되지 않는지 검토합니다.
이 문서는 2026-09-28에 v10.5.1 기준으로 다시 썼습니다. 9.x 이하 계열은 EOL이며 업데이트 대상이 아닙니다.
- 파일 생성:
plugin/your_plugin/your_plugin.js와 필요한 경우your_plugin.css, PHP 업로드 스크립트를 생성합니다. - 등록 — 코어를 고치지 않습니다: 10.0.0부터 hook으로 중앙 집중형에서 분산형으로 바뀌어 플러그인만 수정하면 됩니다.
editor.lib.php를 열어 배열에 이름을 추가하는 단계는 10.5.1에 존재하지 않습니다 — 이 파일은 43줄짜리 불변 부트스트랩이고$plugin_priority심볼이 0건입니다. - 커맨드 정의: 플러그인 클래스 안에서
handleCommand메서드를 구현하여 사용자 명령에 반응합니다. - UI 통합 —
button.json으로 등록합니다: 플러그인 폴더에button.json을 두면 코어가 읽어 버튼을 만듭니다(13개 기본 제공 플러그인이 이 방식을 씁니다).command·plugin·ariaLabel·order·icon(type/name/style) 키를 씁니다.order가 없으면$T2EDITOR_PLUGIN_PRIORITY기반 자동 정렬(우선순위 × 10)이 쓰입니다.toolbar.js나 스킨을 고치는 것은 코어 수정이므로 하지 마십시오. - 제출 훅 —
hooks.js: 제출·복원 시 실행될 훅이 필요하면 같은 폴더에hooks.js를 둡니다. 이 파일은 플러그인 본체와 달리 즉시 로드되므로(본체는 우선순위대로 지연 로드), 폼 제출 전에 훅이 준비되어야 하는 작업은 여기에 씁니다. 같은 훅이 중복 등록되면 제출 내용이 여러 번 변환되므로 한 번만 등록하십시오.
실제 등록 경로는 셋입니다. ① 코어 기본값(참고용) — editor.core.php의 if (!isset($T2EDITOR_PLUGINS)) / if (!isset($T2EDITOR_PLUGIN_PRIORITY)) 블록이 기본 목록과 기본 우선순위를 정의합니다(image0 · video1 · link2 · ai_complex3 · file/code/search4 · table5 · draw/collab/linkcard6 · meme8 · export/clipurl9). 이 배열은 읽어만 보십시오. extend/php/가 먼저 값을 정의하면 if (!isset) 가드가 그 값을 보존하므로, 손으로 고쳐도 갱신 때 지워집니다. ② 확장(권장) — extend/php/(서버사이드)·extend/js/(클라이언트)에 파일을 넣으면 코어를 건드리지 않고 확장됩니다. 파일명 알파벳순으로 자동 로드되고 README로 시작하는 파일은 제외됩니다. 업데이트 후에도 유지됩니다. 로드 시점은 extend/php가 "에디터 기본 상수 정의 직후, editor_html() 호출 전", extend/js가 "플러그인 JS 로드 완료 직후"입니다. ③ 관리자 화면(운영 중 변경) — 10.2.0부터 플러그인 순서·반응형 메뉴바·다크모드·필터·업로드 설정을 관리자 페이지에서 바꿉니다(N-02-admin-console-guide.md). 코어 하드코딩 수정이 필요 없습니다. 서드파티 배포는 확장을 권장합니다. extend/는 갱신에 지워지지 않고, plugin/<id>/에 두면 배포 범위와 라이선스 표기(플러그인은 "T2Editor 호환 플러그인"임을 명시해야 함)의 영향이 생깁니다.
수명주기와 이벤트
플러그인은 에디터 초기화 시점에 등록되고 초기화 함수가 호출됩니다. 이후 사용자 입력이나 명령에 따라 명령 핸들러가 호출되며, 필요 시 본문 설정·선택 영역 변화에 반응하는 핸들러를 구현합니다. 정확한 계약 함수명과 시점은 extend/js/가 로드되는 시점과 플러그인 클래스의 실제 시그니처를 확인한 뒤에 적으십시오 — 본 문서와 plugin-* 계열 문서가 근거 없이 열거한 메서드명이 실제 코드에 없는 사례가 이미 있습니다(plugin-ai.md 참고). [확인 필요] — v10.5.1 플러그인 라이프사이클 계약의 정본 함수명·시점.
테스트와 배포
개발한 플러그인은 다양한 브라우저와 화면 크기에서 테스트해야 합니다. 오류가 없고 성능이 만족스럽다면, 문서 작성 규칙에 따라 설명서를 작성하고 내부 배포 또는 오픈 소스로 공개할 수 있습니다.
플러그인 설계 원칙
좋은 플러그인은 기능이 작더라도 책임이 선명해야 합니다. 툴바 버튼 표시, 사용자 입력 수집, 콘텐츠 삽입, 서버 통신, 스타일 처리가 한 파일 안에 뒤섞여 있으면 유지보수가 급격히 어려워집니다. 가능하면 버튼 트리거와 콘텐츠 처리 로직을 분리하고, 서버 의존 기능은 별도 엔드포인트 문서와 함께 관리하세요.
역호환성 전략
플러그인을 배포할 때는 최소 지원 버전을 문서 상단에 분명히 적으십시오. editor.lib.php에는 플러그인 등록 규칙이 없습니다(10.5.1에서 43줄 부트스트랩). 지켜야 할 계약은 ① 파일명 규칙 — 버튼 스크립트·스타일은 plugin/<id>/<id>.js·plugin/<id>/<id>.css, 등록 파일은 button.json·hooks.js ② 배포 시 "T2Editor 호환 플러그인"임을 명시하고 공식 제품으로 오인될 수 있는 표현을 쓰지 말 것(07-license-guide.md) ③ 로딩 실패해도 다른 플러그인과 에디터 본문이 계속 써질 수 있어야 할 것(10.5.0의 오류 격리) ④ 낮은 판본을 쓰는 사이트가 많다면 새 플러그인이 요구하는 코어 이벤트나 CSS 클래스가 실제로 존재하는지 먼저 확인할 것.
버전 경고를 서버에서 강제하는 장치도 있습니다. 10.5.0부터 서드파티 설치는 매니페스트의 지원 기준 버전(t2editor_min)이 현재 메이저 버전과 다르면 경고를 표시하고, 확인값을 서버에서 검증해 확인 정보가 없는 직접 설치 요청이 그대로 적용되지 않게 합니다. 특히 기존 사이트가 낮은 버전의 T2Editor를 쓰고 있다면, 새 플러그인이 요구하는 코어 이벤트나 CSS 클래스가 실제로 존재하는지 먼저 확인해야 합니다.
참고 자료
- DSclub T2Editor 서비스 페이지: https://dsclub.kr/service/editor
- 판본별 변경 내역(현행): https://dsclub.kr/service/editor
- 참고 이력: SIR T2Editor 8.1.2 소개 글 https://sir.kr/boards/g5_plugin/15016 은 2026-03 판본 자료입니다.
- 코어 파일 구조: core-editor-lib-php.md · core-core-js.md
- 실제 AI 플러그인 사례: plugin-ai.md
- 10.0.0의 아키텍처 변경: N-03-migration-v9-to-v10.md