Collapse

Collapse는 관련 콘텐츠를 펼치고 접을 수 있는 영역으로 구성합니다. 고정 패널을 직접 관리하거나 모델/API 레코드에 하나의 템플릿을 반복 적용할 수 있습니다.

1. Content Mode 선택

모드	사용 시점	콘텐츠 소스
Static	패널 수와 구조가 고정됨	CollapsePanel을 추가하고 각 콘텐츠 편집
Data Source	같은 유형의 레코드를 패널로 표시	Data Source 하나와 Item Template 하나

기존 페이지 JSON에 Content Mode가 없으면 속성 패널에 Static이 자동으로 표시되고 Runtime도 Static으로 동작하므로 마이그레이션할 필요가 없습니다.

이 가이드는 서로 보완하는 세 가지 예제를 사용합니다. 아래 스크린샷과 설정 단계만으로 재현할 수 있으며 Spark Sample 애플리케이션에 접근할 필요가 없습니다.

• Onboarding Checklist는 Content Mode = Static을 명시적으로 설정합니다. 네 개의 패널에 서로 다른 읽기 전용 Form을 배치해 정적 구조, 기본 펼침, 컴포넌트 함수를 설명합니다.
• Frequently Asked Questions는 Content Mode = Data Source를 사용하고 /spark/api/sample/collapse/faqs에서 레코드를 읽어 FAQ Item Template을 반복합니다. Test, 필드 매핑, 페이징, Current Record, 개발 미리보기 데이터를 설명합니다.
• Support Answers with Custom Content는 같은 데이터 소스를 재사용하고 페이지 Content를 각 동적 패널에서 반복합니다. 공유 콘텐츠와 record.* 바인딩을 설명합니다.

2. Static 모드

1. Containers에서 Collapse를 페이지로 끌어옵니다.
2. Content Mode = Static을 유지합니다.
3. Collapse Panels에서 항목을 추가하고 드래그하여 순서를 바꿉니다.
4. Title, Description, Icon, 기본 펼침, Disabled, Trigger Area를 설정합니다.
5. 각 패널에 Form, Panel 또는 다른 콘텐츠를 배치합니다.

외부 Collapse는 Single Panel Mode, Show Border, Transparent Style, Size, Arrow Position을 제어합니다. Trigger Area는 Header를 권장합니다. 이 경우 오른쪽 빈 공간을 포함한 헤더 행 전체를 클릭해 펼치거나 접을 수 있습니다. 화살표만 트리거로 사용하려면 Icon을 선택합니다. Disabled 패널도 Design Mode에서는 선택하여 편집할 수 있습니다.

3. Data Source 모드

3.1 데이터 소스

1. Content Mode = Data Source를 선택합니다.
2. id 또는 code 같은 Row Unique Key를 지정합니다. 모든 레코드에 존재하고 고유해야 합니다.
3. Items Per Request와 Empty State Text를 설정합니다.
4. 모델 또는 Custom URL과 URL, Method, Rows Path, Total Path, Record Fields를 구성합니다.
5. Test를 클릭합니다. Test는 Design Preview 및 Runtime과 동일한 요청/응답 처리를 사용하며 키 누락과 중복도 검사합니다.

권장 응답:

{
  "success": true,
  "data": {
    "total": 6,
    "current": 1,
    "pageSize": 4,
    "records": [{
      "id": "invite-team",
      "category": "Getting started",
      "question": "When should I invite the wider team?",
      "answer": "Invite the team after access rules are ready.",
      "disabled": false,
      "defaultExpanded": true
    }]
  }
}

Rows Path는 data.records, Total Path는 data.total을 사용합니다.

3.2 Item Template

CardSet과 같은 방식입니다. Item Template 편집 버튼을 클릭하고 갤러리에서 템플릿을 선택한 다음, 같은 대화상자에서 필드 매개변수를 설정합니다.

