TextButton

이 컨트롤은 무엇인가요?

TextButton은 <input type="button"> (또는 type="submit", type="reset") 요소를 syn.uicontrols 프레임워크가 인식하는 표준 컨트롤로 만들어주는 가장 단순한 컨트롤입니다.

버튼 자체에 새로운 태그나 화려한 UI를 추가하지는 않습니다. 대신 다음 두 가지 역할을 합니다.

1. syn-options 속성에 적힌 설정값을 읽어 버튼에 적용하고, 필요하면 btn, btn-{color} 같은 클래스를 자동으로 붙여줍니다.
2. 다른 컨트롤들과 동일한 방식(getValue, setValue, clear)으로 버튼의 value 값을 다루게 해줍니다. 즉, 폼에 있는 텍스트박스나 체크박스와 완전히 동일한 API로 버튼을 제어할 수 있습니다.

내부적으로는 syn.uicontrols.$button이라는 이름의 싱글턴 객체이며, 소스 파일명은 TextButton.js이지만 실제 코드에서 사용하는 네임스페이스는 $button입니다.

언제 사용하나요?

• 폼 안에서 "조회", "저장", "취소" 같은 동작을 트리거하는 버튼을 만들 때
• 버튼의 라벨(value)을 스크립트에서 동적으로 읽거나 바꾸고 싶을 때 (getValue / setValue)
• 버튼에 btn btn-primary 같은 부트스트랩 계열 클래스를 옵션으로 자동 부여하고 싶을 때 (toSynControl + color 옵션)
• 다른 컨트롤(TextBox, CheckBox 등)과 함께 폼을 구성하면서, 버튼도 동일한 syn-events 이벤트 바인딩 규칙을 따르게 하고 싶을 때

일반 HTML <button> 만으로 충분한 단순 페이지라면 이 컨트롤을 강제로 쓸 필요는 없습니다. TextButton은 "폼 컨트롤 생태계 안에서 버튼도 일관되게 다루고 싶을 때" 쓰는 도구입니다.

빠른 시작

<form autocomplete="off" id="form1" syn-datafield="MainForm">
    <input type="button" id="btnSave" value="저장" syn-events="['click']" />
</form>
<script src="/js/syn.loader.js"></script>

// btnSave.js (페이지 스크립트, 파일명은 HTML과 동일해야 합니다)
'use strict';
let $btnSave = {
    event: {
        btnSave_click() {
            syn.$l.eventLog('btnSave_click', '저장 버튼이 클릭되었습니다.');
        }
    }
}

syn.loader.js는 <input type="button"> 요소를 자동으로 감지해서 TextButton.css, TextButton.js를 주입하므로, 페이지에서 별도로 컨트롤 스크립트를 <script> 태그로 추가할 필요가 없습니다.

예제 실행하기

/uicontrols/TextButton/example/ 폴더에 두 개의 실행 가능한 예제가 있습니다.

• basic.html — 버튼 클릭 이벤트를 로그로 확인하고, getValue / setValue / clear 메서드로 버튼 라벨을 조작하는 가장 기본적인 예제
• styled.html — syn-options의 toSynControl, color 옵션으로 버튼에 btn, btn-{color} 클래스가 자동으로 붙는 것을 확인하는 예제

각 .html 파일을 웹 서버(rdy 등)를 통해 열면 됩니다. 파일을 더블클릭해서 file://로 여는 방식은 /js/syn.loader.js 등 절대 경로 리소스를 불러오지 못하므로 반드시 웹 서버 경유로 접속하세요.

더 알아보기

• API 상세(옵션/메서드/이벤트 표)는 같은 폴더의 API.md를 참고하세요.
• 이 컨트롤은 기존 샘플(/sample/uicontrol/)이나 실사용 예시가 발견되지 않아, TextButton.js 소스코드만을 근거로 문서화되었습니다. 실제 프로젝트에 적용하기 전에 TextButton.js, TextButton.css 원본을 함께 확인하는 것을 권장합니다.

실전 예제 페이지

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

basic.html

styled.html

소스와 로드 파일

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

API 참조

• 네임스페이스: syn.uicontrols.$button
• 소스 파일: /uicontrols/TextButton/TextButton.js, /uicontrols/TextButton/TextButton.css
• 버전(소스에 표기된 값): v2025.3.1

마크업

TextButton은 커스텀 태그가 아니라 네이티브 <input> 요소를 인핸스하는 컨트롤입니다. js/syn.loader.js의 컨트롤 판별 로직 기준으로 아래 세 가지 type 값이 모두 TextButton(button 모듈)으로 로드됩니다.

• type="button"
• type="submit"
• type="reset"

<input
    type="button"
    id="btnSave"
    value="저장"
    syn-datafield="Save"
    syn-options="{toSynControl: true, color: 'primary'}"
    syn-events="['click']" />

• id : 필수. 컨트롤을 조회/제어할 때 사용하는 식별자(elID)입니다.
• value : 버튼에 표시되는 라벨이자, getValue/setValue/clear가 다루는 값입니다.
• syn-options : defaultSetting을 덮어쓸 JSON 문자열(선택).
• syn-datafield : 폼 데이터 바인딩용 필드명(선택). closest('form')의 syn-datafield와 함께 모듈 목록(addModuleList)에 등록됩니다.
• syn-events : 페이지 스크립트의 event.<id>_<eventName> 핸들러와 연결할 이벤트 이름 배열. 예: ['click'].

