# 템플릿 범위 ## Content 보고서에 반복 구간, 중첩된 상세 정보, 또는 데이터 구조에 따라 동적으로 변하는 그룹 요약이 필요한 경우 **템플릿 범위(Template Range)** 가 적합한 도구입니다. 템플릿 범위를 사용하면 SpreadJS 내부에서 직접 구조화된 데이터 기반 보고서 레이아웃을 설계할 수 있으며, 테이블 연결, 계층 구조 구성, 반복 구간 자동 렌더링을 필드 컨텍스트나 레이아웃 로직을 고민할 필요 없이 처리할 수 있습니다. 데이터에 바인딩된 몇 개의 셀 블록만 정의하면, 템플릿 범위는 고객 → 제품 → 주문 상세와 같은 계층형 데이터를 명확하고 반복 가능한 레이아웃으로 확장하며, 데이터 변경과 항상 동기화됩니다. ## 지원 구조 데이터 구성 방식에 따라 템플릿 범위는 다음 두 가지 구조 패턴을 지원합니다. * **중첩 레벨(Nested Levels)** — 관련된 여러 테이블에 걸친 계층형 데이터용 (예: 고객 → 주문 → 항목) * **그룹(Groups)** — 단일 테이블 내에서 요약 또는 반복 구간을 구성하는 경우 (예: 카테고리별 제품) 아래 다이어그램은 두 구조를 보여줍니다. **중첩 레벨 예제** ![demo.705b4a.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/demo.705b4a-20260108.a96a4e.gif?width=1000) **그룹 예제** ![demo2.1222a8.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/demo2.1222a8-20260108.1ec06f.gif?width=1000) 주요 기능어떤 구조 패턴을 사용하든 템플릿 범위는 다음과 같은 핵심 기능을 제공합니다. * 시각적인 셀 기반 보고서 설계 워크플로 * 부모–자식 관계 자동 감지 * 데이터 바인딩 및 필드 컨텍스트 로직과의 자연스러운 통합 * 가져오기/내보내기 및 실행 취소/다시 실행 완전 지원 ## 핵심 개념 | **용어** | **설명** | **예제** | | --- | --- | --- | | 템플릿 범위 | 보고서 생성을 위한 구조 템플릿 역할을 하는 연속된 셀 블록입니다. 개발자는 이 영역에 데이터 필드를 배치하여 레이아웃과 필드 컨텍스트를 정의합니다. 렌더링 시 엔진이 데이터 관계와 계층 설정에 따라 범위를 자동 확장합니다. | ![image.256808.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.256808-20260108.3f3450.png?width=250) | | 헤더 | 제목, 로고, 열 레이블에 사용되는 템플릿 범위의 상단 영역입니다. 각 그룹 또는 페이지의 시작에 한 번 표시되며, 상세 영역이 확장될 때 자동 반복됩니다. | ![image.01c72c.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.01c72c-20260108.ddce1f.png?width=250) | | 상세(Detail) | 바인딩된 데이터 소스의 각 레코드마다 반복 렌더링되는 주요 영역입니다. 일반적으로 행 단위 값이나 항목 상세 표시용으로 사용됩니다. | ![image.8dcb21.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.8dcb21-20260108.bfe644.png?width=250) | | 푸터 | 합계, 비고, 최종 메모 등에 사용되는 템플릿 범위의 하단 영역입니다. 각 그룹 또는 전체 보고서의 끝에 한 번 표시되며 필요 시 자동 반복됩니다. | ![image.934e67.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.934e67-20260108.52fba7.png?width=250) | | 상세 레벨 | 상세 영역 내부의 중첩된 상세 구간입니다. 각 레벨은 마스터–디테일 관계의 자식 테이블에 대응하며 계층형 데이터 확장을 가능하게 합니다 (예: *주문 → 주문 항목*). | ![image.022451.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.022451-20260108.255731.png?width=250) | | 그룹 헤더 / 푸터 | 그룹 데이터 표시를 위해 상세 영역 내부에 선택적으로 사용하는 밴드입니다. | ![image.d78d17.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.d78d17-20260108.ce8be0.png?width=250) | ## 사용 단계 **1단계: 템플릿 범위 생성** 1. 리포트 시트에서 연속된 셀 범위를 선택합니다. 2. **리포트 시트** 탭의 **템플릿 범위** 그룹에서 **Detail**을 클릭합니다. 3. 선택한 영역이 새 **Detail** 범위로 지정되며, 테두리와 범위 이름이 표시됩니다. ![step1.b05003.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/step1.b05003-20260108.9f8427.gif?width=1000) >type=note > **참고:** > 각 리포트 시트에는 하나의 템플릿 범위만 포함할 수 있습니다. **2단계: 범위 구성 요소 추가** 모든 구성 요소는 동일한 방식으로 추가됩니다. 대상 셀 영역을 선택한 후 리포트 시트 탭의 템플릿 범위 그룹에서 구성 요소 유형을 선택합니다. ![image.605568.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.605568-20260108.a90b3c.png?width=400) 추가 후 선택한 영역은 자동으로 테두리와 레이블이 표시됩니다. **경로 A: 중첩 레벨 구조** 1. 상위 영역 아래에 중첩 상세(Nested Detail)를 삽입합니다. ![step2.1.1.93c571.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/step2.1.1.93c571-20260108.98b122.gif?width=1000) 2. 데이터 테이블 바인딩 1. 대상 **템플릿 범위** 내부를 클릭합니다. 2. 오른쪽에 **템플릿 범위** 패널이 열리며 현재 범위 계층이 표시됩니다. ![image.75c64d.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.75c64d-20260108.409f84.png?width=400) 3. 패널에서 **Detail** 또는 **Detail Level** 항목을 선택하고 **Bind Table**을 클릭합니다. ![image.687c15.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.687c15-20260108.55be57.png?width=400) 4. 사용 가능한 데이터 소스 중 테이블을 선택합니다. ![image.d4c102.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.d4c102-20260108.02ece4.png?width=400) 5. 선택한 테이블 이름이 범위 항목 옆에 표시되어 바인딩이 완료됩니다. ![image.9a96f3.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.9a96f3-20260108.9b16d2.png?width=400) >type=note > **참고:** > Detail Level 영역은 부모 테이블과 관계가 정의된 자식 테이블에만 바인딩할 수 있습니다. ![step2.1.2.5c7058.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/step2.1.2.5c7058-20260108.ca9c8e.gif?width=1000) 3. 필요 시 **Range Selection**을 사용해 영역 좌표를 조정합니다. ![image.fcc77c.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.fcc77c-20260108.208bb9.png?width=1000) **경로 B: 그룹 구조** 1. 상세 영역을 기준으로 그룹 헤더/푸터를 삽입합니다. ![step2.2.1.4fd233.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/step2.2.1.4fd233-20260108.7da740.gif?width=1000) 2. 그룹 및 계층 편집 1. 템플릿 범위 패널에서 **Group Header/Footer** 항목을 클릭합니다. ![image.5706d2.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.5706d2-20260108.905a4c.png?width=400) 2. **Group Field** 버튼을 사용해 그룹화 열을 지정합니다. ![image.96b585.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.96b585-20260108.2495e8.png?width=1000) 3. **Range Selection**으로 그룹 범위 경계를 조정합니다. ![image.5c27c6.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.5c27c6-20260108.0f0778.png?width=1000) **3단계: 보고서 레이아웃 설계** 구조 구성이 완료되면 보고서의 모양과 데이터 표시를 설계할 수 있습니다. ![step3.632ee3.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/step3.632ee3-20260108.0ea0df.gif?width=1000) >type=note > **참고:** > 레이아웃 설계 중 시스템이 자동으로 컨텍스트 로직을 관리하여 데이터 바인딩 일관성을 유지합니다. > > * 필드 컨텍스트 감지 – 테이블 필드 배치 시 데이터 컨텍스트와 확장 방향 자동 결정 > * 기본 셀 유형 – 필드 삽입 시 기본값은 세로 컨텍스트의 List 셀 > * 컨텍스트 초기화 – 최초 삽입 필드가 해당 Detail 또는 Detail Level의 컨텍스트를 설정 > * 컨텍스트 재사용 – 동일 범위의 이후 필드는 기존 컨텍스트 상속 > * 부모–자식 추론 – 중첩 레벨은 부모 범위 컨텍스트 자동 상속 > * 편집 잠금 – 컨텍스트 설정은 UI에서 수정 불가 > * 필드 제한 – 바인딩되지 않은 필드는 Template Range 내부에 배치 불가 **4단계: 미리보기 또는 초기화** * **미리보기**를 클릭하여 보고서 결과를 렌더링하고 검증합니다. ![image.1ac827.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image.1ac827-20260108.30d439.png?width=1000) * **초기화**을 클릭하여 현재 템플릿 범위를 초기화합니다. ![step4.910666.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/step4.910666-20260108.aceeba.gif?width=1000) >type=note > **참고:** > 부모 **Detail** 또는 **Detail Level**을 삭제하면 모든 중첩된 하위 레벨이 자동으로 삭제됩니다. ## 설계 참고 사항 및 제한 **생성 순서** * 반드시 **Detail 범위를 먼저 생성**한 후 중첩 레벨, 그룹 헤더/푸터 또는 기타 템플릿 범위를 추가해야 합니다. * Detail 범위가 존재해야만 데이터 테이블을 바인딩할 수 있습니다. **범위 제한** * 시트당 **하나의 템플릿 범위만 허용** * 하나의 Detail 내부에 **중첩 레벨 범위와 그룹 범위는 공존 불가** * 서로 관련 없는 테이블에 바인딩된 범위는 계층을 구성할 수 없음 **데이터 바인딩 및 컨텍스트 규칙** * 해당 범위에 바인딩된 **테이블의 필드만 사용 가능** * **첫 번째 삽입 필드**가 데이터 컨텍스트를 정의하며 기본값은 세로 확장의 **List 셀** * 이후 필드는 자동으로 기존 컨텍스트 재사용 * 중첩 레이아웃에서 **자식 범위는 부모 Detail의 컨텍스트 상속** * 컨텍스트는 **자동 관리**되며 **UI에서 편집 불가** **헤더 및 푸터** * 부모 Detail에 바인딩된 테이블을 자동 사용 * 별도의 데이터 바인딩 불필요 **부모–자식 삭제 규칙** * 부모 **Detail 또는 Detail Level** 삭제 시 모든 하위 레벨 자동 삭제 **범위 조정 및 이동 정책** * 템플릿 범위를 이동 또는 크기 조정하면 컨텍스트 규칙이 재평가됨 * 범위 외 테이블 필드에 바인딩된 셀이 있으면 바인딩이 **해제됨** * 하위 범위는 부모 선택과 함께 이동 * 계층 레벨 간 이동은 **허용되지 않음** * 이동 후 대상은 하나의 템플릿 범위 또는 시트 범위 내에 완전히 포함되어야 함 * 모든 템플릿 셀은 대상 템플릿 범위와 동일한 바인딩 테이블을 사용해야 함 **템플릿 셀 유형 변환 규칙** | **위치** | **허용 변환** | | --- | ----- | | 일반 / 비어 있음 | Empty ↔ Chart | | 그룹 영역 외부 | List ↔ Summary | | 그룹 헤더/푸터 내부 | Group ↔ Summary | **가져오기 / 내보내기 및 실행 취소 / 다시 실행** * 템플릿 범위는 ReportSheet Designer 형식으로 가져오기/내보내기 지원 * 모든 작업은 **Undo / Redo**를 지원합니다