홈▸개발문서▸컬럼 템플릿

Column Templates

컬럼 레이아웃 템플릿 사용 가이드입니다. 페이지를 여러 개의 세로 열로 나누어 콘텐츠를 배치합니다.

개요

컬럼 템플릿은 page_layout_state 테이블 기반 배치 시스템을 사용하여 같은 페이지 내에서 컬럼별로 콘텐츠를 효율적으로 배치할 수 있습니다.

사용 가능한 컬럼 템플릿

1. 1컬럼 내지 템플릿

템플릿 UID: cnH0Ud1nl1f9 — 파라미터: date (날짜), contents (본문 내용)  — 페이지 전체를 하나의 열로 사용 (일반적인 전면 레이아웃).

2. 2컬럼 내지 템플릿

템플릿 UID: 4G5qpFLebGKd — 파라미터: date (날짜), contents (본문 내용)  — 페이지를 2개의 열로 나누어 콘텐츠 배치 (신문/잡지 스타일).

3. 3컬럼 내지 템플릿

템플릿 UID: 2Ec6Dp8duR3z — 파라미터: date (날짜), contents (본문 내용)  — 페이지를 3개의 열로 나누어 콘텐츠 배치 (멀티 컬럼 레이아웃).

컬럼 템플릿 특징

특징설명
자동 배치 최적화page_layout_state 테이블을 활용하여 최적의 위치에 자동 배치
컬럼 호환성 체크같은 페이지 내에서 동일한 컬럼 수를 가진 템플릿만 배치 가능
배치 우선순위같은 면 빈 슬롯 → 반대 면 → 다음 페이지
슬롯 기반 좌표 계산컬럼별로 X 좌표를 자동 계산하여 정렬
상태 추적각 면의 컬럼 사용 현황을 실시간으로 추적

사용 방법

curl 예시 — 2컬럼 템플릿

bash
curl -X 'POST' \
  'https://api.sweetbook.com/v1/books/bk_3dJTg8WOpR2e/contents?breakBefore=page' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=@image.jpg;type=image/jpeg' \
  -F 'templateUid=4G5qpFLebGKd' \
  -F 'parameters={"date":"2025-08-27","contents":"Hello World!\nThis is a test."}'

curl 예시 — 3컬럼 템플릿

bash
curl -X 'POST' \
  'https://api.sweetbook.com/v1/books/bk_3dJTg8WOpR2e/contents?breakBefore=page' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=@image.jpg;type=image/jpeg' \
  -F 'templateUid=2Ec6Dp8duR3z' \
  -F 'parameters={"date":"2025-10-22","contents":"3컬럼 레이아웃 테스트\n여러 줄의 텍스트"}'

curl 예시 — 1컬럼 템플릿

bash
curl -X 'POST' \
  'https://api.sweetbook.com/v1/books/bk_3dJTg8WOpR2e/contents?breakBefore=page' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=@image.jpg;type=image/jpeg' \
  -F 'templateUid=cnH0Ud1nl1f9' \
  -F 'parameters={"date":"2025-08-27","contents":"Hello World!\nThis is a test."}'

컬럼 배치 규칙

컬럼 호환성

같은 컬럼 수의 템플릿끼리는 같은 페이지 면에 배치 가능합니다. 다른 컬럼 수의 템플릿은 같은 페이지 면에 배치할 수 없으며, 다음 면 또는 페이지로 이동합니다.

컬럼 폭 및 X 좌표 계산 (pageMargin + columnGap)

페이지 단면 너비: pageWidth. 양쪽 마진: spine (책등 쪽), fore (바깥쪽).

1컬럼일 때

text
colWidth = contentWidth = pageWidth - (spine + fore)
// columnGap은 무시됨

X 시작점:
  왼쪽 면(left):  X = fore
  오른쪽 면(right): X = pageWidth + spine

2컬럼 이상일 때

text
colWidth = (contentWidth - columnGap × (columns - 1)) / columns

baseX:
  왼쪽 면(left):  baseX = fore
  오른쪽 면(right): baseX = pageWidth + spine

columnOffset = CurrentSlotIndex × (colWidth + columnGap)

X_final = baseX + columnOffset + templateX

세로 높이 (head/tail 마진)

text
effectivePageHeight = pageHeight - (head + tail)
// Contents API는 이 값을 기준으로 슬롯 여부를 판단합니다.

처리 과정

1. 템플릿 조회 및 layout_rules에서 컬럼 수 추출
2. page_layout_state 테이블에서 최근 페이지 상태 조회
3. 배치 위치 결정: 같은 면 빈 슬롯 → 반대 면 → 다음 페이지
4. 슬롯 기반 X 좌표 계산
5. JSON 파일 저장 및 데이터베이스 업데이트
6. page_layout_state 업데이트 (PageNum, PageSide, TotalColumns, UsedColumns)

컬럼 레이아웃 활용 예시 — 신문/잡지 스타일 책 만들기 (2컬럼)

bash
# 1. 책 생성
curl -X 'POST' 'https://api.sweetbook.com/v1/books' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"2컬럼 잡지 스타일","bookSpecUid":"SQUAREBOOK_HC","creationType":"TEST"}'

# 2. 2컬럼 콘텐츠 연속 추가 (같은 페이지에 2개까지 배치 가능)
curl -X 'POST' 'https://api.sweetbook.com/v1/books/bk_xxxxx/contents' \
  -F 'files=@image1.jpg' \
  -F 'templateUid=4G5qpFLebGKd' \
  -F 'parameters={"date":"2025-10-22","contents":"첫 번째 컬럼 내용"}'

curl -X 'POST' 'https://api.sweetbook.com/v1/books/bk_xxxxx/contents' \
  -F 'files=@image2.jpg' \
  -F 'templateUid=4G5qpFLebGKd' \
  -F 'parameters={"date":"2025-10-22","contents":"두 번째 컬럼 내용 (같은 페이지 왼쪽에 자동 배치)"}'

주의사항

같은 면에는 동일한 컬럼 수의 템플릿만 배치됩니다. 컬럼이 호환되지 않으면 자동으로 다음 면/페이지로 이동합니다. 표지(pageNum=0) 다음 첫 내지는 항상 오른쪽 면(pageSide=right)에 배치됩니다. 텍스트 파라미터와 함께 이미지 파일 1장 업로드가 필요합니다.

관련 문서