템플릿 구조와 바인딩

템플릿의 파라미터 구조를 이해하고, API 호출 시 텍스트·이미지를 올바르게 바인딩하는 방법을 설명합니다.

파라미터 구조

각 템플릿은 parameters.definitions에 바인딩 변수 목록을 정의합니다. 템플릿 조회 API(GET /templates/{templateUid})로 구조를 확인할 수 있습니다.

변수 속성

속성	타입	설명
`binding`	string	바인딩 유형. `text` (텍스트), `file` (이미지 파일), `collageGallery` (콜라주 갤러리), `rowGallery` (행 갤러리)
`type`	string	값 타입. `string`, `int`, `boolean`, `double`, `array`
`required`	boolean	`true`이면 필수. 누락 시 400 에러
`description`	string	변수 설명

표지 템플릿 parameters 예시 (79yjMH3qRPly)

{
  "definitions": {
    "coverPhoto": {
      "binding": "file",
      "type": "string",
      "required": true,
      "description": "앞표지 메인 사진"
    },
    "title": {
      "binding": "text",
      "type": "string",
      "required": true,
      "description": "책 제목 (예: 나의 하루 기록)"
    },
    "dateRange": {
      "binding": "text",
      "type": "string",
      "required": true,
      "description": "날짜 범위 (예: 26.01 - 27.03)"
    }
  }
}

바인딩 유형별 전달 방법

text 바인딩

parameters JSON 문자열에 키-값으로 텍스트를 전달합니다.

file 바인딩

이미지를 전달하는 방식입니다. 두 가지 방법 중 선택:

방식	parameters 값	form 필드
파일 업로드	`"$upload"`	변수명과 동일한 필드에 파일 첨부
URL 전달	이미지 URL 문자열	불필요

collageGallery / rowGallery 바인딩

여러 장의 사진을 갤러리 형태로 배치합니다. type: "array"이며 itemType: "file"로 이미지 배열을 전달합니다. 자세한 내용은 갤러리 템플릿 페이지 참조.

parameters JSON 예시 — 텍스트 + 파일 업로드

{
  "title": "나의 하루 기록",
  "dateRange": "26.01 - 26.04",
  "coverPhoto": "$upload"
}

parameters JSON 예시 — URL 전달

{
  "title": "나의 하루 기록",
  "dateRange": "26.01 - 26.04",
  "coverPhoto": "https://example.com/front.jpg"
}

필수/선택 파라미터

`required` 값	동작
`true`	필수 — 누락 시 400 에러
`false` 또는 미정의	선택 — 누락 시 해당 요소가 페이지에서 제거됨

선택 파라미터를 생략하면 해당 요소가 렌더링 결과에서 자동으로 숨겨집니다. 의도적으로 특정 요소를 표시하지 않고 싶을 때 활용할 수 있습니다.

내지 템플릿 parameters 예시 (46VqZhVNOfAp)

{
  "definitions": {
    "monthNum": {
      "binding": "text",
      "type": "string",
      "required": true,
      "description": "월 번호 2자리 (예: 04)"
    },
    "dayNum": {
      "binding": "text",
      "type": "string",
      "required": true,
      "description": "일 번호 2자리 (예: 25)"
    },
    "diaryText": {
      "binding": "text",
      "type": "string",
      "required": true,
      "description": "일기 본문 텍스트"
    },
    "photo": {
      "binding": "file",
      "type": "string",
      "required": true,
      "description": "메인 사진"
    }
  }
}

템플릿 종류 (templateKind)

종류	용도	사용 API
`cover`	표지	`POST /books/{bookUid}/cover`
`content`	내지 (본문 페이지)	`POST /books/{bookUid}/contents`
`divider`	간지 (구분 페이지)	`POST /books/{bookUid}/contents`
`publish`	발행면	`POST /books/{bookUid}/contents`

템플릿 조회 시 templateKind 파라미터로 종류를 필터링할 수 있습니다.