DataSource

이 컨트롤은 무엇인가요?

DataSource는 화면에 아무것도 그리지 않는(display: none) 데이터 저장 노드입니다. <syn_data> 태그로 선언하면 페이지 안에 이름이 있는 자바스크립트 객체(또는 배열) 저장소 하나가 만들어지고, 다른 컨트롤(TextBox, CheckBox, Grid 등)이 여기에 "바인딩"되어 값을 주고받습니다.

즉, DataSource 자체는 입력창도 버튼도 아니고, 화면의 입력 컨트롤들과 서버 전송(트랜잭션) 사이에 값을 모아두는 "그릇" 역할만 합니다.

<syn_data id="srcForm" syn-options="{
    dataSourceID: 'FormStore',
    storeType: 'Form',
    columns: [
        { data: 'Name', dataType: 'string' },
        { data: 'Age', dataType: 'number' }
    ]
}"></syn_data>

내부적으로는 columns에 정의된 각 필드에 대해 Object.defineProperty로 getter/setter가 만들어지고, 그 필드에 syn-datafield로 바인딩된 입력 컨트롤(bindingID: 'FormStore')의 getValue/setValue를 자동으로 호출해 줍니다. 그래서 "DataSource에 값을 저장한다"는 것은 실제로는 "바인딩된 화면 컨트롤의 값을 읽고 쓴다"는 뜻입니다.

언제 사용하나요?

DataSource는 storeType 옵션 값에 따라 두 가지 형태로 사용합니다.

storeType	저장 형태	사용 시점
Form (기본값)	객체 1개(단일 레코드)	상세/등록/수정 화면처럼 필드 여러 개를 한 건의 데이터로 다룰 때. TextBox, CheckBox, DropDownList 등을 bindingID로 연결
Grid (또는 리스트 계열)	배열(레코드 여러 건)	목록/그리드 화면처럼 여러 행을 다룰 때. Grid, GridList 등을 bindingID로 연결

두 경우 모두 서버 조회/저장 트랜잭션(transactConfig)의 입력(input) 또는 출력(output) 대상으로 지정해서, 조회 결과를 화면에 뿌리거나 화면에서 입력한 값을 서버로 보낼 때 중간 저장소로 사용합니다. Grid 형태에서는 각 행마다 Flag 값(R/C/U/D)으로 조회 이후 무엇이 바뀌었는지를 추적합니다.

빠른 시작

<syn_data id="srcForm" syn-options="{
    dataSourceID: 'FormStore',
    storeType: 'Form',
    columns: [
        { data: 'Name', dataType: 'string' },
        { data: 'Age', dataType: 'number' }
    ]
}"></syn_data>

<input type="text" id="txtName" syn-datafield="Name" syn-options="{bindingID: 'FormStore'}">
<input type="text" id="txtAge" syn-datafield="Age" syn-options="{editType: 'number', bindingID: 'FormStore'}">

<script src="/js/syn.loader.js"></script>

syn.loader.js 한 줄만 추가하면 필요한 CSS/JS가 자동으로 주입되고, bindingID: 'FormStore'가 지정된 입력 컨트롤들이 srcForm DataSource와 자동으로 연결됩니다.

값을 읽거나 초기화할 때는 컨트롤 API를 사용합니다.

// isAll을 true로 줘야 필드 값이 모두 채워진 전체 레코드를 돌려받습니다.
var record = syn.uicontrols.$data.getValue('srcForm', true);

// Form의 각 필드를 columns에 정의한 dataType 기본값으로 되돌립니다.
syn.uicontrols.$data.clear('srcForm');

DataSource는 setValue를 지원하지 않습니다("지원 안함"으로 구현되어 있음). 값을 바꾸려면 바인딩된 화면 컨트롤(TextBox.setValue, Grid.setValue 등)을 사용해야 DataSource에도 값이 반영됩니다.

반대로 clear()는 내부 저장소 값만 초기화할 뿐, 이미 화면에 바인딩된 입력 컨트롤의 표시 값까지 자동으로 지워주지는 않습니다.

예제 실행하기

아래 예제 파일들을 브라우저로 열어 실제 동작을 확인할 수 있습니다. (/uicontrols/DataSource/example/ 경로)

