레이아웃 반복 필드

레이아웃에는 슬라이더·배너·FAQ·파트너 로고처럼 같은 모양의 항목이 여러 개 반복되는 데이터가 자주 들어갑니다. 예전에는 slider1_title, slider2_title … 식으로 변수를 수십 개 선언하고 순서 변경·추가·삭제를 직접 구현해야 했습니다.

Zittme의 반복 필드(repeat field) 는 항목 1개의 필드 구성만 선언하면, 코어가 레이아웃 상세설정에서 다음을 자동으로 제공합니다.

• 항목 추가 / 삭제
• 드래그로 순서 변경
• 노출 켬/끔 + 노출 기간(시작~종료일): 선언하지 않아도 기본 제공
• JSON 저장과 프론트 렌더 시 노출 조건 필터링

슬라이더는 이 범용 기능의 한 가지 용도일 뿐입니다.

1. 선언: conf/info.xml

<extra_vars> 안에 <group> 으로 감싸고, type="repeat" 변수의 <item> 안에 항목 1개의 필드를 넣습니다.

<extra_vars>
  <group>
    <title xml:lang="ko">첫 화면</title>
    <var name="visuals" type="repeat">
      <title xml:lang="ko">비주얼 슬라이드</title>
      <item>
        <var name="image" type="image"><title xml:lang="ko">배경 이미지</title></var>
        <var name="title" type="text"><title xml:lang="ko">제목</title></var>
        <var name="text" type="textarea"><title xml:lang="ko">설명</title></var>
        <var name="link_text" type="text"><title xml:lang="ko">버튼 이름</title></var>
        <var name="link_url" type="text"><title xml:lang="ko">버튼 링크</title></var>
        <var name="align" type="select" default="center">
          <title xml:lang="ko">문구 정렬</title>
          <options value="left"><title xml:lang="ko">왼쪽</title></options>
          <options value="center"><title xml:lang="ko">가운데</title></options>
        </var>
      </item>
    </var>
  </group>
</extra_vars>

• <item> 안의 <var> 는 일반 extra_var와 같은 타입을 그대로 씁니다: text / textarea / image / select / checkbox / color 등.
• 한 레이아웃에 반복 필드를 여러 개 둘 수 있습니다 (예: visuals, partners).
• 반드시 <group> 안에 두세요. 레이아웃 상세설정은 그룹을 탭으로 그리므로, 그룹 밖의 변수는 화면에 보이지 않습니다.

2. 자동으로 붙는 항목 필드

코어가 항목마다 아래 필드를 자동으로 관리합니다. 직접 선언하지 않습니다.

순서는 배열 순서가 곧 노출 순서입니다. 별도 순서 필드는 없습니다.

3. 템플릿에서 사용: layout.html

저장된 값은 템플릿에서 $layout_info->{변수명} 으로 항목 객체 배열이 되어 들어옵니다. 노출 조건(켬/끔·기간)은 LayoutModel::getVisibleItems() 헬퍼로 거릅니다: 날짜를 직접 비교할 필요가 없습니다.

@version(2)
@php
$slides = LayoutModel::getVisibleItems($layout_info->visuals ?? []);
@endphp

@if (count($slides))
<div class="my-slider">
  @foreach ($slides as $slide)
  <div class="slide" style="background-image:url('{{ $slide->image }}')">
    <h2>{{ $slide->title }}</h2>
    @if (!empty($slide->text))<p>{{ $slide->text }}</p>@endif
    @if (!empty($slide->link_text))<a href="{{ $slide->link_url }}">{{ $slide->link_text }}</a>@endif
  </div>
  @endforeach
</div>
@endif

관리자 화면에서는 전체 항목이(꺼진 것 포함), 프론트에서는 getVisibleItems() 를 거친 항목만 보입니다.

4. 저장 형식

값은 항목 객체의 JSON 배열로 해당 레이아웃 인스턴스에 저장됩니다. 날짜는 YYYYMMDDHHIISS 형식, 이미지는 업로드된 파일 경로입니다. 직접 파싱할 일은 없지만, 내보내기·이전 도구를 만들 때 참고하세요.

5. 제약과 주의

• 반복 필드 안에 다시 반복 필드(중첩)는 지원하지 않습니다.
• 항목 수 상한은 없지만 성능을 위해 20개 안쪽을 권장합니다.
• 기존 일반 extra_var와 변수 이름이 겹치지 않게 하세요.
• 이 기능은 Zittme 고유입니다. 같은 info.xml을 라이믹스에 설치하면 반복 필드는 무시됩니다(오류는 나지 않습니다).