빠른 시작
몇 분 안에 Walla 커스텀 필드를 만들어 보세요
빠른 시작
이 가이드에서는 Walla 폼 빌더에 연동되는 색상 선택기를 예제로, 첫 커스텀 필드를 만드는 과정을 안내합니다.
사전 준비사항
- 워크스페이스가 있는 Walla 계정
- HTML과 JavaScript 기본 지식
- 정적 HTML을 호스팅할 수 있는 환경 (웹 서버, CDN, 호스팅 서비스 등)
1단계: SDK 설치
옵션 A: npm (번들 프로젝트 권장)
npm install @wallaform/custom-field-sdk옵션 B: CDN (단일 HTML 파일용)
<script type="module">
import { WallaField } from 'https://esm.sh/@wallaform/custom-field-sdk';
</script>SDK는 ESM 전용입니다.
<script type="module">또는 번들러(Vite, webpack, esbuild 등)를 사용하세요.
2단계: 필드 만들기
색상 선택기가 포함된 index.html 파일을 생성합니다:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: system-ui; padding: 12px; }
.swatches { display: flex; gap: 8px; flex-wrap: wrap; }
.swatch {
width: 36px; height: 36px; border-radius: 8px;
border: 2px solid transparent; cursor: pointer;
}
.swatch.selected { border-color: var(--primary, #007eff); }
.custom-input {
margin-top: 12px; display: flex; align-items: center; gap: 8px;
}
.custom-input input[type="color"] {
width: 36px; height: 36px; border: none; cursor: pointer;
}
.custom-input span {
font-size: 14px; color: var(--fg, #333);
}
</style>
</head>
<body>
<div class="swatches" id="swatches"></div>
<div class="custom-input">
<input type="color" id="picker" value="#007EFF" />
<span id="hex">#007EFF</span>
</div>
<script type="module">
import { WallaField } from 'https://esm.sh/@wallaform/custom-field-sdk';
const field = new WallaField({ debug: true });
const presets = ['#FF6B6B','#4ECDC4','#45B7D1','#96CEB4','#FFEAA7','#DDA0DD','#007EFF','#2D3436'];
let selectedColor = '#007EFF';
// Render preset swatches
const swatchesEl = document.getElementById('swatches');
presets.forEach(color => {
const el = document.createElement('div');
el.className = 'swatch';
el.style.background = color;
el.addEventListener('click', () => selectColor(color));
swatchesEl.appendChild(el);
});
// Custom color picker
const pickerEl = document.getElementById('picker');
const hexEl = document.getElementById('hex');
pickerEl.addEventListener('input', (e) => selectColor(e.target.value));
function selectColor(color) {
selectedColor = color;
pickerEl.value = color;
hexEl.textContent = color.toUpperCase();
// Update swatch selection UI
document.querySelectorAll('.swatch').forEach(el => {
el.classList.toggle('selected', el.style.background === color);
});
// Report value to host — auto-saved on every call
field.setValue(color);
}
// 1. Receive initialization data
field.onInit(({ value, theme, properties }) => {
// Apply form theme
document.documentElement.style.setProperty('--primary', theme.primary);
document.documentElement.style.setProperty('--fg', theme.foreground);
document.body.style.fontFamily = theme.fontFamily;
document.body.style.background = theme.background;
// Restore saved value
if (value) {
selectColor(value);
}
// Resize iframe to fit content
field.setHeight(document.body.scrollHeight);
});
// 2. Handle validation
field.onValidate((submitType) => {
if (!selectedColor) {
return { valid: false, errors: [{ message: 'Please select a color' }] };
}
return { valid: true };
});
</script>
</body>
</html>3단계: 로컬에서 테스트
정적 서버로 파일을 서빙합니다:
npx serve -l 4567 .http://localhost:4567/index.html에서 필드를 확인할 수 있습니다.
현재 독립형 테스트 하네스는 제공되지 않습니다. 폼 내에서 테스트하려면 Walla 대시보드에 필드를 등록해야 합니다. 로컬 개발용 목(mock) 호스트는 향후 릴리스에 포함될 예정입니다.
4단계: 배포
HTML 파일을 공개적으로 접근 가능한 URL에 호스팅합니다. 몇 가지 옵션을 소개합니다:
- 정적 호스팅: Vercel, Netlify, Cloudflare Pages, GitHub Pages
- CDN: 퍼블릭 접근이 가능한 CDN 또는 클라우드 스토리지에 업로드
- 자체 서버: 정적 파일을 서빙할 수 있는 웹 서버
배포한 URL이 Walla 대시보드에 등록하는 렌더 URL이 됩니다.
5단계: Walla에 등록
참고: 현재 커스텀 필드 타입 등록은 셀프 서비스로 제공되지 않습니다. 새로운 커스텀 필드 타입을 등록하려면 Walla 팀에 문의하여 사용 사례를 논의하고 함께 설정해야 합니다.
Walla 팀을 통해 커스텀 필드 타입이 등록되면, 폼 빌더의 커스텀 필드 탭에서 해당 필드를 폼에 추가할 수 있습니다.
코드 이해하기
주요 부분을 살펴보겠습니다.
생성자
const field = new WallaField({ debug: true });새 필드 인스턴스를 생성합니다. SDK가 자동으로:
- URL 쿼리 파라미터에서
fieldId를 추출합니다 (?fieldId=xxx) - 호스트가
MessagePort를 전달할 때까지 대기합니다 - RPC 세션을 수립합니다
debug 옵션을 켜면 모든 RPC 메시지가 브라우저 콘솔에 출력됩니다 — 개발 중에 유용합니다.
콜백
field.onInit(callback) // Receive config, theme, saved value
field.onValidate(callback) // Respond to validation requests콜백은 연결이 수립되기 전에 등록합니다. 호스트가 연결하고 init()을 호출하면 전체 초기화 페이로드와 함께 콜백이 실행됩니다.
액션
field.setValue(color) // Report value changes
field.setHeight(document.body.scrollHeight) // Resize iframe이 메서드들은 호스트로 RPC 호출을 전송합니다. setValue()는 매 호출마다 호스트가 자동으로 저장합니다 (50ms 디바운스). setHeight()는 iframe 높이를 조절합니다 (100ms 스로틀, 0–5000px 범위 제한).