템플릿 범위
보고서에 반복 구간, 중첩된 상세 정보, 또는 데이터 구조에 따라 동적으로 변하는 그룹 요약이 필요한 경우 템플릿 범위(Template Range) 가 적합한 도구입니다.
템플릿 범위를 사용하면 SpreadJS 내부에서 직접 구조화된 데이터 기반 보고서 레이아웃을 설계할 수 있으며, 테이블 연결, 계층 구조 구성, 반복 구간 자동 렌더링을 필드 컨텍스트나 레이아웃 로직을 고민할 필요 없이 처리할 수 있습니다.
데이터에 바인딩된 몇 개의 셀 블록만 정의하면, 템플릿 범위는 고객 → 제품 → 주문 상세와 같은 계층형 데이터를 명확하고 반복 가능한 레이아웃으로 확장하며, 데이터 변경과 항상 동기화됩니다.
지원 구조
데이터 구성 방식에 따라 템플릿 범위는 다음 두 가지 구조 패턴을 지원합니다.
중첩 레벨(Nested Levels) — 관련된 여러 테이블에 걸친 계층형 데이터용 (예: 고객 → 주문 → 항목)
그룹(Groups) — 단일 테이블 내에서 요약 또는 반복 구간을 구성하는 경우 (예: 카테고리별 제품)
아래 다이어그램은 두 구조를 보여줍니다.
중첩 레벨 예제
그룹 예제
주요 기능어떤 구조 패턴을 사용하든 템플릿 범위는 다음과 같은 핵심 기능을 제공합니다.
시각적인 셀 기반 보고서 설계 워크플로
부모–자식 관계 자동 감지
데이터 바인딩 및 필드 컨텍스트 로직과의 자연스러운 통합
가져오기/내보내기 및 실행 취소/다시 실행 완전 지원
핵심 개념
용어 | 설명 | 예제 |
|---|---|---|
템플릿 범위 | 보고서 생성을 위한 구조 템플릿 역할을 하는 연속된 셀 블록입니다. 개발자는 이 영역에 데이터 필드를 배치하여 레이아웃과 필드 컨텍스트를 정의합니다. 렌더링 시 엔진이 데이터 관계와 계층 설정에 따라 범위를 자동 확장합니다. |
|
헤더 | 제목, 로고, 열 레이블에 사용되는 템플릿 범위의 상단 영역입니다. 각 그룹 또는 페이지의 시작에 한 번 표시되며, 상세 영역이 확장될 때 자동 반복됩니다. |
|
상세(Detail) | 바인딩된 데이터 소스의 각 레코드마다 반복 렌더링되는 주요 영역입니다. 일반적으로 행 단위 값이나 항목 상세 표시용으로 사용됩니다. |
|
푸터 | 합계, 비고, 최종 메모 등에 사용되는 템플릿 범위의 하단 영역입니다. 각 그룹 또는 전체 보고서의 끝에 한 번 표시되며 필요 시 자동 반복됩니다. |
|
상세 레벨 | 상세 영역 내부의 중첩된 상세 구간입니다. 각 레벨은 마스터–디테일 관계의 자식 테이블에 대응하며 계층형 데이터 확장을 가능하게 합니다 (예: 주문 → 주문 항목). |
|
그룹 헤더 / 푸터 | 그룹 데이터 표시를 위해 상세 영역 내부에 선택적으로 사용하는 밴드입니다.
|
|
사용 단계
1단계: 템플릿 범위 생성
리포트 시트에서 연속된 셀 범위를 선택합니다.
리포트 시트 탭의 템플릿 범위 그룹에서 Detail을 클릭합니다.
선택한 영역이 새 Detail 범위로 지정되며, 테두리와 범위 이름이 표시됩니다.
참고:
각 리포트 시트에는 하나의 템플릿 범위만 포함할 수 있습니다.
2단계: 범위 구성 요소 추가
모든 구성 요소는 동일한 방식으로 추가됩니다. 대상 셀 영역을 선택한 후 리포트 시트 탭의 템플릿 범위 그룹에서 구성 요소 유형을 선택합니다.
추가 후 선택한 영역은 자동으로 테두리와 레이블이 표시됩니다.
경로 A: 중첩 레벨 구조
상위 영역 아래에 중첩 상세(Nested Detail)를 삽입합니다.
데이터 테이블 바인딩
대상 템플릿 범위 내부를 클릭합니다.
오른쪽에 템플릿 범위 패널이 열리며 현재 범위 계층이 표시됩니다.
패널에서 Detail 또는 Detail Level 항목을 선택하고 Bind Table을 클릭합니다.
사용 가능한 데이터 소스 중 테이블을 선택합니다.
선택한 테이블 이름이 범위 항목 옆에 표시되어 바인딩이 완료됩니다.
참고:
Detail Level 영역은 부모 테이블과 관계가 정의된 자식 테이블에만 바인딩할 수 있습니다.
필요 시 Range Selection을 사용해 영역 좌표를 조정합니다.
경로 B: 그룹 구조
상세 영역을 기준으로 그룹 헤더/푸터를 삽입합니다.
그룹 및 계층 편집
템플릿 범위 패널에서 Group Header/Footer 항목을 클릭합니다.
Group Field 버튼을 사용해 그룹화 열을 지정합니다.
Range Selection으로 그룹 범위 경계를 조정합니다.
3단계: 보고서 레이아웃 설계
구조 구성이 완료되면 보고서의 모양과 데이터 표시를 설계할 수 있습니다.
참고:
레이아웃 설계 중 시스템이 자동으로 컨텍스트 로직을 관리하여 데이터 바인딩 일관성을 유지합니다.
필드 컨텍스트 감지 – 테이블 필드 배치 시 데이터 컨텍스트와 확장 방향 자동 결정
기본 셀 유형 – 필드 삽입 시 기본값은 세로 컨텍스트의 List 셀
컨텍스트 초기화 – 최초 삽입 필드가 해당 Detail 또는 Detail Level의 컨텍스트를 설정
컨텍스트 재사용 – 동일 범위의 이후 필드는 기존 컨텍스트 상속
부모–자식 추론 – 중첩 레벨은 부모 범위 컨텍스트 자동 상속
편집 잠금 – 컨텍스트 설정은 UI에서 수정 불가
필드 제한 – 바인딩되지 않은 필드는 Template Range 내부에 배치 불가
4단계: 미리보기 또는 초기화
미리보기를 클릭하여 보고서 결과를 렌더링하고 검증합니다.
초기화을 클릭하여 현재 템플릿 범위를 초기화합니다.
참고:
부모 Detail 또는 Detail Level을 삭제하면 모든 중첩된 하위 레벨이 자동으로 삭제됩니다.
설계 참고 사항 및 제한
생성 순서
반드시 Detail 범위를 먼저 생성한 후 중첩 레벨, 그룹 헤더/푸터 또는 기타 템플릿 범위를 추가해야 합니다.
Detail 범위가 존재해야만 데이터 테이블을 바인딩할 수 있습니다.
범위 제한
시트당 하나의 템플릿 범위만 허용
하나의 Detail 내부에 중첩 레벨 범위와 그룹 범위는 공존 불가
서로 관련 없는 테이블에 바인딩된 범위는 계층을 구성할 수 없음
데이터 바인딩 및 컨텍스트 규칙
해당 범위에 바인딩된 테이블의 필드만 사용 가능
첫 번째 삽입 필드가 데이터 컨텍스트를 정의하며 기본값은 세로 확장의 List 셀
이후 필드는 자동으로 기존 컨텍스트 재사용
중첩 레이아웃에서 자식 범위는 부모 Detail의 컨텍스트 상속
컨텍스트는 자동 관리되며 UI에서 편집 불가
헤더 및 푸터
부모 Detail에 바인딩된 테이블을 자동 사용
별도의 데이터 바인딩 불필요
부모–자식 삭제 규칙
부모 Detail 또는 Detail Level 삭제 시 모든 하위 레벨 자동 삭제
범위 조정 및 이동 정책
템플릿 범위를 이동 또는 크기 조정하면 컨텍스트 규칙이 재평가됨
범위 외 테이블 필드에 바인딩된 셀이 있으면 바인딩이 해제됨
하위 범위는 부모 선택과 함께 이동
계층 레벨 간 이동은 허용되지 않음
이동 후 대상은 하나의 템플릿 범위 또는 시트 범위 내에 완전히 포함되어야 함
모든 템플릿 셀은 대상 템플릿 범위와 동일한 바인딩 테이블을 사용해야 함
템플릿 셀 유형 변환 규칙
위치 | 허용 변환 |
|---|---|
일반 / 비어 있음 | Empty ↔ Chart |
그룹 영역 외부 | List ↔ Summary |
그룹 헤더/푸터 내부 | Group ↔ Summary |
가져오기 / 내보내기 및 실행 취소 / 다시 실행
템플릿 범위는 ReportSheet Designer 형식으로 가져오기/내보내기 지원
모든 작업은 Undo / Redo를 지원합니다