홈▸개발문서▸갤러리 템플릿

Gallery Templates

여러 장의 사진을 자동으로 레이아웃하여 배치하는 특수 템플릿 가이드입니다.

개요

갤러리 타입바인딩사진 제한레이아웃 방식상태
collageGallerycollageGallery최대 9장콜라주 표현식구현됨
rowGalleryrowGallery제한 없음행 기반 배치구현됨

collageGallery (콜라주 갤러리)

PhotoLayoutCore 라이브러리의 콜라주 알고리즘을 사용하여 1~9장의 사진을 예쁘게 배치합니다. 업로드된 사진들의 가로/세로 비율을 분석하여 최적의 배치를 자동 생성합니다.

템플릿 정의

json
{
  "parameters": {
    "definitions": {
      "collagePhotos": {
        "binding": "collageGallery",
        "type": "array",
        "itemType": "file",
        "minItems": 1,
        "maxItems": 9,
        "required": true,
        "description": "콜라주 갤러리 사진들"
      }
    }
  },
  "layout": {
    "elements": [
      {
        "element_id": "collageGallery-1",
        "type": "collageGallery",
        "photos": "$$collagePhotos$$",
        "tag": "collageGallery1",
        "fit": "cover",
        "position": { "x": 0, "y": 0 },
        "container": {
          "maxWidth": 424,
          "maxHeight": 424,
          "itemGap": 10,
          "padding": 0,
          "layout": "auto",
          "fit": "contain",
          "align": {
            "horizontal": "center",
            "vertical": "top"
          }
        },
        "isDynamic": true
      }
    ]
  }
}

container 속성

속성타입기본값설명
maxWidthnumber978콜라주 최대 너비 (px)
maxHeightnumber424콜라주 최대 높이 (px)
itemGapnumber10사진 간 간격 (px)
paddingnumber0컨테이너 내부 여백 (px)
layoutstring"auto"레이아웃 모드
fitstring"contain"피팅 모드: contain
align.horizontalstring"center"수평 정렬: left, center, right
align.verticalstring"top"수직 정렬: top, center, bottom
피팅 모드 contain은 기본값이자 유일한 옵션으로, 콜라주를 maxWidth x maxHeight 영역 내에 비율을 유지하며 맞춥니다.

rowGallery (행 갤러리)

RowPhotoLayoutCore 라이브러리의 O(n) 알고리즘을 사용하여 사진을 행 단위로 자동 배치합니다. 사진 수 제한 없이 사용할 수 있으며, 사진이 많으면 자동으로 여러 그룹으로 분할됩니다.

템플릿 정의

json
{
  "parameters": {
    "definitions": {
      "rowPhotos": {
        "binding": "rowGallery",
        "type": "array",
        "itemType": "file",
        "minItems": 1,
        "required": true,
        "description": "행 갤러리 사진들"
      }
    }
  },
  "layout": {
    "elements": [
      {
        "element_id": "rowGallery-1",
        "type": "rowGallery",
        "photos": "$$rowPhotos$$",
        "tag": "rowGallery1",
        "fit": "cover",
        "position": { "x": 0, "y": 0 },
        "container": {
          "maxWidth": 424,
          "maxHeight": 424,
          "itemGap": 10,
          "padding": 0,
          "row": {
            "maxHeight": 300,
            "fillMiddle": true
          }
        },
        "isDynamic": true
      }
    ]
  }
}

container 속성

속성타입기본값설명
maxWidthnumber978컨테이너 최대 너비 (px)
maxHeightnumber0컨테이너 최대 높이 (px), 0=무제한
itemGapnumber10사진 간 간격 및 행 간 간격 (px)
paddingnumber0컨테이너 내부 여백 (px)
row.maxHeightnumber400행 최대 높이 (px), 최소 100px
row.fillMiddlebooleanfalse중간 행 가로 채움 (Justified 모드)

heightMode 속성

값설명
auto (기본값)동적 높이 - 사진에 맞게 자동 조절
fixed고정 높이 - container.maxHeight 기준 청크 분할

API 호출 예시

collageGallery 호출

bash
curl -X 'POST' \
  'https://api.sweetbook.com/v1/books/{bookUid}/contents' \
  -H 'Content-Type: multipart/form-data' \
  -F 'templateUid=6VgvkpdYZzsI' \
  -F 'parameters={"dateStr":"2025-01-15","contents1":"부모님 말씀","contents2":"교사 코멘트"}' \
  -F 'collagePhotos=@photo1.jpg' \
  -F 'collagePhotos=@photo2.jpg' \
  -F 'collagePhotos=@photo3.jpg'

rowGallery 호출

bash
curl -X 'POST' \
  'https://api.sweetbook.com/v1/books/{bookUid}/contents' \
  -H 'Content-Type: multipart/form-data' \
  -F 'templateUid=3Z5VACFSGpEW' \
  -F 'parameters={"dateStr":"2025-01-15","contents1":"부모님 말씀","contents2":"교사 코멘트"}' \
  -F 'rowPhotos=@photo1.jpg' \
  -F 'rowPhotos=@photo2.jpg' \
  -F 'rowPhotos=@photo3.jpg' \
  -F 'rowPhotos=@photo4.jpg' \
  -F 'rowPhotos=@photo5.jpg'

자동 분할 기능

collageGallery 분할 기준

콜라주 너비ratio설명
<= 400px0.5작은 콜라주는 관대하게
<= 500px0.3중간 콜라주
<= 1000px0.2큰 콜라주
> 1000px0.15매우 큰 콜라주

분할 공식: 분할 필요 = minPhotoArea < (collageWidth × ratio)²

분할 결과 groupName

collageGallery: collageGallery_tag_part0, collageGallery_tag_part1, ...
rowGallery: rowGallery_tag_page0, rowGallery_tag_page1, ...

collageGallery vs rowGallery 선택 기준

기준collageGalleryrowGallery
사진 수1~9장제한 없음
레이아웃콜라주 표현식 (미적)행 기반 (정돈)
용도소수의 사진을 예쁘게많은 사진을 체계적으로
알고리즘표현식 기반O(n) 행 완성

주의사항

collageGallery는 1~9장의 사진이 필요합니다. rowGallery는 최소 1장 이상의 사진이 필요합니다. 동일한 필드명으로 여러 파일을 업로드해야 하며, 갤러리 요소는 서버에서 자동으로 개별 photo 요소들로 변환됩니다.

관련 문서