일반 플러그인 구현 가이드

이 문서는 요청된 일반 구현 사례인 /plugin/code, /plugin/image, /plugin/file, /plugin/video, /plugin/draw, /plugin/table만 참고한다.

최소 구조

plugin/<name>/
├─ button.json       # 툴바 명령과 순서
├─ hooks.js          # 등록·submit·restore 훅
├─ plugin.js         # 선택적 UI·블록 구현
├─ plugin.css        # 선택적 스타일
├─ locales/          # 선택적 플러그인 namespace 번역
└─ upload.php        # 필요할 때만 두는 얇은 엔드포인트 래퍼

button.json은 UI 선언일 뿐 플러그인 등록이 아니다. 명령 이름은 code의 insertCodeBlock, image의 insertImage, file의 attachFile, video의 insertYouTube, table의 insertTable, draw의 insertDrawing처럼 구현의 공개 명령과 일치해야 한다.

초기화 원칙

• 같은 에디터나 블록에 두 번 바인딩되어도 이벤트가 중복되지 않게 한다.
• 전역 DOM 전체보다 전달받은 에디터 루트에서 찾는다.
• 변경 전 undo 지점을 만들고 변경 후 autosave를 호출한다.
• 런타임 컨트롤과 저장 콘텐츠를 분리한다.

저장과 복원

• code는 submit에서 코드 내용을 안전하게 정규화하고 컨트롤을 제거하며 restore에서 pre > code를 편집 블록으로 되살린다.
• image는 submit 훅으로 저장 구조를 정리하고 onContentSet에서 이미지 블록을 재초기화한다.
• file은 저장 후 손실될 수 있는 구조를 탐지해 복원한다.
• video와 draw는 원본 URL·식별 정보를 중복 가능한 최소 메타데이터로 남긴다.
• table은 편집 래퍼 .t2-table-wrapper와 저장용 .table-responsive를 구분한다. 최종 변환은 get_editor_js()가 만든 제출 계약과도 맞아야 한다.

새 플러그인은 “호스트 필터가 클래스 일부를 없애도 무엇으로 복원할 것인가”부터 정한다.

HTML과 URL 보안

• 플러그인 HTML은 setPluginHTML() 또는 sanitizePluginHTML() 경계를 사용한다.
• 문자열 연결로 사용자 HTML을 만들지 말고 DOM API와 textContent를 우선한다.
• 외부 URL은 서버에서도 t2editor_is_allowed_url()과 플러그인별 정책으로 다시 검증한다.
• iframe은 허용 도메인, sandbox, 필요한 최소 allow만 적용한다.

업로드 플러그인

브라우저 압축은 전송 최적화일 뿐 신뢰 경계가 아니다. 서버는 원본 또는 변환 결과의 MIME·시그니처·크기·픽셀 수를 다시 확인한다. CMS 이름을 직접 분기하지 말고 다음 공통 host adapter 경계를 사용한다.

T2Utils.appendHostUploadFields(formData, editor);
const uploadUrl = T2Utils.getHostUploadUrl(defaultUrl, 'file', editor);
const normalized = T2Utils.normalizeHostUploadResponse(data, 'file', editor);
T2Utils.applyHostUploadResult(normalized, editor);

등록

공개 등록 계약은 editor.lib.php이고, 10.5.0 base의 실제 기본 배열 선언은 editor.core.php에 있다. 일반 플러그인은 $T2EDITOR_PLUGINS에 이름을 넣고 $T2EDITOR_PLUGIN_PRIORITY로 로딩 순서를 지정한다. 관리자 활성 목록을 이미 사용하는 설치에서는 관리자 설정에도 반영한다. 자동 등록 manifest는 사용하지 않는다.

완료 기준

새 글·수정·복사 붙여넣기·undo/redo·autosave·제출·재편집, 모바일, 다중 인스턴스, 그누보드5·라이믹스·독립 환경을 각각 시험한다.

10.5.0 기준 변경점

플러그인 클래스는 기존 이름 추론 외에 T2Editor.registerPluginClass('my-plugin', MyPluginClass)로 명시적 등록할 수 있다. 하이픈이 포함된 디렉토리명은 반드시 실제 클래스와 등록 정보를 연결한다. 비동기 로더는 플러그인별 제한 시간과 오류 격리를 적용하므로 실패한 플러그인은 자기 버튼만 복구하고 다른 플러그인·본문 초기화를 막지 않아야 한다. 업로드·블록 삽입은 임시로 문서 끝을 사용하지 말고 공통 논리 위치 bookmark를 보존한다.