CSS 클래스 ui_textbutton (및 .small, .searchButton 변형)이 TextButton.css에 정의되어 있지만, TextButton.js 코드는 이 클래스를 자동으로 붙여주지 않습니다. 필요하면 마크업에 직접 class="ui_textbutton small" 등으로 추가해야 합니다.

Options (defaultSetting)

옵션	기본값	설명
color	'default'	toSynControl: true일 때 버튼에 붙는 클래스 접미사. btn-{color} 형태로 클래스가 생성됩니다 (예: color: 'primary' → btn-primary).
toSynControl	false	true로 설정하면 컨트롤 로드 시 요소에 btn 클래스와 btn-{color} 클래스를 자동으로 추가합니다(이미 해당 색상 클래스가 없을 때만). 부트스트랩류 버튼 스타일 클래스를 자동 적용하고 싶을 때 사용합니다.
dataType	'string'	이 컨트롤이 다루는 값의 데이터 타입 표기(다른 컨트롤과의 공통 규약용 메타 정보).
belongID	null	소속 그룹/컨테이너 식별자(공통 규약용 메타 정보).
getter	false	값 조회 시 커스텀 로직을 연결하기 위한 훅 플래그(공통 규약, TextButton 자체 로직에서는 직접 사용되지 않음).
setter	false	값 설정 시 커스텀 로직을 연결하기 위한 훅 플래그(공통 규약, TextButton 자체 로직에서는 직접 사용되지 않음).
controlText	null	다국어/커스텀 라벨 텍스트 지정용 공통 옵션(공통 규약, TextButton 자체 로직에서는 직접 사용되지 않음. setLocale도 빈 함수라 현재 구현에서는 동작하지 않습니다).
validators	null	유효성 검사 규칙(공통 규약용, syn.$v 밸리데이터와 연동되는 다른 컨트롤에서 주로 사용).
transactConfig	null	트랜잭션 연동 설정(공통 규약용 메타 정보).
triggerConfig	null	트리거 연동 설정(공통 규약용 메타 정보).

주의: 위 옵션 중 color, toSynControl을 제외한 나머지는 defaultSetting에 선언만 되어 있을 뿐, TextButton.js의 controlLoad/getValue/setValue/clear 로직 안에서 실제로 분기 처리되지 않습니다. 다른 syn.uicontrols 컨트롤들과 설정 스키마를 통일하기 위한 공통 필드로 보입니다.

메서드

메서드	시그니처	설명
controlLoad	controlLoad(elID, setting)	컨트롤 초기화. syn.loader.js가 해당 <input>을 발견하면 자동으로 호출합니다. setting을 defaultSetting과 병합하고, 페이지 스크립트에 hook.controlInit(elID, setting)이 정의되어 있으면 그 결과도 병합합니다. toSynControl: true이면 btn/btn-{color} 클래스를 추가하고, 최종 설정을 syn-options 속성에 다시 기록합니다. setting.bindingID가 있고 syn.uicontrols.$data가 로드되어 있으면 데이터 소스 바인딩도 수행합니다.
getValue	getValue(elID, meta)	elID 요소의 value 속성 값을 그대로 반환합니다.
setValue	setValue(elID, value, meta)	elID 요소의 value 속성에 값을 설정합니다(버튼 라벨이 변경됩니다).
clear	clear(elID, isControlLoad)	elID 요소의 value를 빈 문자열로 초기화합니다(버튼 라벨이 지워집니다).
setLocale	setLocale(elID, translations, control, options)	다국어 처리용 훅이지만, 현재 구현은 빈 함수(no-op)입니다.
addModuleList	addModuleList(el, moduleList, setting, controlType)	폼 전체 컨트롤 목록을 수집하는 내부 유틸리티. id, 소속 폼의 syn-datafield, 자신의 syn-datafield, 모듈명, 컨트롤 타입을 moduleList 배열에 push합니다. 페이지 스크립트에서 직접 호출할 일은 거의 없습니다.

이벤트 (syn-events)

TextButton 자체는 자신만의 전용 이벤트를 정의하지 않습니다. syn-events="['click']"처럼 표준 DOM 이벤트 이름을 배열로 지정하면, syn 프레임워크의 공통 이벤트 바인딩 로직이 페이지 스크립트의 event.<elID>_<eventName> 함수를 자동으로 연결합니다.

이벤트 이름	핸들러 예시	설명
click	event.btnSave_click(args)	버튼 클릭 시 호출됩니다. 대부분의 TextButton 사용 사례에서 필요한 유일한 이벤트입니다.

change, focus, blur 등 다른 표준 DOM 이벤트도 동일한 방식(syn-events에 이름 추가)으로 연결할 수 있지만, 버튼 요소 특성상 click 외에는 거의 사용되지 않습니다.

참고

이 문서는 /sample/uicontrol/ 폴더와 qcn.groupware 등 실사용 코드베이스를 조사했으나 TextButton(type="button" 인핸스) 전용 샘플이나 실사용 예시를 찾지 못해, 오직 TextButton.js, TextButton.css 소스코드 정독만을 근거로 작성되었습니다. 다른 컨트롤 샘플(checkbox.html/checkbox.js 등)에서 반복적으로 등장하는 <input type="button" ... syn-events="['click']" /> 패턴을 교차 확인하여 마크업 형태의 신뢰도를 보강했습니다.