Content에서 제목, 설명, 본문, 카테고리 또는 배지 필드를 매핑합니다. Behavior에서는 Icon, Visible, Disabled, Default Expanded 필드를 필요에 따라 매핑합니다. 세 템플릿은 같은 동작 규칙을 공유합니다.

템플릿	용도	주요 매핑
FAQ	도움말 센터	Title, Answer, Category, Answer Format
Record Summary	업무 레코드	Title, Description, Content, Badge
Custom Content	사용자 정의 레이아웃	헤더/동작 필드와 페이지 Content 참조

Live Preview에서 Preview Record를 변경하거나 실제 미리보기 데이터를 다시 불러올 수 있습니다. Save는 초안을 저장하고 Cancel, 닫기, Escape는 기존 템플릿을 변경하지 않습니다.

3.3 Content로 사용자 정의 내용 구성

Content는 페이지에서 재사용하는 리소스이며 Form이나 Collapse 내부의 숨은 하위 캔버스가 아닙니다. Page Resources는 Popups와 Contents로 구분됩니다. Content를 열면 팔레트와 속성 패널을 유지한 채 오른쪽에서 넓은 디자인 드로어가 열립니다. 제목 표시줄의 닫기 버튼, 드로어 바깥 영역, Back to page 또는 Escape로 돌아갈 수 있습니다.

Custom Content에서는 기존 Content를 선택하거나 Create Content, Edit Content, Unlink Content를 사용할 수 있습니다. Unlink는 현재 Collapse의 참조만 제거합니다. 하나의 Content를 여러 곳에서 공유할 수 있으며 수정은 모든 참조에 반영됩니다. 참조 중인 Content는 삭제할 수 없습니다. 하위 컨트롤은 별도 매개변수 매핑 없이 record.*를 직접 읽습니다. 이전 Item Template panels 구조는 첫 로드 또는 저장 시 Content로 자동 전환됩니다.

3.4 디자인 미리보기와 Runtime

• Design Preview와 Runtime은 같은 렌더러를 사용합니다.
• 미리보기는 한 페이지를 요청하며 실제 데이터가 없으면 Sample Record로 명확히 표시된 예제를 보여 줍니다.
• 최초에는 스켈레톤, 빈 상태와 오류를 명확히 표시하며 Retry를 제공합니다.
• Runtime은 추가 데이터가 있으면 Load more를 표시하고 동시에 하나의 요청만 실행합니다.
• 다시 불러온 후에도 존재하는 펼침 키는 유지됩니다.
• Runtime은 잘못된 키를 건너뛰고 Test는 설정 오류로 알려 줍니다.

4. 상호작용

Static은 Collapse onChange와 CollapsePanel onClick, Data Source는 Collapse onChange와 Item Template onClick을 지원합니다.

동적 항목을 전환하면 Current Record를 먼저 기록하고 Item Template onClick, Collapse onChange 순으로 실행합니다. 액션은 record.*와 다음 값을 읽을 수 있습니다.

collapse.activeKeys
collapse.expandedCount
collapse.changedKey
collapse.changedIndex
collapse.changedNumber
collapse.changedRecord
collapse.expanded
collapse.accordion
collapse.contentMode

Toast 예: FAQ: [[record.question]].

5. 컴포넌트 함수

함수	동작
expandAll	활성 항목을 펼침. Single Panel Mode에서는 첫 항목만 유지
collapseAll	모두 접기
resetPanels	기본 펼침 상태 복원
reloadCollapse	데이터를 다시 불러오고 펼침 키 조정
setCollapseData(data)	이전 액션이 제공한 배열로 데이터 교체

6. 요청 컨텍스트

Test, Design Preview, Runtime은 다음 헤더를 자동 전송합니다.

X-Spark-Page-Environment: DEV | TEST | PROD
X-Spark-Page-Render-Mode: DESIGN_PREVIEW | RUNTIME

