CodePicker

이 컨트롤은 무엇인가요?

CodePicker는 "코드값 검색 팝업" 패턴을 구현한 UI 컨트롤입니다. 하나의 <syn_codepicker> 태그를 화면에 배치하면, 컨트롤이 초기화되면서 실제로는 아래 3개의 엘리먼트로 확장됩니다.

• <id>_Code : 실제 값(코드값)을 담는 입력창
• <id>_Text : 코드값에 해당하는 이름(텍스트)을 보여주는 입력창
• <id>_Button : 돋보기 아이콘 버튼. 클릭하면 검색 팝업(코드도움 다이얼로그)이 열립니다.

사용자가 돋보기 버튼을 누르거나 _Code/_Text 입력창에서 Enter를 치면, syn.uicontrols.$codepicker.find()가 호출되어 dataSourceID로 지정한 데이터소스를 검색할 수 있는 팝업창(codeHelpUrl, 기본적으로 /assets/shared/codehelp/index2.html)을 띄웁니다. 팝업에서 항목을 선택하면 그 결과가 다시 _Code(코드값)와 _Text(코드명)에 채워집니다.

즉, CodePicker는 "화면에 코드 목록을 미리 다 그려놓는" 방식이 아니라, "필요할 때 팝업으로 검색해서 하나(또는 여러 개)를 골라오는" 방식의 컨트롤입니다. 컨트롤 자체 외에도 Handsontable 기반 WebGrid의 커스텀 셀 타입(registerCellType('codehelp', ...))으로도 동일한 팝업 검색 기능을 사용할 수 있지만, 이 문서는 단독 입력 컨트롤로 사용하는 방법을 기준으로 설명합니다.

언제 사용하나요?

• DropDownList ($select): 코드값 개수가 적당히 적고(수십 개 이내), 화면에 옵션을 미리 다 나열해도 괜찮은 경우에 사용합니다. 성별, 지역, 상태값처럼 "목록에서 하나 고르기"에 적합합니다.
• CodePicker ($codepicker): 코드값(마스터 데이터)이 매우 많거나(예: 거래처, 상품, 사용자 목록), 조건을 입력해서 검색한 뒤 골라야 하는 경우에 사용합니다. 드롭다운으로 나열하기엔 항목이 너무 많을 때 적합한 선택입니다.

정리하면, "옵션 개수가 적으면 DropDownList, 많고 검색이 필요하면 CodePicker"가 기본 기준입니다.

빠른 시작

1. 페이지에 <syn_codepicker> 태그를 배치하고 id, syn-datafield, syn-options 속성을 지정합니다.

<syn_codepicker id="chpCompanyID" syn-datafield="CompanyID" syn-options="{
    belongID: 'LD01',
    dataSourceID: 'BDLCHP011',
    local: false,
    isMultiSelect: false,
    textBelongID: ['LD01'],
    textDataFieldID: 'CompanyName',
    controlText: '업체 명'
}"></syn_codepicker>

2. 페이지 하단에 syn.loader.js 스크립트 한 줄만 추가하면, 로더가 필요한 CSS/JS(CodePicker.js, CodePicker.css 등)를 자동으로 주입하고 컨트롤을 초기화합니다.

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

3. 값을 읽거나 설정할 때는 페이지 스크립트에서 syn.uicontrols.$codepicker를 사용합니다.

// 코드값 조회
var value = syn.uicontrols.$codepicker.getValue('chpCompanyID');

// 코드값 직접 설정
syn.uicontrols.$codepicker.setValue('chpCompanyID', '1000');

// 검색 팝업을 코드로 직접 여는 방법(돋보기 버튼 클릭과 동일)
syn.uicontrols.$codepicker.open('chpCompanyID');

예제 실행하기

