Template Engine Specification

API 플랫폼 신규 템플릿 엔진 구조 개선을 위해 정의된 최신 템플릿 스펙입니다. visible 바인딩, shiftUpOnHide, binding/type 명확화 등을 포함합니다.

1. 개요

항목	내용
required 프로퍼티 제거	parameters에 정의된 모든 항목은 기본적으로 필수(required=true)
visible 바인딩	Layout 요소에 visible 바인딩 처리 도입
shiftUpOnHide	레이아웃 규칙 추가
binding	text / file 두 종류
type	string / int / boolean / double 명확화

2. Layout 예시 (visible 제어 적용)

json

{
  "itemIndex": "0",
  "tag": "Print",
  "width": 424,
  "height": 950.8,
  "elements": [
    {
      "element_id": "text-1",
      "type": "text",
      "position": { "x": 0, "y": 20 },
      "width": 424,
      "height": 30,
      "text": "$$dateStr$$",
      "fontFamily": "Malgun Gothic",
      "fontSize": 12,
      "textBold": true,
      "textBrush": "#FF7D90C8",
      "groupName": "group1"
    },
    {
      "element_id": "text-2",
      "type": "text",
      "position": { "x": 0, "y": 87 },
      "width": 424,
      "height": 20,
      "text": "$$contents1$$",
      "fontFamily": "Malgun Gothic",
      "fontSize": 11,
      "textBrush": "#FF000000",
      "isDynamic": true,
      "splittable": true,
      "groupName": "group1"
    },
    {
      "element_id": "graphic-3",
      "type": "graphic",
      "imageSource": "pack://siteoforigin:,,,/ebook/images/puruni/teacher.png",
      "position": { "x": 0, "y": 136 },
      "width": 50,
      "height": 15,
      "groupName": "group2",
      "visible": "$$showTeacherIcon$$"
    },
    {
      "element_id": "text-3",
      "type": "text",
      "position": { "x": 0, "y": 152 },
      "width": 424,
      "height": 150,
      "text": "$$contents2$$",
      "fontFamily": "Malgun Gothic",
      "fontSize": 11,
      "isDynamic": true,
      "splittable": true,
      "groupName": "group2",
      "visible": "$$showContents2$$"
    },
    {
      "element_id": "photo-1",
      "type": "photo",
      "fileName": "$$imageMain$$",
      "position": { "x": 0, "y": 319 },
      "width": 424,
      "height": 424
    }
  ]
}

3. Parameters 정의

json

{
  "definitions": {
    "dateStr":          { "binding": "text", "type": "string",  "description": "날짜 텍스트" },
    "contents1":        { "binding": "text", "type": "string",  "description": "본문 텍스트 1" },
    "contents2":        { "binding": "text", "type": "string",  "description": "본문 텍스트 2" },
    "imageMain":        { "binding": "file", "type": "string",  "description": "사진 파일" },
    "showContents2":    { "binding": "text", "type": "boolean", "description": "text-3 표시 여부" },
    "showTeacherIcon":  { "binding": "text", "type": "boolean", "description": "graphic-3 표시 여부" }
  }
}

4. Layout Rules (shiftUpOnHide 포함)

json

{
  "space": "page",
  "margin": {
    "pageMargin": { "spine": 50, "fore": 50, "head": 20, "tail": 30 },
    "mirrorEvenPages": false
  },
  "flow": {
    "columns": 2,
    "columnGap": 30,
    "itemAlign": "center",
    "itemSpacing": { "size": 10, "mode": "between" }
  },
  "shiftUpOnHide": true,
  "lanes": [
    { "id": "left",  "xMin": 0,   "xMax": 155  },
    { "id": "right", "xMin": 155, "xMax": 1000 }
  ]
}

layoutRules 속성 정리

속성	타입	설명
`space`	string	배치 공간 ("page")
`margin.pageMargin`	object	페이지 마진 (spine, fore, head, tail)
`margin.mirrorEvenPages`	boolean	짝수 페이지에서 spine/fore 반전 여부
`flow.columns`	int	컬럼 수 (1~3)
`flow.columnGap`	number	컬럼 간격 (px)
`flow.itemSpacing.size`	number	템플릿 간 간격 (px)
`shiftUpOnHide`	boolean	숨겨진 요소 아래 재배치 여부
`lanes`	array	X-lane 정의 (각 레인: id, xMin, xMax)

shiftUpOnHide 상세 설명

visible: "$$param$$"에 바인딩된 파라미터 값이 false이면 해당 요소가 숨겨집니다.shiftUpOnHide: true일 때, 숨겨진 요소 아래의 요소를 위로 당겨 배치합니다. lanes가 정의된 경우 숨겨진 요소와 같은 X 범위(레인)에 속하는 요소만 상향 이동합니다. 자세한 내용은 요소 그룹핑 문서를 참조하세요.

5. binding / type 설명

binding

API 입력값의 전달 방식을 의미합니다.

binding	설명
`text`	문자열 기반 입력
`file`	이미지/파일 ID 또는 URL

type

PAGE JSON에 저장할 때의 실제 데이터 타입을 의미합니다.

type	설명
`string`	문자열
`int`	정수
`double`	실수
`boolean`	true/false

타입 변환 예시 (fontSize)

json

// 템플릿 정의
"fontSize": { "binding": "text", "type": "int" }

// API 입력 (문자열로 전달)
"fontSize": "14"

// PAGE JSON 저장 (정수로 변환)
"fontSize": 14

6. API 호출 예시

둘 다 숨김

json

{
  "dateStr": "2025-03-01",
  "contents1": "첫 번째 문단",
  "imageMain": "photo_001.jpg",
  "contents2": "",
  "showContents2": "false",
  "showTeacherIcon": "false"
}

둘 다 표시

json

{
  "dateStr": "2025-03-01",
  "contents1": "첫 번째 문단",
  "imageMain": "photo_001.jpg",
  "contents2": "안녕하세요. 오늘은 봄 소풍을 다녀왔습니다.",
  "showContents2": "true",
  "showTeacherIcon": "true"
}

텍스트만 숨김, 아이콘 표시

json

{
  "dateStr": "2025-03-01",
  "contents1": "첫 번째 문단",
  "imageMain": "photo_001.jpg",
  "contents2": "",
  "showContents2": "false",
  "showTeacherIcon": "true"
}

7. 최종 정리

항목	설명
required 제거	parameters에 정의된 항목은 모두 필수
visible	요소의 표시 여부를 결정
shiftUpOnHide	숨겨진 요소 아래 요소 재정렬
binding	text / file
type	PAGE JSON의 저장 타입