WordPress 플러그인 사용자 가이드
이 가이드는 4개 섹션으로 구성됩니다. §1 빠른 시작으로 첫 단축코드를 게시하는 데 필요한 모든 단계를 스크린샷과 함께 따라갈 수 있고, §2~§4는 깊이 있게 작성하거나 문제를 해결할 때 참고하세요.
1. 빠른 시작
WordPress 관리자에서 3Min API → + New 메뉴를 열면 단축코드 빌더가 나타납니다. 위에서 아래로 4단계를 따라가면 단축코드 하나가 완성됩니다.
처음이라면 3Min API 둘러보기에서 엔드포인트 + API 키 발급 방법을 확인하거나, ChatGPT Apps에서 "3Min API"를 검색해 대화로 시작할 수 있습니다.
1.1 엔드포인트 입력 + 테스트
- 엔드포인트 ID + API 키를 붙여넣고 HTTP 메서드(Get Record / Get List / POST)를 선택합니다.
- Test endpoint 버튼을 누르면 실제 요청이 전송되고, 응답이 그 자리에서 인라인으로 표시됩니다.
- 응답이 정상이면 자동으로 다음 카드들이 채워집니다 (변수, 템플릿).
POST 엔드포인트는 빌더에서 미리 테스트되지 않습니다. 단축코드를 저장하고 페이지에 붙여넣은 뒤 폼을 제출해 확인하세요.
1.2 변수 확인
테스트 응답을 분석해 사용 가능한 템플릿 변수가 칩 형태로 표시됩니다. 대표적인 변수:
{{response}}— 응답 전체{{response.payload}}— 사용자 레코드 본문{{response.payload.title}},{{response.id}}같은 "점 표기법"으로 깊이 접근
이 변수들을 다음 단계의 HTML/CSS에 그대로 삽입하면 안전하게 처리됩니다.
1.3 템플릿 선택 + AI 디자인
- 메서드별 템플릿을 선택하면 HTML/CSS·JavaScript 패널이 자동으로 채워집니다.
- 상단 Copy AI prompt 버튼을 누르면, 선택한 템플릿 코드 + 플러그인 작성 규칙 + 자동 감지된 변수가 시스템 프롬프트로 묶여 클립보드에 복사됩니다.
- ChatGPT / Claude / Gemini 같은 LLM에 그대로 붙여넣고 "더 미니멀하게", "다크모드 기본", "별점도 보여줘" 같은 자연어로 디자인을 다듬으세요.
- 결과를 HTML/CSS 패널에 (필요시 JavaScript 패널에도) 붙여넣고 우측 라이브 프리뷰로 확인합니다.
JavaScript 패널은 옵션입니다. JavaScript는 사이트 관리자만 저장할 수 있습니다.
1.4 저장 + 페이지에 게시
- 단축코드 이름을 입력합니다 (첫 저장 후 변경 불가).
- Save를 누르면 다음 형식의 단축코드가 생성됩니다:
[3minapi name="your-snippet-name"] - 이 한 줄을 어떤 글·페이지·위젯·블록에든 붙여넣으면 그 자리에 작성한 UI가 렌더됩니다.
같은 단축코드를 여러 페이지에서 재사용할 수 있고, 한 페이지에 서로 다른 단축코드 여러 개를 둘 수도 있습니다 — 각각 독립적으로 렌더됩니다.
2. HTML/CSS 가이드
HTML/CSS는 저장할 때 보안을 위해 일부 코드가 자동으로 제거됩니다. 안전하게 사용할 수 있는 태그·속성·CSS를 아래에서 확인하세요.
2.1 렌더링 방식
- Get Record: 페이지가 열릴 때 서버에서 API를 호출하고, 응답을 포함한 HTML/CSS가 렌더된 뒤 JavaScript 코드가 실행됩니다.
- Get List: Get Record와 동일한 흐름. 단, 첫 페이지만 서버에서 렌더되고, 다음 페이지부터는 JavaScript의
threeminApi.fetch()로 가져옵니다("Load more" 버튼 등). - POST: 폼 HTML/CSS가 먼저 렌더되고, 사용자가 폼을 제출할 때 API 호출과 JavaScript 핸들러가 동작합니다. (JavaScript 코드 자체는 렌더 직후 등록되어 제출 시점에 작동하도록 준비됩니다.)
- 모든 단축코드는 렌더 시 자동으로
<div class="threemin-api-rendered" data-3minapi-preset="<snippet>">…</div>로 감싸집니다. JavaScript에서 root를 찾을 때 이 속성을 사용하세요 — 직접 HTML에data-3minapi-preset을 추가하지 마세요.
2.2 허용되는 태그·CSS
| 분류 | 허용 |
|---|---|
| 텍스트 태그 | h1–h6, p, div, span, blockquote, ul / ol / li, table 계열, a, img, figure, figcaption |
| 폼 태그 | form, input, button, textarea, select, option, fieldset, legend, label |
| 스타일링 | <style> 블록 |
| CSS | 색상 / 타이포그래피, 박스 모델, 레이아웃(Flexbox + Grid), 모션(transform, transition, animation, filter), 인터랙션(pointer-events, cursor, user-select) |
| 가시성 토글 | hidden 속성, <style>의 display:none 클래스, 인라인 style="display:none" |
| 저장 시 제거 | <script> 태그, PHP 태그(<?php, <?=), 인라인 이벤트 핸들러(onclick, onerror, …), javascript: URL |
일부 인라인 style 속성은 저장 시 제거됩니다 — CSS 규칙은 <style> 블록 안에 두세요.
2.3 권장 패턴
- Semantic HTML5 — 헤딩, 리스트, 표는 표 계열 태그로, 이미지+캡션은
figure+figcaption. - 단축코드 이름을 접두사로 가진 BEM 클래스 —
.product-card,.product-card__title같은 식. 같은 단축코드가 한 페이지에 여러 번 와도 충돌하지 않습니다. - 단축코드당
<style>블록 하나. - 모던 레이아웃 — Flex / Grid /
gap모두 허용. - 반응형 단위 —
rem,%,vw,vh. - 이미지 lazy-load —
<img loading="lazy">. - 접근성 —
aria-label,aria-hidden,role="..."모두 저장 후에도 그대로 동작합니다. - HTML5 폼 검증 —
required,min,max,pattern,type=email/number/date/...그대로 적용됩니다.
2.4 피해야 할 패턴
- ⚠️ 폼 계열 태그의 사용자 정의
data-3minapi-*(가장 흔한 무동작 원인 — 에러도 안 뜸).<button>/<input>/<textarea>/<form>/<select>/<fieldset>에 화이트리스트에 없는data-*속성을 붙이면 저장 시 조용히 제거되고, 이후 JS의querySelector('[data-...]')는null을 반환하는데 콘솔 에러도 없습니다. 버튼·입력 같은 인터랙션 요소는 BEM 클래스로 쓰세요.<div>/<span>/<li>같은 일반 태그는 어떤data-*든 통과합니다. - 셀렉터는 HTML과 정확히 일치해야 합니다 — 한 글자 오타도 에러 없이 무동작.
<div role="button">대신<button>사용.- 레이아웃을 inline
style="..."로 잡지 마세요 —<style>블록 안에 두세요. id로 스타일링하지 마세요 — 같은 단축코드가 페이지에 두 번 들어가면 id가 충돌합니다. 클래스 사용.- 최상위 컨테이너에 고정
px너비 금지 — 반응형이 깨집니다.
2.5 메서드별 작성 팁
2.5.1 Get Record — API 필드를 HTML에 꽂기
- Test endpoint 실행 후 Variables 카드에 두 칩이 표시됩니다:
{{response}}(응답 전체),{{response.payload}}(사용자 레코드). - 점 표기법으로 하위 접근:
{{response.payload.title}},{{response.id}},{{response.payload.author.name}}. - 변수 값은 자동으로 안전하게 처리됩니다.
- 보기/편집 전환 속성 (폼 계열 태그용 화이트리스트):
data-3minapi-view-mode,data-3minapi-edit-mode,data-3minapi-edit-toggle,data-3minapi-save,data-3minapi-cancel,data-3minapi-delete. 편집 폼 내부 input은 평범한name="..."을 사용.
2.5.2 Get List — 동적 아이템 렌더링
- HTML에는 빈 컨테이너만 두고, JavaScript가 런타임에 각 행을 추가합니다. 하드코딩된 행은 게시 페이지에서 중복됩니다.
- DOM 후크 화이트리스트:
<ul data-3minapi-feed-list>(아이템 컨테이너),<button data-3minapi-feed-more>(Load more),[data-3minapi-feed-empty](비어 있는 상태). - 변수 칩:
{{response.data}}(배열 — 템플릿에서는 빈 값으로 치환, 참고용 표시),{{response.pagination.next_cursor}},{{response.data.0.payload.x}}(인덱스로 단일 레코드 접근, 정적으로 표시되는 영역용). - 다중 행 렌더링 + 페이지네이션은 JS 패널에서 처리합니다.
2.5.3 POST — 폼을 엔드포인트에 연결
- 엔드포인트의 body 필드 정의를 3Min API 대시보드에서 확인하세요.
- 각 input의
name속성을 body 필드명과 정확히 일치시키세요. - 자동 제출 바인딩:
[data-3minapi-preset]내부에<form data-3minapi-form>을 두면 런타임이 submit 이벤트를 가로챕니다. 기본 POST 템플릿에는 이미 들어 있습니다. - 자동 상태 피드백: 폼 안에
<div data-3minapi-status></div>를 두세요. 런타임이textContent를 채우고is-success/is-error클래스를 토글합니다. - HTML5 검증 속성(
required,min,max,pattern,type=email/number/date/...)은 그대로 통과합니다 — JS 없이 가벼운 검증 가능. - 커스텀 검증, 조건부 제출, 라이프사이클 후크가 필요하면 JavaScript 패널을 사용하세요.
3. JavaScript 가이드
JavaScript 패널은 선택사항이며, 사이트 관리자만 저장할 수 있습니다. 여기에 붙여넣은 코드는 단축코드의 HTML/CSS가 렌더된 직후 자동으로 실행됩니다.
3.1 실행 방식
- 런타임에서
(function(scope){ /* your code */ })('<snippet>')형태로 자동으로 감싸집니다.<script>태그, import, IIFE 래퍼 모두 필요 없습니다. scope변수는 자동 주입되니 그대로 사용하세요. 단축코드 이름을 코드에 직접 적지 마세요.- 같은 단축코드가 한 페이지에 여러 번 등장하면 각 인스턴스가 자기 scope로 독립 실행됩니다.
- 모든 헬퍼는
window.threeminApi.*에서 사용할 수 있습니다. 정확한 응답 필드 경로와 샘플 코드는 Copy AI prompt 결과의[Sample —]블록에 모두 들어 있습니다.
3.2 런타임 환경
- 일반 브라우저 JavaScript(ES2017+) —
async/await,fetch,Promise, 화살표 함수, 구조분해 모두 동작. - DOM API 직접 사용 —
document.querySelector,addEventListener,createElement등. - 단축코드 안에서는 import를 쓸 수 없습니다. 외부 라이브러리는 테마/플러그인에서
wp_enqueue_script로 로드한 뒤 글로벌(window.X)로 접근. - JavaScript 저장은 사이트 관리자만 가능합니다. HTML/CSS 등 다른 필드는 다른 사용자도 저장할 수 있습니다.
3.3 헬퍼 한눈에 보기
| 헬퍼 | 모드 | 동작 |
|---|---|---|
data(scope) |
All | 인라인된 응답 데이터를 파싱(네트워크 호출 없음). 없으면 null. |
fetch(scope, q) |
Get List | 서버 프록시를 통해 다음 페이지 가져오기. { cursor: <next_cursor> }. |
fetchById(scope, id) |
Get List | id로 단일 레코드 GET. |
submit(scope, body) |
POST | <form data-3minapi-form>이 있으면 자동 바인딩됩니다 — 직접 호출하는 경우는 드뭅니다. |
update(scope, body) |
Get Record | 단축코드가 가리키는 레코드를 PUT. |
updateById(scope, id, body) |
Get List | id로 단일 레코드 PUT. |
delete(scope) |
Get Record | 단축코드가 가리키는 레코드 DELETE. |
deleteById(scope, id) |
Get List | id로 단일 레코드 DELETE. |
on(scope, event, cb) |
POST | 'before-submit' / 'success' / 'error' 후크 등록. |
mutation은 큐 확인 응답만 반환합니다. 업데이트된 레코드는 반환하지 않습니다.
update/delete/updateById/deleteById의 응답은success,message,id(큐 작업 id로 레코드 id가 아님),queued_at을 담은 확인 응답입니다. 보낸 body로 DOM을 직접 업데이트하세요(낙관적 UI). 실제 레코드 쓰기는 후속 GET에서 ~3초 정도 지연될 수 있습니다.
3.4 권장 / 피해야 할 패턴
권장
- root를 한 번만 찾기 —
var root = document.querySelector('[data-3minapi-preset="' + scope + '"]');그리고root.querySelector(...)로 모든 셀렉터의 범위를 한정. 같은 단축코드가 여러 번 렌더되어도 안전합니다. - 이벤트 위임 — 동적으로 추가되는 행에는 컨테이너에 한 번 리스너를 걸고
e.target.closest('.…')로 식별. - dataset으로 행 식별자 —
li.dataset.recordId = item.id로 한 번 새기고, 클릭 핸들러에서e.target.closest('li').dataset.recordId읽기. - 읽기는 캐시 사용 —
threeminApi.data(scope)는 인라인된 JSON만 파싱하므로 성능 부담 없이 반복 호출할 수 있습니다. - mutation 응답은 확인 응답 —
update/delete응답은 큐 확인 응답만 담고 있으니 보낸 body로 DOM 업데이트 (낙관적 UI).
피하기
- ⚠️ scope + record_id 문자열 합성으로 element id 만들기 — 단축코드 이름과 원본 레코드 id는 완전히 다른 문자열입니다.
- ⚠️ mutation 응답 wrap depth 오인 — success는
res.json.data.data.success.res.json.data.success(점 하나 모자람)를 읽으면 항상 falsy → HTTP 200이 에러 처리 경로로 빠지는 가장 흔한 함정. - mutation 응답에서 업데이트된 레코드 읽기 시도 — 큐 확인 응답에는 레코드 내용 없음.
- mutation 직후 즉시 재조회 — 비동기 처리로 ~3초 지연 가능.
setTimeout(..., 3000)+ "Saving…" 인디케이터. - mutation body를
{ payload: { ... } }로 감싸기 — body는 1단계 객체{ field: value }형태. 중첩 객체는 URL 인코딩 과정에서 에러 없이 사라집니다. record_id합성 —[A-Za-z0-9_-], ≤256자. 위반하면 422 에러. API가 이전 응답에서 돌려준 id를 그대로 재사용하세요.- 단축코드 이름을 코드에 직접 적기 — 자동 주입된
scope변수 사용.
3.5 응답 wrap depth — 흔한 함정
WordPress의 wp_send_json_success가 한 번, 플러그인의 admin-ajax 핸들러가 한 번 감쌉니다. 결과:
- 페이지 내 단일 GET 읽기(
data(scope)) —data(scope).data.payload.X. fetch()다음 페이지 — 응답 전체는res.json.data.data(.data두 번).fetchById()단일 레코드 — 레코드는res.json.data.data.data(.data세 번).- mutation 큐 확인 응답 —
res.json.data.data.{success, message, id, queued_at}(.data두 번). - POST
'success'후크 이벤트 —e.response.data.data.{success, …}(.data두 번).
전체 시그니처와 검증된 코드 샘플은 Copy AI prompt 결과의 [Sample —] 블록을 참고하세요.
4. 자주 묻는 질문
4.1 "버튼 클릭이 안 먹는데 콘솔 에러도 없어요"
폼 계열 태그(<button>, <input>, <form>, <select>, <fieldset>)에 data-* 속성을 붙였군요. WordPress의 보안 필터(wp_kses)가 저장 시 제거했고, querySelector('[data-...]')는 null, 리스너 바인딩이 없어 아무 로그도 안 찍힙니다.
해결 — 그 요소에 BEM 클래스를 두고(<button class="my-card__back">) root.querySelector('.my-card__back')로 찾으세요.
4.2 "카드가 비거나 필드가 undefined로 표시됩니다"
응답 데이터의 잘못된 경로를 읽고 있습니다. 헬퍼별 정확한 경로는 AI prompt의 [Sample —] 블록에 모두 있습니다. 자주 쓰이는 정답:
data(scope).data.payload.X— 단일 GET.res.json.data.data.data.payload.X—fetchById(세 번 감쌈).
4.3 "Update가 HTTP 200을 받았는데 화면이 안 바뀌어요"
res.json.data.success를 확인하고 있군요. 이 경로는 .data 하나가 모자라서 mutation에서는 항상 undefined입니다. mutation의 success 플래그는 res.json.data.data.success에 있습니다(WP가 한 번, 플러그인이 한 번 감쌉니다). delete / updateById / deleteById도 동일. POST 'success' 후크는 e.response.data.data.success.
4.4 "리스트가 비어 보이는데 API는 200 응답"
DOM 후크 셀렉터가 HTML과 정확히 일치하지 않습니다. HTML을 다시 보고 data-3minapi-feed-list(또는 커스텀 후크)가 그대로 적혀 있는지 확인하세요.
4.5 "저장 후 CSS 규칙이 안 먹어요"
그 규칙이 인라인이었고 보안 필터가 제거했거나, 안전 CSS 목록에 없는 속성입니다. <style> 블록 안으로 옮기세요.
4.6 "POST는 잘 제출됐는데 피드백이 안 보입니다"
폼 안에 <div data-3minapi-status></div>가 없습니다. 런타임은 그 요소에만 textContent를 쓰고 is-success / is-error를 토글합니다.
4.7 "Update 성공인데 UI에 이전 값이 남아요"
mutation 응답에서 업데이트된 레코드를 읽으려 하셨군요. mutation은 큐 확인 응답만 반환합니다 — 레코드 내용 없음. 방금 보낸 body로 DOM을 직접 업데이트하세요.
4.8 "Mutation 직후 페이지 새로고침해도 옛 데이터가 보입니다"
mutation은 비동기 처리되어 재조회가 ~3초까지 지연될 수 있습니다. 낙관적 UI를 쓰세요. 재조회가 꼭 필요하면 "Saving…" 인디케이터와 함께 setTimeout(..., 3000).
4.9 "JS 패널이 비활성화되어 있고 안내가 떠요"
JavaScript 저장 권한이 없는 계정입니다(멀티사이트나 제한된 역할에서 흔함). JavaScript 없이 저장하거나, 사이트 관리자에게 JavaScript 부분 저장을 요청하세요.
4.10 "Test endpoint가 네트워크 에러를 반환합니다"
3Min API 대시보드에서 엔드포인트 ID와 API 키를 확인하세요.
도움받기
- 3Min API 둘러보기 — 3minapi.com/tour
- 직접 문의 — contact@3minapi.com
- WordPress.org 지원 포럼 — 플러그인 정식 공개 후 디렉토리 페이지의 Support 탭에서.