• form.html - storeType: 'Form', 입력 컨트롤과 1:1 필드 바인딩, getValue/clear 예제
• grid.html - storeType: 'Grid', 배열 데이터 바인딩과 행 추가/삭제에 따른 Flag(R/C/U/D) 변화 예제
• getset.html - getValue(elID, isAll)의 기본/전체 조회 차이, setValue 미지원, clear 동작 데모

각 예제는 <script src="/js/syn.loader.js"></script> 한 줄만으로 동작하며, 버튼을 눌러 콘솔/로그 영역에서 결과를 확인할 수 있습니다.

더 알아보기

• 자세한 옵션/메서드/이벤트 목록은 같은 폴더의 아래 API 참조 섹션를 참고하세요.
• 실제 소스는 DataSource.js, DataSource.css 파일을 참고하세요.

실전 예제 페이지

/uicontrols/DataSource/example/ 경로의 예제를 아래 iframe에서 바로 확인할 수 있습니다.

form.html

getset.html

grid.html

소스와 로드 파일

항목	내용
컨트롤	DataSource
전역 별칭	syn.uicontrols.$data
버전	v2025.9.16
소스	uicontrols/DataSource/DataSource.js
스타일	uicontrols/DataSource/DataSource.css

API 참조

syn.uicontrols.$data

마크업

DataSource는 화면에 표시되지 않는 <syn_data> 태그 하나로 선언합니다. controlLoad 시점에 el.style.display = 'none'이 자동으로 설정됩니다.

<syn_data id="srcForm" syn-options="{
    dataSourceID: 'FormStore',
    storeType: 'Form',
    columns: [
        { data: 'Name', dataType: 'string' },
        { data: 'Age', dataType: 'number' }
    ]
}"></syn_data>

• id : 페이지 내에서 이 DataSource를 가리키는 컨트롤 id(elID). getValue/clear 등 메서드 호출 시 이 값을 사용합니다.
• dataSourceID : 다른 컨트롤이 bindingID로 참조할 저장소 이름. elID와 다른 문자열이어도 됩니다.
• 값을 주고받을 화면 컨트롤(TextBox, CheckBox, Grid 등) 쪽에는 syn-datafield="<필드명>"과 syn-options="{bindingID: '<dataSourceID>'}"를 지정해야 자동으로 연결(binding)됩니다.
• 연결은 syn.uicontrols.$data.bindingSource(elID, dataSourceID)가 담당하며, bindingID 옵션이 있는 컨트롤은 자신의 controlLoad에서 이 함수를 자동으로 호출합니다. DataSource를 사용하는 페이지에서 이 함수를 직접 호출할 일은 거의 없습니다.

Options (defaultSetting)

옵션	타입/기본값	설명
dataSourceID	string, 기본 ''	이 저장소를 가리키는 이름. 다른 컨트롤의 bindingID, Grid의 bindingID 등에서 참조
storeType	string, 기본 'Form'	'Form'이면 저장소가 객체 1개(단일 레코드), 그 외('Grid' 등)면 배열(레코드 목록)로 초기화됨
columns	array, 기본 없음(직접 지정 필요)	객체 설정 형태의 배열. 필드 목록, clear() 시 되돌릴 기본값, Grid/List/Chart 바인딩 시 넘겨줄 메타데이터(fieldID, dataType)로 사용됨. defaultSetting에는 없지만 실제 동작에 필수인 옵션
dataItems	array, 기본 []	예약 옵션(현재 DataSource.js 로직에서 직접 사용되지 않음). columns를 대신 사용할 것
dataType	string, 기본 'string'	컨트롤 자체의 데이터 타입 표기(참고용)
belongID	string, 기본 null	소속 그룹/화면 식별자
getter / setter	boolean, 기본 false	페이지 훅(mod.hook.controlInit) 연동 여부
controlText	string, 기본 null	로케일 처리 대상 표시명(참고용, setLocale은 현재 빈 함수로 구현됨)
validators	array, 기본 null	폼 전송(transactConfig) 검증 규칙(참고용)
transactConfig	object, 기본 null	트랜잭션(서버 전송) 연동 설정. inputs/outputs에 객체 설정 형태로 지정해 조회/저장 버튼과 연결
triggerConfig	object, 기본 null	트리거 옵션 연동 설정(참고용)