이 폴더의 example 디렉토리에 초보자용 실행 예제가 있습니다. 웹 서버를 통해 /uicontrols/CodePicker/example/*.html 경로로 접속해서 바로 확인할 수 있습니다.

• basic.html: CodePicker를 배치하고 돋보기 버튼으로 검색 팝업을 여는 가장 단순한 예제
• events.html: change 이벤트로 선택 결과를 로그로 확인하고, getValue/setValue/setText/clear API를 함께 보여주는 예제

각 예제는 <script src="/js/syn.loader.js"></script> 한 줄만으로 동작하도록 만들어졌습니다.

주의: 실제 팝업 검색 화면(codeHelpUrl)은 서버에 등록된 dataSourceID가 실제 데이터를 응답해야 정상적으로 항목이 표시됩니다. 예제 화면 자체는 CodePicker 컨트롤의 마크업/이벤트/API 사용법을 보여주는 데 초점을 맞췄습니다.

더 알아보기

• 전체 옵션(Options), 메서드, 이벤트 목록은 같은 폴더의 아래 API 참조 섹션 문서를 참고하세요.
• 실제 소스 코드는 CodePicker.js 파일에서 확인할 수 있습니다.
• 팝업 검색 화면 자체(코드도움 다이얼로그, index2.html)의 동작은 이 컨트롤의 범위 밖이며, 서버 쪽 데이터소스(dataSourceID) 설정과 함께 별도로 관리됩니다.

실전 예제 페이지

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

basic.html

events.html

소스와 로드 파일

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

API 참조

syn.uicontrols.$codepicker

CodePicker는 코드값 검색 팝업 패턴을 구현한 컨트롤입니다. 아래 내용은 1.WebHost/rdy/modules/wwwroot/wwwroot/uicontrols/CodePicker/CodePicker.js 소스 코드를 기준으로 정리했습니다.

마크업

<syn_codepicker id="chpCompanyID" syn-datafield="CompanyID" syn-options="{
    belongID: 'LD01',
    dataSourceID: 'BDLCHP011',
    local: false,
    codeElementClass: 'hidden',
    isMultiSelect: false,
    textBelongID: ['LD01'],
    textDataFieldID: 'CompanyName',
    controlText: '업체 명'
}"></syn_codepicker>

controlLoad가 실행되면 원래의 <syn_codepicker id="chpCompanyID"> 태그는 id="chpCompanyID_hidden"으로 이름이 바뀌고 display: none으로 숨겨진 뒤, 그 자리에 다음 3개의 실제 엘리먼트가 순서대로 생성됩니다.

엘리먼트 id	역할
<id>_Code	코드값(실제 값)을 담는 <input type="text">. syn-datafield가 지정되어 있으면 이 값이 폼 데이터 필드와 연결됩니다.
<id>_Text	코드값에 대응하는 이름(텍스트)을 보여주는 <input type="text">. textDataFieldID가 있으면 그 필드와 연결됩니다.
<id>_Button	돋보기 아이콘 버튼(<button>). 클릭하면 검색 팝업이 열립니다.

• codeElementClass: 'hidden'처럼 지정하면 _Code 입력창을 화면에서 숨기고 _Text만 보여주는 형태로 구성할 수 있습니다(값은 여전히 _Code에 저장됨).
• getValue/setValue는 항상 _Code(코드값) 기준으로 동작하고, 화면에 보이는 이름은 setText로 별도 제어합니다.
• syn-options는 JavaScript 객체 리터럴 문자열이며 defaultSetting을 덮어씁니다.

Options (defaultSetting)

옵션	타입	기본값	설명
dataSourceID	string | null	null	검색 팝업이 조회할 데이터소스 ID. 필수값이며, 지정하지 않으면 find() 호출 시 콘솔에 디버그 로그만 남기고 팝업이 열리지 않습니다.
storeSourceID	string | null	null	데이터 캐시 키. 지정하지 않으면 dataSourceID 값을 그대로 사용합니다.
local	boolean	true	팝업(코드도움 화면) 쪽에서 로컬/원격 데이터소스 여부를 판단하는 데 사용되는 값입니다.
parameters	string	''	검색 팝업에 전달할 조회 조건 문자열(@Key:Value; 형태). @ApplicationID, @CompanyNo, @LocaleID는 지정하지 않아도 find()가 자동으로 앞에 추가합니다.
label / labelWidth	string	''	라벨 텍스트 및 너비(용도별 커스텀 표시에 사용).
codeElementID	string	''	_Code 엘리먼트 id. find() 호출 시 내부적으로 <elID>_Code로 자동 설정됩니다.
codeElementWidth	string	''	_Code 입력창 너비(CSS 값, 예: '120px').
codeElementClass	string	''	_Code 입력창에 추가할 CSS 클래스(예: 'hidden'으로 지정하면 코드값 입력창을 화면에서 숨김).
textElementID	string	''	_Text 엘리먼트 id. find() 호출 시 내부적으로 <elID>_Text로 자동 설정됩니다.
textElementWidth	string	''	_Text 입력창 너비(CSS 값).
textElementClass	string	''	_Text 입력창에 추가할 CSS 클래스.
required	boolean	false	true면 _Code, _Text 입력창에 required 속성을 추가합니다.
readonly	boolean	false	true면 _Code, _Text 입력창을 읽기 전용으로 만듭니다(팝업은 여전히 열 수 있음).
disabled	boolean	false	true면 _Code, _Text 입력창을 비활성화합니다.
textBelongID	string | string[] | null	null	_Text 입력창 내부 textbox 컨트롤의 belongID(다국어/그룹 식별용). 배열도 지정 가능합니다.
textDataFieldID	string | null	null	_Text 입력창에 연결할 syn-datafield 이름(코드명을 저장할 폼 필드).
searchValue / searchText	string	''	팝업을 열 때 초기 검색어로 전달되는 값(코드값/코드명). 버튼 클릭 시 현재 _Code/_Text 값으로 자동 갱신됩니다.
isMultiSelect	boolean	false	true면 팝업에서 여러 항목을 선택할 수 있고, 선택 결과가 콤마(,)로 연결된 문자열로 _Code/_Text에 채워집니다.
isAutoSearch	boolean	true	팝업 화면 자체의 자동 검색 여부(코드도움 화면 쪽 동작에 사용되는 전달값).
isSingleAutoReturn	boolean	true	단일 결과일 때 팝업에서 바로 자동으로 선택 처리할지 여부(코드도움 화면 쪽 동작에 사용되는 전달값).
isOnlineData	boolean	false	온라인(실시간) 데이터 여부 플래그(코드도움 화면 쪽 동작에 사용되는 전달값).
viewType	string	''	선택 결과를 어디에 반영할지 지정. find() 내부에서 폼 컨트롤이면 'form', WebGrid 셀이면 'grid', AUIGrid 셀이면 'auigrid'로 자동 설정됩니다.
sharedAssetUrl	string	''	공용 자원 기준 경로. 비어 있으면 syn.Config.SharedAssetUrl을 사용합니다.
dataType	string	'string'	값의 데이터 타입.
belongID	string | string[] | null	null	_Code 입력창 내부 textbox 컨트롤의 belongID(다국어/그룹 식별용). 배열도 지정 가능합니다.
getter / setter	boolean	false	값 조회/설정 시 커스텀 훅 사용 여부.
controlText	string | null	null	검색 팝업 다이얼로그의 제목(caption)에 사용됩니다. 지정하지 않으면 columnText → headerText → dataSourceID 순으로 대체됩니다.
validators	object | null	null	유효성 검사 규칙.
transactConfig / triggerConfig	object | null	null	트랜잭션/트리거 연동 설정.

메서드

메서드	설명
controlLoad(elID, setting)	컨트롤 초기화. _Code/_Text/_Button 엘리먼트를 생성하고 이벤트를 바인딩합니다. 보통 페이지 로더가 자동으로 호출하므로 직접 호출할 일은 거의 없습니다.
find(setting, callback)	검색 팝업(코드도움 다이얼로그)을 엽니다. dataSourceID가 없으면 동작하지 않습니다. 팝업에서 선택이 끝나면 viewType에 따라 _Code/_Text(form), WebGrid 셀(grid), AUIGrid 셀(auigrid)에 결과를 반영하고 callback(result)을 호출합니다. 돋보기 버튼 클릭 시 내부적으로 자동 호출됩니다.
open(elID)	돋보기 버튼(<elID>_Button) 클릭을 코드로 트리거해서 검색 팝업을 엽니다.
getValue(elID, meta)	<elID>_Code의 현재 값(코드값)을 반환합니다.
setValue(elID, value, meta)	<elID>_Code에 코드값을 직접 설정합니다. (코드명 _Text는 함께 바뀌지 않으므로 필요하면 setText를 같이 호출)
setText(elID, value, meta)	<elID>_Text에 코드명(표시 텍스트)을 직접 설정합니다.
clear(elID, isControlLoad)	_Code와 _Text 값을 모두 빈 문자열로 초기화합니다.
toParameterString(jsonObject)	객체 설정 형태의 객체를 '@Key:Value;' 형태의 파라미터 문자열로 변환합니다.
toParameterObject(parameters)	'@Key:Value;' 형태의 파라미터 문자열을 객체 설정 객체로 변환합니다.
setLocale(elID, translations, control, options)	다국어(로케일) 텍스트 적용용 훅(현재 구현은 비어 있음).

이벤트 (syn-events)

CodePicker는 컨트롤 자체에 별도의 커스텀 이벤트 시스템을 두지 않고, 페이지 스크립트의 event 객체에 정의한 핸들러를 컨트롤 내부 로직이 직접 찾아서 호출하는 방식으로 동작합니다.

핸들러 이름	호출 시점	인자
<elID>_change(value, text, result)	_Code/_Text 입력창에서 값이 바뀌었을 때(Enter가 아닌 일반 변경), 또는 검색 팝업에서 선택을 완료했을 때	value: 코드값, text: 코드명, result: 팝업에서 선택 완료 시 선택된 원본 데이터 배열(직접 입력으로 바뀐 경우는 null)
<elID>_buttonClick(elID, synOptions)	돋보기 버튼을 클릭해서 팝업이 열리기 직전	elID: 컨트롤 id, synOptions: 팝업에 전달될 설정값(현재 _Code/_Text 값 포함)

또한 mod.hook.frameEvent(eventName, jsonObject) 훅이 정의되어 있으면 다음 시점에 호출됩니다.

eventName	호출 시점
'codeInit'	find() 실행 직전, 팝업에 전달할 설정을 보완할 수 있는 시점
'codeReturn'	팝업에서 선택을 완료해 결과가 반영된 직후 (객체 설정 전달)

일반적인 _Code/_Text 입력창은 keydown, change 이벤트가 항상 바인딩되어 있으며, 페이지 마크업의 syn-events 속성에 지정한 이벤트가 있으면 그대로 추가됩니다.

<syn_codepicker id="chpCompanyID" syn-events="['change']" syn-options="{...}"></syn_codepicker>

event: {
    chpCompanyID_change(value, text, result) {
        syn.$l.eventLog('chpCompanyID_change', JSON.stringify({ value, text, result }));
    },

    chpCompanyID_buttonClick(elID, synOptions) {
        syn.$l.eventLog('chpCompanyID_buttonClick', elID);
    }
}

참고: 팝업 콜백/선택 결과 처리 방식

1. 사용자가 돋보기 버튼(<elID>_Button)을 클릭하거나 _Code/_Text 입력창에서 Enter를 누르면 _Button의 click 이벤트가 발생합니다.
2. click 핸들러는 <elID>_hidden 엘리먼트의 syn-options를 읽어 현재 설정값(synOptions)을 만들고, elID, viewType: 'form', codeElementID, textElementID, 그리고 현재 _Code/_Text 값을 채워 넣습니다.
3. mod.event[<elID>_buttonClick]이 있으면 먼저 호출됩니다.
4. syn.uicontrols.$codepicker.find(synOptions, callback)가 실행되어 syn.$w.showUIDialog로 검색 팝업(codeHelpUrl + ?parameterID=...)을 엽니다. 이때 @ApplicationID, @CompanyNo, @LocaleID 파라미터가 parameters에 자동으로 추가됩니다.
5. 팝업에서 사용자가 항목을 선택하고 닫으면, showUIDialog의 콜백으로 선택된 배열(result, 각 원소는 { value, text, ... } 형태)이 전달됩니다.
   • isMultiSelect: false이면 result[0]의 value/text만 사용합니다.
   • isMultiSelect: true이면 모든 항목의 value/text를 콤마(,)로 이어붙입니다.
6. viewType이 'form'이면 _Code/_Text 입력창에 값을 바로 채워 넣습니다('grid'/'auigrid'이면 해당 그리드 셀에 반영).
7. mod.event[<elID>_change]가 있으면 (value, text, result)와 함께 호출되고, mod.hook.frameEvent가 있으면 'codeReturn' 이벤트로도 알림을 받습니다.
8. 마지막으로 find()의 3번째 인자로 넘긴 callback(result)이 호출됩니다.

팝업 화면(index2.html) 자체는 서버에 등록된 dataSourceID가 실제 데이터를 반환해야 정상적으로 목록이 표시됩니다. 개발 환경에서 데이터소스가 구성되어 있지 않다면, 팝업 대신 setValue/setText로 값을 직접 넣어 화면 흐름만 확인할 수 있습니다.