직접 추가하지 마세요. 페이지 요청 컨텍스트를 참고하세요. Spark Sample은 /spark/api/sample/collapse/faqs를 사용하고 백엔드는 SparkPageRequestHeaders.resolve(environment, renderMode)로 컨텍스트를 해석합니다. DESIGN_PREVIEW에서는 개발용 결정적 데이터를 반환할 수 있습니다.

7. 예제 재현

7.1 정적 온보딩 체크리스트

1. Collapse를 추가하고 Static을 유지한 채 Single Panel Mode를 끕니다.
2. CollapsePanel 네 개를 추가하고 각각 다른 읽기 전용 Form을 배치합니다.
3. 첫 항목에서 Expanded by Default를 켭니다.
4. expandAll, collapseAll, resetPanels를 호출하는 버튼 세 개를 추가합니다.

7.2 동적 FAQ

1. Data Source, Single Panel Mode, Transparent Style을 선택합니다.
2. Row Unique Key는 id, Items Per Request는 4로 설정합니다.
3. /spark/api/sample/collapse/faqs, POST, data.records, data.total을 사용합니다.
4. Test 후 FAQ 템플릿을 선택합니다.
5. question, answer, category, disabled, defaultExpanded를 매핑합니다.
6. onChange에 FAQ: [[record.question]]을 추가합니다.

7.3 Custom Content 레코드 상세

1. Data Source Collapse를 하나 더 추가하고 동일한 응답 경로로 /spark/api/sample/collapse/faqs를 재사용합니다.
2. Custom Content를 선택하고 Title은 question, Description은 summary에 매핑합니다.
3. Create Content를 누르고 리소스 이름을 Support answer content로 지정한 뒤 넓은 디자인 드로어에서 편집합니다.
4. Content에 읽기 전용 Form을 추가하고 Controls Per Row 2, Label 4, Content 8로 설정합니다.
5. [[record.category]], [[record.environment]], [[record.renderMode]]에 바인딩한 읽기 전용 Field를 추가합니다.
6. [[record.answer]]에 바인딩한 전체 행 읽기 전용 TextArea를 추가합니다.
7. Preview Record를 바꿀 때 헤더와 Form이 함께 변경되는지 확인합니다.

8. 문제 해결

Test에서 Row Unique Key 중복을 알림

행 번호가 아니라 페이징, 정렬, 새로고침 후에도 유지되는 업무 ID를 사용합니다.

Design Preview에 Sample Record가 표시됨

데이터 소스가 없거나 접근할 수 없거나 요청이 실패한 상태입니다. Test에서 URL, 응답 경로, 백엔드 요청을 확인합니다.

템플릿 수정 후 미리보기가 바뀌지 않음

템플릿 대화상자를 저장하고 Record Fields 또는 실제 응답에 매핑 필드가 있는지 확인합니다.

Content에서 현재 레코드 읽기

하위 컨트롤 값이나 Interaction 표현식에 record.*를 사용하고 미리보기 값을 고정하지 않습니다.

Load more 후 펼친 항목이 사라짐

같은 업무 레코드가 같은 Row Unique Key를 유지하는지 확인합니다. Spark는 안정적인 키만 보존할 수 있습니다.

9. 디자인 권장 사항

• 한 그룹에는 보통 3~8개의 패널만 표시하고 더 많으면 카테고리나 검색을 제공합니다.
• FAQ와 긴 설명에는 Single Panel Mode를 우선 사용하고, 비교가 필요한 경우 여러 패널 펼치기를 허용합니다.
• Title만으로 펼친 콘텐츠를 알 수 있게 하고 Description에서 제목을 반복하지 않습니다.
• Disabled는 회색 표현에만 의존하지 말고 읽을 수 있는 설명을 함께 제공합니다.
• 백엔드는 안정적인 고유 키를 반환하고 페이지 응답 구조를 일관되게 유지해야 합니다.
• 동적 매핑을 Record Fields에 선언하여 선택, 테스트, 유지보수를 쉽게 합니다.
• 여러 단계의 Collapse 중첩을 피하고 제목, Tab 또는 별도 페이지를 사용합니다.