메서드

메서드	매개변수	설명
controlLoad(elID, setting)	요소 id, 옵션 객체	컨트롤 초기화(내부적으로 페이지 로드 시 자동 호출됨). 저장소를 storeType에 맞춰 {} 또는 []로 만들고 storeList에 메타 정보(dataSourceID, storeType, columns)를 등록
getValue(elID, isAll)	요소 id, 전체조회 여부(boolean, 기본 false)	저장소 값을 반환. isAll이 true면 저장소 원본을 그대로 반환. false(기본)이면 배열(Grid)은 Flag !== 'R'인 행만 걸러서 반환하고, 객체(Form)는 값이 객체 타입인 필드만 남기므로 필드 대부분이 문자열/숫자/불린인 일반적인 Form에서는 isAll: true로 호출하는 것을 권장
setValue(elID, value, meta)	-	지원하지 않음(빈 구현). 값을 바꾸려면 bindingID로 연결된 화면 컨트롤의 setValue를 사용해야 함(예: syn.uicontrols.$textbox.setValue('txtName', '홍길동'))
clear(elID, isControlLoad)	요소 id	storeType: 'Form'이면 columns에 정의된 각 필드를 dataType에 맞는 기본값(string→'', number/numeric/int→0, bool/boolean→false, 그 외→null)으로 되돌림. 배열(Grid)이면 length = 0으로 비움. 내부 저장소 값만 초기화하며, 이미 바인딩된 화면 컨트롤(TextBox 등)의 표시 값은 자동으로 지워지지 않음(clear 동작 중에는 바인딩 반응이 꺼져 있음)
getMetaStore(elID)	요소 id	storeList에 등록된 메타 정보(dataSourceID, storeType, columns) 조회
bindingSource(elID, dataSourceID)	필드 컨트롤 id, dataSourceID	필드 컨트롤(syn-datafield 지정)과 DataSource를 연결하고 Object.defineProperty로 getter/setter를 등록. bindingID 옵션이 있는 컨트롤이 자신의 controlLoad에서 자동 호출함
reactionGetValue / reactionSetValue	(내부용)	바인딩된 필드에 접근(get/set)할 때 실제로 연결된 컨트롤의 getValue/setValue를 호출해 주는 내부 구현. 직접 호출할 필요 없음
setLocale(elID, translations, control, options)	-	현재 빈 함수로 구현되어 있어 동작 없음

이벤트 (syn-events)

DataSource는 화면에 표시되지 않는 저장 노드이므로 syn-events로 연결할 DOM 이벤트가 없습니다. 값 변화에 반응하려면 값을 실제로 입력/변경하는 화면 컨트롤(TextBox, Grid 등) 쪽에 syn-events를 지정하세요.

참고

• Flag(R/C/U/D) 변경 추적 컨벤션: Grid처럼 storeType이 배열인 저장소는 각 행에 Flag 필드를 가집니다.
  • R (Read) : 조회 결과 그대로인 원본 행. getValue(elID)(기본, isAll 생략)를 호출하면 이 행들은 결과에서 제외됩니다.
  • C (Create) : 화면에서 새로 추가한 행(Grid의 insertRow 등으로 생성).
  • U (Update) : 원본(R) 행의 값을 수정하면 R에서 U로 바뀝니다.
  • D (Delete) : 원본/수정된 행을 삭제 표시한 경우. 실제로 배열에서 즉시 제거되지 않고 Flag만 D로 바뀌는 경우가 많아, 서버 저장 트랜잭션에서 D 행을 삭제 대상으로 판단합니다.
  • Flag 값 관리 자체는 Grid 계열 컨트롤(예: syn.uicontrols.$grid)이 담당하며, DataSource는 getValue(elID) 호출 시 Flag !== 'R' 조건으로 걸러주는 역할만 합니다.
• columns는 defaultSetting에 명시되어 있지 않지만 controlLoad, clear, Grid/List 바인딩 메타 변환(reactionGetValue/reactionSetValue)에서 실제로 사용되므로 반드시 지정해야 합니다.
• 예제는 example 폴더, 사용 개요는 이 문서의 사용법 섹션를 참고하세요.