> ## Documentation Index
> Fetch the complete documentation index at: https://make.edicus.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 변수와 데이터 병합
> 글상자와 QR 코드에 변수를 만드는 두 방식, 변환 결과, 편집기와 TnView와 VDP 주문에서 쓰이는 방식
변수는 데이터마다 내용이 달라지는 개체입니다. 이런 인쇄 방식을 VDP(가변 데이터 인쇄)라고 부릅니다. 이름과 직함만 다른 명함 100장을 한 템플릿으로 뽑을 때 씁니다. 템플릿에서 변수를 만드는 방법은 둘입니다. 글상자 전체를 바꾸는 **어노테이션 방식**과, 문장 안의 일부만 바꾸는 **데이터 병합(data merge) 방식**입니다.
## 배우는 것
* 두 방식으로 변수를 만드는 정확한 문법
* 데이터를 넣었을 때 글자와 서식이 바뀌는 규칙
* 빈 값일 때 글자와 줄을 지우는 방법
* 편집기, TnView, VDP 주문에서 변수가 쓰이는 곳
## 두 방식 비교
| | 어노테이션 방식 | 데이터 병합 방식 |
| - | - | - |
| 만드는 곳 | 개체 이름 | InDesign **데이터 병합** 패널의 필드 |
| 바뀌는 범위 | 글상자 전체 | 필드 자리만 |
| 변수 id | `#` 뒤의 이름 또는 `var_id` | 데이터 병합 필드 이름 |
| 주입할 때 | `segment`를 주지 않습니다 | `segment: true`를 줍니다 |
## 어노테이션 방식
`Text` 레이어 글상자의 **개체 이름**을 아래처럼 짓습니다. 개체 이름은 **레이어** 패널에서 바꿉니다.
```text theme={null}
#name@title=이름
```
* `#` 뒤가 변수 id입니다. 위 예는 `name`입니다.
* `title`은 편집기 입력 칸에 보일 제목입니다. 없어도 됩니다.
id에 하이픈(`-`)이 필요하면 `var_id`를 씁니다. `#` 방식은 하이픈에서 이름을 잘라 `#title-role`의 id가 `title`이 됩니다.
```text theme={null}
직함칸@var_id=title-role,var_title=직함
```
| 규칙 | 설명 |
| - | - |
| 둘 다 쓴 경우 | `#` 이름이 이깁니다. 한 개체에는 한 방식만 씁니다 |
| 금지 문자 | 값에 `,` `:` `=` `@`를 쓰지 않습니다. 이 문자는 문법 구분에 쓰입니다 |
| 같은 id | 여러 글상자에 같은 id를 주면 같은 값이 모두에 들어갑니다 |
변수를 단 글상자도 일반 글상자처럼 편집할 수 있습니다. 문법 전체는 [어노테이션](/docs/templates/annotations)에 있습니다.
### 값을 넣으면
글상자의 글자 전체가 넣은 값으로 바뀝니다.
* 바뀐 글자는 모두 **원래 첫 글자의 서식**을 따릅니다. 글자마다 서식이 다른 글상자를 통째로 바꾸면 첫 글자 서식만 남습니다.
* 값에 줄바꿈(`\n`)을 넣으면 단락이 나뉩니다.
## 데이터 병합 방식
**창** > **유틸리티** > **데이터 병합** 패널에서 CSV나 텍스트 데이터 원본을 고릅니다. 첫 행의 열 이름이 필드 이름이 되고, 이 이름이 변수 id입니다.
`Text` 레이어 글상자에서 바꿀 자리에 필드를 넣습니다. 고정 글자와 필드를 한 글상자에 섞어도 됩니다. 필드 모양의 글자를 손으로 치면 필드로 인식되지 않습니다.
글상자 이름을 `#field1@stitle=이름/직함/부서`처럼 짓습니다. `stitle`은 필드마다 붙일 제목을 `/`로 나눈 것입니다. 글상자에 나오는 필드 순서대로 붙습니다.
익스포트할 때 글상자에 보이는 글자가 그대로 기본 글자가 됩니다. **데이터 병합** 패널의 **미리 보기**를 켜 두면 첫 레코드 값이 기본 글자가 됩니다.
`stitle`은 `#` 이름이 있어야 읽힙니다. 그래서 데이터 병합 글상자에도 `#` 이름을 붙입니다.
연동 담당자에게 전달: 편집기가 문서를 열거나 바꿀 때 보내는 `doc-changed` 이벤트에는 문서에 든 변수 목록(`vdp_catalog`)이 담깁니다. `#` 이름이 없는 데이터 병합 글상자는 필드가 동작해도 편집기의 이 목록에 나오지 않습니다.
### 값을 넣으면
* 필드 자리만 바뀌고 나머지 고정 글자는 그대로입니다.
* 넣은 글자는 **필드 첫 글자의 서식**을 따릅니다. 필드마다 InDesign에서 서식을 따로 줘 둡니다.
### 빈 값일 때 함께 지울 글자
빈 값(`""`)을 넣으면 필드 자리가 지워집니다. 필드 앞뒤의 고정 글자도 같이 지우려면 InDesign 글상자에서 그 범위를 백틱(`` ` ``)으로 감쌉니다.
```text theme={null}
`Tel. «f_tel» ``Fax. «f_fax»`
```
InDesign 글상자에서는 `` `Tel. `` 다음에 `f_tel` 필드, 공백 두 칸, 백틱 두 개, `Fax. `, `f_fax` 필드, 백틱 하나가 한 줄로 이어진 모습입니다. 백틱 두 개가 붙은 곳은 앞 범위가 닫히고 뒤 범위가 열리는 자리입니다.
`f_tel`이 비면 첫 백틱 쌍 안의 `Tel. `부터 공백까지가 모두 지워지고, `Fax.` 부분은 남습니다. 백틱 문자는 변환할 때 사라집니다.
한 줄에 있는 필드가 모두 비면 그 줄이 통째로 지워지고 아래 줄이 올라옵니다. 세로 정렬이 아래쪽인 글상자에서는 위 줄이 내려옵니다.
### 글자 수에 따른 자간
필드에 들어가는 글자 수에 따라 자간을 바꾸려면 `DataRule` 레이어에 개체를 하나 두고 이름을 아래처럼 짓습니다.
```text theme={null}
name@letter_space=0:0/4:-50/6:-100
```
* `@` 앞은 데이터 병합 필드 이름입니다.
* `글자수:자간`을 `/`로 잇습니다. 넣은 글자 수가 `글자수` 이상인 항목 중 **마지막에 적은 항목**이 적용됩니다. 그래서 글자 수가 작은 것부터 적습니다. 위 예는 3자까지 0, 4\~5자 -50, 6자 이상 -100입니다.
* 자간 단위는 InDesign 자간과 같은 1/1000em입니다. 값은 정수만 씁니다.
* 형식이 틀리면 변환 자체가 실패합니다.
`DataRule` 레이어는 숨기지 않습니다. 이 개체는 페이지에 그려지지 않습니다.
## QR 코드 변수
`Sticker` 레이어에 QR 코드 자리 그림을 두고 이름을 `#qr@qrcode=https://example.com`처럼 짓습니다. 변수 `qr`에 글자 값을 넣으면 그 글자로 만든 QR 코드가 그려집니다. 값을 넣지 않으면 InDesign에서 둔 그림이 그대로 나옵니다.
## 편집기에서 변수가 쓰이는 곳
| 기능 | 템플릿 쪽 조건 | 하는 일 |
| - | - | - |
| 이름 넣기 탭(`name-tab`) | 현재 페이지의 `Text` 레이어 글상자에 어노테이션 변수 | 변수마다 입력 칸을 보여 줍니다. 칸 제목은 `title`입니다. 글자, 폰트, 색을 바꿉니다 |
| 변수 탭(`var-tab`) | `Guide` 레이어처럼 선택할 수 없는 안내 개체(글자나 도형)에 어노테이션 변수 | 상품 설정 `var command`에 묶은 변수들의 글자색이나 칠 색을 한 번에 바꿉니다. 일반 `Text` 레이어 글상자는 대상이 아닙니다 |
| VDP 모드(`run_mode: 'vdp'`) | 데이터 병합 필드 | 여러 명의 데이터를 입력받는 화면을 엽니다. 입력 칸 제목은 `stitle`입니다 |
탭을 켜는 설정과 `var command` 형식은 [탭 구성](/docs/products/editor-tabs)과 [사진과 글자 편집 범위](/docs/products/photo-text)에 있습니다.
## TnView와 VDP 주문에 넣기
TnView는 편집기 없이 템플릿이나 프로젝트를 썸네일로만 보여 주는 화면입니다. 개발자는 TnView 미리 보기와 VDP 주문에 변수 id로 값을 넣습니다. 형식은 [TnView와 VDP](/docs/sdk/tnview#가변-데이터-주입)와 [주문](/docs/server/orders-vdp)에 있습니다.
연동 담당자에게 전달: 아래는 값을 넣는 데이터 한 행의 예입니다.
```json theme={null}
{ "cols": [
{ "id": "name", "value": { "text": "홍길동" }, "shrink": true },
{ "id": "f_tel", "segment": true, "value": { "text": "" } }
] }
```
| 필드 | 템플릿과의 관계 |
| - | - |
| `id` | 어노테이션 변수 id 또는 데이터 병합 필드 이름입니다 |
| `segment` | 데이터 병합 필드에 줍니다. 어노테이션 변수에 주면 TnView에서 반영되지 않습니다 |
| `shrink` | `true`면 단락마다 한 줄에 들어가도록 장평을 줄입니다. 한 줄에 이미 들어가면 그대로 둡니다. 데이터 병합 글상자는 그 글상자에 넣는 모든 필드에 `true`를 줘야 적용됩니다 |
사진 칸에도 변수 id를 달 수 있지만, 주문 렌더링은 사진 칸 변수를 바꾸지 않습니다. 도형(`Path`)에 단 변수의 칠 색은 PDF 렌더링에서만 바뀝니다. VDP 주문에는 글자 변수와 QR 코드 변수를 기본으로 씁니다.
제작자는 개발자에게 아래를 넘깁니다.
| 넘길 것 | 예 |
| - | - |
| 상품과 템플릿 | `ps_code`, Edicus Manager에서 복사한 `resUri` |
| 변수 id와 방식 | `name`(어노테이션), `f_tel`(데이터 병합) |
| 빈 값 처리 | 백틱으로 함께 지우는 범위, 줄 삭제 여부 |
| 입력 제약 | 최대 글자 수, 줄 수, `shrink` 필요 여부 |
## 됐는지 확인
TnView는 연동 코드로 띄우는 화면이라 제작자 혼자서는 열 수 없습니다. 개발자에게 TnView에서 짧은 값, 긴 값, 빈 값을 넣어 테스트해 달라고 요청하고, 글자가 바뀌고 빈 필드의 줄과 범위가 지워지는지 함께 확인하면 됩니다. 같은 데이터로 테스트 주문을 넣어 생산 파일도 비교합니다.
## 다음 단계
실제 생산 파일로 변수를 확인합니다.
개발자가 값을 넣는 방법을 봅니다.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.