본문으로 건너뛰기

화면 개발 및 거래 업무 사용법 (syn.$w)

개요​

syn.$w(별칭: $webform)는 syn.js에서 가장 큰 하위 모듈로, 화면 부트스트랩(페이지 로드/포커스 관리), 로컬/세션 스토리지, 동적 스크립트/스타일 로딩, IntersectionObserver 기반 지연 로딩, 그리고 HandStack 백엔드와 통신하는 거래(transaction) 엔진까지 화면 개발에 필요한 핵심 기능을 담당합니다.

로드 방법​

syn.js가 로드되면 전역에 syn.$w(별칭: $webform)로 즉시 사용할 수 있습니다. 화면(HTML) 진입 시 syn.loader.js가 syn.$w.contentLoaded()를 자동으로 1회 호출하여 페이지 부트스트랩을 수행합니다.

빠른 시작​

// 세션 스토리지에 값 저장/조회
syn.$w.setStorage('lastVisited', new Date());
var lastVisited = syn.$w.getStorage('lastVisited');

// 거래 요청/응답 매핑 설정(예: GD01)이 있는 화면에서 거래 실행
syn.$w.transactionAction('GD01');

주요 시나리오​

페이지 부트스트랩(contentLoaded)​

contentLoaded()는 document의 DOMContentLoaded 시점(또는 설정 파일 로드 완료 시점)에 자동으로 호출되어 다음을 처리합니다.

  • <form> 제출(submit) 이벤트 가로채기 및 hook.beforeSubmit 연동
  • SSO 사용자 정보(syn.$w.User)를 hook.getSSOInfo() 또는 기본값으로 초기화하고 deepFreeze 처리
  • 미디어 쿼리 구간(xs~xxl) 변경 시 hook.pageMatch() 호출
  • 화면 내 컨트롤의 탭 순서(tabOrderControls) 계산
  • 완료 후 현재 페이지 모듈의 hook.pageLoad() 실행

페이지 진입 시 이미 자동 실행되므로, 직접 호출할 필요는 거의 없습니다. 현재 상태는 syn.$w.pageScript, syn.$w.isPageLoad 속성으로 확인할 수 있습니다.

console.log(syn.$w.pageScript); // 예: '$webforms'

페이지 준비 완료 대기​

컨트롤의 데이터 소스 로딩 등 화면 초기화가 모두 끝난 뒤(= hook.pageLoad() 실행 시점, syn.$w.isPageLoad === true) 실행할 코드는 다음 API로 대기할 수 있습니다. 내부적으로 syn.$w.addReadyCount() / removeReadyCount() 로 집계되는 준비 카운터가 0이 되는 시점에 일괄 실행됩니다.

  • syn.$w.readyAsync() → Promise<void> — 페이지 준비 완료를 Promise로 대기. 이미 준비되었으면 즉시 resolve.
  • syn.$w.ready(callback) — 콜백 전달 시 준비 완료 시(또는 즉시) 실행하고 syn.$w 반환. 콜백 미전달 시 readyAsync() 반환.
  • syn.$w.withReadyCount(promise | function) → Promise — 전달한 비동기 작업이 끝날 때까지 페이지 준비 완료(pageLoad)를 지연시킵니다. 컨트롤이 비동기 리소스를 로드하는 동안 화면 코드가 빈 상태로 실행되는 것을 방지합니다.
await syn.$w.readyAsync();
// 이 시점에는 모든 컨트롤의 데이터 소스가 채워져 있음

syn.$w.ready(function () {
    syn.$l.get('txtName').focus();
});

// 컨트롤 개발자: 비동기 초기화를 페이지 준비 카운터에 연동
syn.$w.withReadyCount(async function () {
    await syn.$w.loadScriptAsync('/lib/thirdparty/lib.min.js', 'thirdpartyLib');
});

로컬/세션 스토리지 TTL 관리​

setStorage(prop, val, isLocal, ttl) / getStorage(prop, isLocal) / removeStorage(prop, isLocal) / getStorageKeys(isLocal)는 브라우저 환경에서는 sessionStorage/localStorage를 그대로 사용하고, Node(디바이스) 환경에서 세션 저장(isLocal이 아닌 경우)은 expiry/ttl 필드를 포함한 래퍼 객체를 localStorage에 저장해 만료(TTL) 관리를 흉내냅니다. 조회 시 만료 시간이 지나면 자동으로 삭제되고, 만료 전이면 조회할 때마다 expiry가 갱신됩니다.

syn.$w.setStorage('token', 'abcd1234');           // sessionStorage (브라우저)
syn.$w.setStorage('token', 'abcd1234', true);      // localStorage
var token = syn.$w.getStorage('token');
var keys = syn.$w.getStorageKeys();                // 저장된 전체 키 목록
syn.$w.removeStorage('token');

거래(transaction) 실행 흐름​

화면 모듈에는 아래와 같은 형태로 거래별 입력/출력 매핑을 선언합니다(예시는 이 페이지의 webforms.js에 이미 존재하는 GD01 선언입니다).

transaction: {
    GD01: {
        inputs: [{ type: 'Row', dataFieldID: 'MainForm' }],
        outputs: [{ type: 'Form', dataFieldID: 'MainForm' }]
    }
}

실행 흐름은 다음과 같습니다.

  1. transactionAction(functionID 또는 transactConfig, options)를 호출하면 내부적으로 tryAddFunction()으로 화면의 거래 목록에 등록하고, transaction(functionID, callback, options)을 실행합니다.
  2. transaction()은 화면 컨트롤(synControls)에서 inputs 매핑에 해당하는 값을 수집해 서버로 전송할 거래 객체(transactionObject()로 생성한 골격)를 구성합니다.
  3. 서버 응답은 outputs 매핑에 따라 화면 컨트롤에 자동으로 반영되고, 완료 후 hook.afterTransaction(error, functionID, result, additionalData, correlationID)가 호출됩니다.
  4. 화면 매핑 없이 값을 직접 지정해 호출하려면 transactionDirect(directObject, callback, options)를 사용합니다. 이 경우 functionID, transactionID 등 값을 직접 채워 넘깁니다.
  5. 컨트롤 매핑 없이 요청/응답 원본 값만 다루려면 getterValue(functionID) / setterValue(functionID, responseData)를 사용합니다.

options에는 message, dynamic, authorize, commandType, returnType, transactionScope, transactionLog, endpoint 등의 공통 옵션이 병합되어 전달됩니다(모두 syn.js 소스에 정의된 기본값이며, 특정 업무 데이터 필드가 아닙니다).

개발 환경(syn.Config.Environment가 D로 시작)에서 화면마다 다른 API 서버로 직접 요청을 보내야 한다면 화면 스크립트의 config.domainAPIServer에 대상 서버 정보를 지정합니다. 지정하지 않으면 전역 설정인 syn.Config.DomainAPIServer가 사용되며, 운영 환경에서는 이 화면별 재정의가 적용되지 않습니다.

// 화면 모듈(webforms.js)
config: {
    domainAPIServer: { /* 개발 전용 API 서버 접속 정보 */ }
}

자동 매핑 거래 실행과 점검(transactionExchange / inspectExchange)​

화면마다 transaction: { functionID: { inputs, outputs } }를 일일이 선언하는 대신, 화면 저작 도구 등이 생성한 $this.config.pageMappings(colGroups/rowGroups/exchanges) 정의를 그대로 읽어 컨트롤 값을 주고받는 방식도 지원합니다.

  • colGroups: 기능(거래) 단위 정의. 각 항목은 groupID(기능 ID)와 요청/응답에 사용할 requestRowGroupSet/responseRowGroupSet(rowGroup ID 배열)을 가집니다.
  • rowGroups: 데이터 컬렉션 정의. type이 Single이면 단건(Row/Form), Multi이면 다건(List/Grid)이며 mappingControls(컨트롤 ID 배열)를 가집니다.
  • exchanges: { [colGroupID]: { [rowGroupID]: { [controlID]: { input, output } } } } 형태로 컨트롤과 서버 필드명을 연결합니다.
$this.config.pageMappings = {
    colGroups: [{ groupID: 'GD01', requestRowGroupSet: ['SearchForm'], responseRowGroupSet: ['MainForm'] }],
    rowGroups: [
        { groupID: 'SearchForm', type: 'Single', mappingControls: ['txtKeyword'] },
        { groupID: 'MainForm', type: 'Single', mappingControls: ['txtName', 'txtEmail'] }
    ],
    exchanges: {
        GD01: {
            SearchForm: { txtKeyword: { input: 'Keyword' } },
            MainForm: { txtName: { output: 'Name' }, txtEmail: { output: 'Email' } }
        }
    }
};

syn.$w.transactionExchange('GD01', { message: '조회 중...' });

Single 타입 rowGroup이 그리드 컨트롤(syn-datafield 대상이 그리드/차트)에 연결돼 있으면, 그리드에서 선택한 행 값을 요청으로 자동 사용합니다(목록에서 한 행을 고른 뒤 상세 조회하는 화면에 적합).

매핑 설정이 올바른지 코드를 실행하지 않고 미리 확인하려면 inspectExchange(colGroupID)로 점검 보고서를 출력합니다.

console.log(syn.$w.inspectExchange('GD01'));
// 기능 "GD01" 매핑 점검
//   요청 SearchForm (Single --> Row)
//     txtKeyword --> Keyword
//   응답 MainForm (Single --> Form)
//     txtName <-- Name
//     txtEmail <-- Email
//   dataMapInterface: Row|Form

매핑이 빠진 컨트롤은 (매핑 없음)으로 표시되므로, 화면이 비어 있는 문제를 진단할 때 syn-datafield 이름과 exchanges 설정 중 어느 쪽이 어긋났는지 빠르게 좁힐 수 있습니다.

동적 스크립트/스타일 로딩​

  • loadScript(url, scriptID, callback) / loadStyle(url, styleID, callback): 외부 <script>/<link> 리소스를 중복 없이 <head>에 추가합니다.
  • getDynamicStyle(styleID) / addCssRule(rules, styleID) / removeCssRule(identifier, styleID): 런타임에 <style> 시트를 생성/조회하고 CSS 규칙을 추가·삭제합니다.
  • pseudoStyle(elID, selector, cssText) / pseudoStyles(elID, styles): 지정한 <style> 엘리먼트의 내용을 selector/cssText 조합으로 통째로 교체합니다.
syn.$w.loadStyle('/sample/syn/style.css', 'demo-style');
syn.$w.addCssRule('.highlight { background: yellow; }', 'demo-style');
syn.$w.pseudoStyle('quick-style', '#target', 'color: red;');

IntersectionObserver 기반 지연 로딩​

startIntersection(id, placeholder, loadMore, options)는 placeholder 엘리먼트가 뷰포트(또는 지정한 root)에 들어오면 loadMore(done) 콜백을 실행하는 무한 스크롤/지연 로딩 헬퍼입니다. done(true)를 호출하면 해당 관찰이 자동으로 종료됩니다.

syn.$w.startIntersection('list-scroll', '#loading-placeholder', function (done) {
    // 추가 데이터 로드 로직
    done(false); // 계속 관찰, true면 관찰 종료
}, { rootMargin: '100px' });

syn.$w.stopIntersection('list-scroll');
syn.$w.stopAllIntersections();

실전 예제 페이지​

/sample/syn/webforms.html 예제에서 다음 항목을 실습할 수 있습니다.

  • 속성: version
  • 메서드: setStorage(), getStorage(), removeStorage(), getStorageKeys(), activeControl(), argumentsExtend(), contentLoaded(), getTriggerOptions(), triggerAction(), getControlModule(), tryAddFunction(), getterValue(), setterValue(), transactionAction(), transaction(), transactionDirect(), transactionObject(), scrollToTop(), scrollToElement(), setFavicon(), fileDownload(), sleep(), purge(), setServiceObject(), setServiceClientHeader(), xmlHttp(), xmlParser(), apiHttp(), loadScript(), loadStyle(), getDynamicStyle(), addCssRule(), removeCssRule(), pseudoStyle(), pseudoStyles(), fetchText(), fetchJson(), loadJson(), loadJsonAsync(), fetchImage(), startIntersection(), stopIntersection(), stopAllIntersections()
  • transactionExchange()/inspectExchange()는 $this.config.pageMappings 설정이 필요하며, 이 예제 페이지에는 해당 설정이 없어 별도로 시연하지 않습니다. 사용법은 위 "자동 매핑 거래 실행과 점검" 절과 API 참조를 확인하세요.

주의 사항​

  • GD01 행(거래 실행: transactionAction()/transaction(), transactionDirect())은 실제 HandStack 백엔드/거래 모듈이 연결되어 있어야 정상 동작합니다. 이 예제 페이지를 백엔드 없이 단독으로 열면 해당 항목은 오류 메시지가 표시되거나 빈 결과가 반환됩니다 — 이는 정상적인 동작이며 페이지 자체의 오류가 아닙니다.
  • getterValue()/setterValue()는 네트워크 요청 없이 화면-거래 매핑 설정과 컨트롤 값만 다루므로 백엔드 없이도 동작을 확인할 수 있습니다. 다만 실제 서버 응답 형태(응답 필드 구조)는 백엔드 거래 정의에 따라 달라지므로 이 문서에서는 임의의 업무 필드를 제시하지 않습니다.
  • Node(디바이스) 환경과 브라우저 환경에서 setStorage/getStorage의 세션 스토리지 동작 방식(TTL 유무)이 다릅니다.
  • purge(), triggerAction() 데모는 화면 조작 편의를 위한 예시이며, 운영 화면에서는 컨트롤 생명주기와 이벤트 바인딩 규칙을 함께 고려해야 합니다.
  • apiHttp()(webform)와 httpFetch()(request 모듈, syn.$r)는 서로 다른 모듈의 별개 기능입니다. 이름이 유사하니 혼동하지 않도록 주의합니다.
  • transactionExchange()/inspectExchange()는 $this.config.pageMappings 정의가 있는 화면에서만 동작합니다. 정의가 없으면 경고 로그만 남기고 조용히 종료(inspectExchange는 빈 문자열 반환)됩니다.

관련 모듈​

  • API 상세는 아래 API 참조 섹션을 확인하세요.

API 참조​

모듈 정보​

항목내용
전역 별칭syn.$w (원본: context.$webform)
예제 페이지/sample/syn/webforms.html
의존 모듈syn.$l(library, get/eventLog/addEvent 등), syn.$d(dimension, offset), syn.$o(object), syn.$s(string), syn.$b(browser, getIpAddress), syn.$a(array), syn.uicontrols.*(그리드/차트 등 컨트롤)

스토리지​

syn.$w.setStorage(prop, val, isLocal, ttl)​

  • 설명: 값을 sessionStorage(기본) 또는 localStorage(isLocal=true)에 JSON 직렬화하여 저장합니다. Node(디바이스) 환경에서 세션 저장은 ttl(기본 1,200,000ms)을 적용한 만료 정보를 함께 저장합니다.
  • 매개변수
    이름타입필수설명
    propstringY저장 키
    valanyY저장할 값(JSON 직렬화됨)
    isLocalbooleanNtrue이면 localStorage 사용(기본값 false)
    ttlnumberNNode 환경 세션 저장 시 만료(ms), 기본 1,200,000
  • 반환값: syn.$w — 메서드 체이닝을 위한 자기 자신
  • 예시 
    syn.$w.setStorage('token', 'abcd1234');
    syn.$w.setStorage('token', 'abcd1234', true);

syn.$w.getStorage(prop, isLocal)​

  • 설명: sessionStorage/localStorage에서 값을 조회해 JSON으로 역직렬화합니다. prop이 배열이면 해당 키들에 매칭되는 값들을 객체로 반환합니다. Node 환경의 세션 저장은 만료 시간이 지나면 자동 삭제 후 null을 반환합니다.
  • 매개변수
    이름타입필수설명
    prop`string \string[]`Y
    isLocalbooleanNtrue이면 localStorage 조회(기본값 false)
  • 반환값: any | object | null — 조회된 값(파싱 실패/미존재 시 null)
  • 예시 
    var token = syn.$w.getStorage('token');

syn.$w.removeStorage(prop, isLocal)​

  • 설명: sessionStorage/localStorage에서 지정한 키를 삭제합니다.
  • 매개변수
    이름타입필수설명
    propstringY삭제할 키
    isLocalbooleanNtrue이면 localStorage 대상(기본값 false)
  • 반환값: syn.$w — 메서드 체이닝을 위한 자기 자신
  • 예시 
    syn.$w.removeStorage('token');

syn.$w.getStorageKeys(isLocal)​

  • 설명: sessionStorage/localStorage에 저장된 전체 키 목록을 배열로 반환합니다.
  • 매개변수
    이름타입필수설명
    isLocalbooleanNtrue이면 localStorage 대상(기본값 false)
  • 반환값: string[] — 키 목록
  • 예시 
    var keys = syn.$w.getStorageKeys();

페이지 라이프사이클​

syn.$w.activeControl(evt)​

  • 설명: 이벤트가 발생한 노드(evt.target) → 마지막으로 포커스했던 노드($this.context.focusControl) → document.activeElement 순서로 현재 활성 컨트롤을 조회합니다. 조회된 노드는 이후 참조를 위해 $this.context.focusControl에 갱신됩니다.
  • 매개변수
    이름타입필수설명
    evtEventN이벤트 객체(생략 시 window.event 또는 마지막 활성 노드 사용)
  • 반환값: HTMLElement | null — 활성 컨트롤 엘리먼트
  • 예시 
    var el = syn.$w.activeControl();

syn.$w.argumentsExtend(...args)​

  • 설명: 여러 객체를 Object.assign({}, ...args)로 얕은 병합(shallow merge)합니다. syn.js 내부에서 옵션 병합에 광범위하게 사용됩니다.
  • 매개변수
    이름타입필수설명
    argsobject[]Y병합할 객체들(가변 인자)
  • 반환값: object — 병합된 새 객체
  • 예시 
    var merged = syn.$w.argumentsExtend({ a: 0, b: '' }, { a: 1 });

syn.$w.contentLoaded()​

  • 설명: 페이지 진입 시 syn.loader.js가 자동으로 1회 호출하는 화면 부트스트랩 함수입니다. 폼 submit 가로채기, SSO 사용자 정보(syn.$w.User) 초기화, 미디어 쿼리 구간 변경 이벤트 연결, 탭 순서(tabOrderControls) 계산 등을 수행한 뒤 현재 페이지 모듈의 hook.pageLoad()를 호출합니다.
  • 매개변수: 없음
  • 반환값: Promise<void>
  • 예시 
    // 일반적으로 직접 호출하지 않으며, syn.loader.js가 DOMContentLoaded 시점에 자동 실행합니다.
    console.log(syn.$w.pageScript, syn.$w.isPageLoad);

syn.$w.getTriggerOptions(el)​

  • 설명: 엘리먼트의 triggerOptions 속성(JSON 문자열)을 파싱해 객체로 반환합니다.
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`Y
  • 반환값: object | null — 파싱된 옵션 객체, 속성이 없거나 파싱 실패 시 null
  • 예시 
    var options = syn.$w.getTriggerOptions('btn_target');

syn.$w.triggerAction(triggerConfig)​

  • 설명: triggerConfig.triggerID/action 조합(또는 method 문자열)으로 등록된 event 핸들러나 syn.uicontrols.$* 함수를 간접적으로 실행합니다. 실행 전후로 hook.beforeTrigger/hook.afterTrigger가 호출됩니다.
  • 매개변수
    이름타입필수설명
    triggerConfigobjectY{ triggerID, action, method, params: { arguments, options } } 형태
  • 반환값: 없음(내부적으로 실행 결과는 hook.afterTrigger로 전달)
  • 예시 
    syn.$w.triggerAction({ triggerID: 'btn_scrollToTop', action: 'click', params: { arguments: [], options: {} } });

syn.$w.getControlModule(modulePath)​

  • 설명: "syn.$l"과 같은 점(dot) 표기 경로 문자열로 전역 컨텍스트에서 실제 모듈 객체 참조를 조회합니다.
  • 매개변수
    이름타입필수설명
    modulePathstringY점(dot) 표기 모듈 경로
  • 반환값: object | null — 조회된 모듈 참조, 없으면 null
  • 예시 
    var lib = syn.$w.getControlModule('syn.$l');

거래 엔진​

아래 항목들은 화면 모듈에 선언한 transaction 설정({ functionID: { inputs, outputs } })을 기반으로 동작하는 범용 구조를 설명합니다. 실제 업무 필드/응답 데이터는 연결된 HandStack 백엔드 거래 정의에 따라 달라지며, 이 문서와 예제는 그 실제 값을 임의로 정의하지 않습니다.

syn.$w.tryAddFunction(transactConfig)​

  • 설명: transactConfig(functionID, inputs, outputs, transactionResult, noProgress 등)를 현재 화면의 거래 목록($this.config.transactions)에 등록(중복 시 교체)합니다. 네트워크 요청을 수행하지 않는 로컬 등록 함수입니다.
  • 매개변수
    이름타입필수설명
    transactConfigobjectY{ functionID, inputs: [{type, dataFieldID}], outputs: [{type, dataFieldID}], transactionResult?, noProgress? }
  • 반환값: 없음
  • 예시 
    syn.$w.tryAddFunction($webforms.transaction.GD01);

syn.$w.getterValue(functionID)​

  • 설명: 화면-거래 매핑 설정(transaction[functionID].inputs)에 따라 현재 컨트롤 값을 수집해 요청 정보 형태로 반환합니다. 네트워크 요청은 수행하지 않습니다.
  • 매개변수
    이름타입필수설명
    functionIDstringY화면에 선언된 거래 식별자(예: GD01)
  • 반환값: { errors: string[], inputs: any[] } — 수집된 입력 정보
  • 예시 
    var result = syn.$w.getterValue('GD01');

syn.$w.setterValue(functionID, responseData)​

  • 설명: 서버 응답 형태의 responseData를 화면-거래 매핑 설정(transaction[functionID].outputs)에 따라 화면 컨트롤에 적용합니다. 네트워크 요청은 수행하지 않습니다.
  • 매개변수
    이름타입필수설명
    functionIDstringY화면에 선언된 거래 식별자(예: GD01)
    responseDataany[]Y출력 매핑(outputs) 순서에 대응하는 응답 데이터 배열
  • 반환값: { errors: string[], outputs: any[] } — 적용 결과 요약
  • 예시 
    syn.$w.setterValue('GD01', dataSet);

syn.$w.transactionAction(transactConfigInput, options)​

  • 설명: functionID 문자열 또는 거래 설정 객체를 받아 tryAddFunction()으로 등록 후 transaction()을 실행하는 상위 래퍼입니다. 완료/실패 시 화면 모듈의 hook.afterTransaction(error, functionID, result, additionalData, correlationID)을 호출합니다.
  • 매개변수
    이름타입필수설명
    transactConfigInput`string \object`Y
    optionsobjectNmessage, dynamic, authorize, commandType, returnType, transactionScope, transactionLog, endpoint 등 공통 옵션
  • 반환값: 없음(결과는 hook.afterTransaction 콜백으로 전달)
  • 예시 
    syn.$w.transactionAction('GD01', { message: '조회 중...' });
  • 참고: 실제 서버 응답을 받으려면 HandStack 백엔드/거래 모듈 연결이 필요합니다. 연결되어 있지 않으면 hook.afterTransaction의 error 값이 채워지는 것이 정상입니다.

syn.$w.transaction(functionID, callback, options)​

  • 설명: transactionAction() 내부에서 사용하는 저수준 함수로, 화면 컨트롤에서 입력값을 수집해 서버에 거래를 요청하고 응답을 컨트롤에 매핑합니다.
  • 매개변수
    이름타입필수설명
    functionIDstringY화면에 선언된 거래 식별자
    callbackfunction(result, additionalData, correlationID)N완료 콜백. result는 { errorText: string[], outputStat: any[] }
    optionsobjectNtransactionAction()과 동일한 공통 옵션
  • 반환값: 없음
  • 예시 
    syn.$w.transaction('GD01', function (result) {
        console.log(result.errorText);
    });
  • 참고: 실제 응답을 받으려면 HandStack 백엔드/거래 모듈 연결이 필요합니다.

syn.$w.transactionDirect(directObject, callback, options)​

  • 설명: 화면 컨트롤 매핑 없이 functionID, transactionID 등 값을 직접 지정해 서버에 거래를 요청합니다. Promise를 반환하며 실패 시 reject 됩니다.
  • 매개변수
    이름타입필수설명
    directObjectobjectY{ functionID, programID?, moduleID?, businessID?, systemID?, transactionID, transactionToken?, dataMapInterface?, transactionResult?, screenID?, startTraceID?, inputObjects?, inputLists?, noProgress? }
    callbackfunction(responseData, additionalData)N응답 수신 콜백
    optionsobjectNtransactionAction()과 동일한 공통 옵션
  • 반환값: Promise<{ responseData, additionalData }>
  • 예시 
    const result = await syn.$w.transactionDirect({ functionID: 'GD01', transactionID: 'GD01', inputObjects: {} });
  • 참고: 실제 응답을 받으려면 HandStack 백엔드/거래 모듈 연결이 필요합니다. 연결되어 있지 않으면 이 호출은 오류(reject)로 종료되는 것이 정상입니다.

syn.$w.transactionObject(functionID, returnType)​

  • 설명: 서버 전송용 거래 객체의 기본 골격을 생성합니다(programID, businessID, systemID, transactionID 등은 빈 값으로 초기화되며, 이후 호출부에서 채워집니다). 네트워크 요청을 수행하지 않습니다.
  • 매개변수
    이름타입필수설명
    functionIDstringY거래 식별자
    returnTypestringN반환 형식(기본값 'Json')
  • 반환값: object — { programID, businessID, systemID, transactionID, transactionToken, dataMapInterface, transactionResult, functionID, screenID, startTraceID, requestID, returnType, resultAlias, inputsItemCount, inputs }
  • 예시 
    var obj = syn.$w.transactionObject('GD01');

syn.$w.transactionExchange(colGroupID, options)​

  • 설명: 화면 스크립트에 transaction 매핑을 개별 선언하는 대신, $this.config.pageMappings(colGroups/rowGroups/exchanges)에 정의된 화면-거래 매핑 정보를 읽어 요청을 구성하고 컨트롤 값을 직접 주고받습니다. Single rowGroup이 그리드에 연결돼 있으면 그리드에서 선택한 행을 요청 값으로 사용합니다. 완료/실패 시 $this.hook.afterTransaction이 호출됩니다.
  • 매개변수
    이름타입필수설명
    colGroupIDstringYpageMappings.colGroups에 정의된 기능 ID
    optionsobjectNtransactionAction()과 동일한 공통 옵션 + callback(error, responseData, additionalData, correlationID)
  • 반환값: 없음(결과는 options.callback 또는 hook.afterTransaction으로 전달)
  • 예시 
    syn.$w.transactionExchange('GD01', { message: '조회 중...' });
  • 참고: $this.config.pageMappings 정의가 없거나 colGroupID를 찾을 수 없으면 경고 로그만 남기고 실행되지 않습니다. 상세 구조와 예시는 위 "자동 매핑 거래 실행과 점검" 절을 참고하세요.

syn.$w.inspectExchange(colGroupID)​

  • 설명: 지정한 기능 ID의 pageMappings 설정을 사람이 읽을 수 있는 문자열 보고서로 반환하는 디버깅 도구입니다. 요청/응답 각 데이터 컬렉션의 타입(Single/Multi → Row/List/Form/Grid), 컨트롤별 매핑 필드, 매핑이 빠진 컨트롤, 최종 dataMapInterface 값을 실제 거래 실행 없이 확인할 수 있습니다.
  • 매개변수
    이름타입필수설명
    colGroupIDstringYpageMappings.colGroups에 정의된 기능 ID
  • 반환값: string — 점검 결과 보고서. colGroupID를 생략했거나 매핑을 찾지 못하면 경고 로그와 함께 빈 문자열('')
  • 예시 
    console.log(syn.$w.inspectExchange('GD01'));
  • 참고: 네트워크 요청을 수행하지 않으므로 백엔드 연결 없이도 매핑 설정만 검증할 수 있습니다.

스크립트/스타일 로딩​

syn.$w.loadScript(url, scriptID, callback)​

  • 설명: 외부 <script> 리소스를 <head>에 동적으로 추가합니다. 동일한 scriptID가 이미 있으면 다시 추가하지 않습니다. callback은 스크립트가 실제로 로드 완료(onload)된 뒤 호출되며, 로드 실패 시에는 호출되지 않고 syn.$l.eventLog로 오류가 기록됩니다.
  • 매개변수
    이름타입필수설명
    urlstringY스크립트 URL
    scriptIDstringN중복 방지를 위한 엘리먼트 ID(생략 시 자동 생성). 명시하면 동일 리소스에 대한 중복 로드를 방지(single-flight)합니다.
    callbackfunction()N로드 완료 콜백
  • 반환값: syn.$w
  • 예시 
    syn.$w.loadScript('https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.13.6/underscore-min.js');

syn.$w.loadScriptAsync(url, scriptID, options)​

  • 설명: loadScript의 Promise 버전입니다. 스크립트 로드 완료 시 resolve, 실패(onerror)/시간 초과 시 reject됩니다. scriptID를 명시하면 중복 로드를 방지하고, 동일 요청은 캐시된 Promise를 반환합니다.
  • 매개변수
    이름타입필수설명
    urlstringY스크립트 URL
    scriptIDstringN중복 방지를 위한 엘리먼트 ID(생략 시 자동 생성)
    optionsobjectN{ timeout } — 로드 제한 시간(ms, 기본 0 = 무제한)
  • 반환값: Promise<HTMLScriptElement | void>
  • 예시 
    await syn.$w.loadScriptAsync('/lib/print-js/print.min.js', 'printjs', { timeout: 10000 });
    printJS('/files/sample.pdf');

syn.$w.loadStyle(url, styleID, callback)​

  • 설명: 외부 <link rel="stylesheet"> 리소스를 <head>에 동적으로 추가합니다. callback은 스타일시트가 실제로 로드 완료(onload)된 뒤 호출됩니다.
  • 매개변수
    이름타입필수설명
    urlstringY스타일시트 URL
    styleIDstringN중복 방지를 위한 엘리먼트 ID(생략 시 자동 생성)
    callbackfunction()N로드 완료 콜백
  • 반환값: syn.$w
  • 예시 
    syn.$w.loadStyle('/sample/syn/style.css');

syn.$w.loadStyleAsync(url, styleID, options)​

  • 설명: loadStyle의 Promise 버전입니다. 매개변수·반환 형식은 loadScriptAsync와 동일하며 <link rel="stylesheet">를 로드합니다.
  • 반환값: Promise<HTMLLinkElement | void>
  • 예시 
    await syn.$w.loadStyleAsync('/css/custom.css', 'customStyle');

syn.$w.getDynamicStyle(styleID)​

  • 설명: styleID에 해당하는 <style> 엘리먼트를 조회하거나 없으면 생성한 뒤 해당 CSSStyleSheet를 반환합니다. styleID를 생략하면 문서의 마지막 스타일시트를 반환합니다.
  • 매개변수
    이름타입필수설명
    styleIDstringN대상 <style> 엘리먼트 ID
  • 반환값: CSSStyleSheet | null
  • 예시 
    var sheet = syn.$w.getDynamicStyle('demo-style');

syn.$w.addCssRule(rules, styleID)​

  • 설명: getDynamicStyle(styleID)로 얻은 시트에 CSS 규칙(문자열 또는 문자열 배열)을 insertRule로 추가합니다.
  • 매개변수
    이름타입필수설명
    rules`string \string[]`Y
    styleIDstringN대상 <style> 엘리먼트 ID
  • 반환값: number[] — 추가된 규칙들의 인덱스 배열
  • 예시 
    syn.$w.addCssRule('.highlight { background-color: yellow; }', 'demo-style');

syn.$w.removeCssRule(identifier, styleID)​

  • 설명: 인덱스(number) 또는 셀렉터 문자열(string)로 지정한 CSS 규칙을 삭제합니다.
  • 매개변수
    이름타입필수설명
    identifier`number \string`Y
    styleIDstringN대상 <style> 엘리먼트 ID
  • 반환값: boolean — 삭제 성공 여부
  • 예시 
    syn.$w.removeCssRule('.highlight', 'demo-style');

syn.$w.pseudoStyle(elID, selector, cssText)​

  • 설명: elID의 <style> 엘리먼트 내용을 selector { cssText } 형태로 통째로 교체(생성)합니다.
  • 매개변수
    이름타입필수설명
    elIDstringY대상 <style> 엘리먼트 ID
    selectorstringYCSS 셀렉터
    cssTextstringY선언 블록 내용
  • 반환값: 없음
  • 예시 
    syn.$w.pseudoStyle('quick-style', '#target', 'color: red;');

syn.$w.pseudoStyles(elID, styles)​

  • 설명: elID의 <style> 엘리먼트 내용을 여러 {selector, cssText} 조합으로 한 번에 교체(생성)합니다.
  • 매개변수
    이름타입필수설명
    elIDstringY대상 <style> 엘리먼트 ID
    styles{selector, cssText}[]Y적용할 스타일 목록
  • 반환값: 없음
  • 예시 
    syn.$w.pseudoStyles('quick-style', [{ selector: '#a', cssText: 'color:red;' }]);

기타 유틸리티​

syn.$w.scrollToTop()​

  • 설명: requestAnimationFrame을 이용해 화면 스크롤을 부드럽게 최상단으로 이동합니다.
  • 매개변수: 없음
  • 반환값: 없음
  • 예시 
    syn.$w.scrollToTop();

syn.$w.scrollToElement(el, offset)​

  • 설명: 지정한 엘리먼트 위치까지 ease-in-out 곡선으로 스크롤 이동합니다(200ms).
  • 매개변수
    이름타입필수설명
    el`string \HTMLElement`Y
    offsetnumberN목표 지점에서 뺄 여백(px), 기본값 0
  • 반환값: 없음
  • 예시 
    syn.$w.scrollToElement('#anchor_bottom', 80);

syn.$w.setFavicon(url)​

  • 설명: 문서의 favicon(link[rel="icon"])을 조회하거나 새로 생성해 url로 설정합니다.
  • 매개변수
    이름타입필수설명
    urlstringYfavicon 이미지 URL
  • 반환값: 없음
  • 예시 
    syn.$w.setFavicon('/img/logo.ico');

syn.$w.fileDownload(url, fileName)​

  • 설명: 임시 <a download> 엘리먼트를 생성해 url 응답을 파일로 다운로드합니다.
  • 매개변수
    이름타입필수설명
    urlstringY다운로드할 리소스 URL
    fileNamestringN저장할 파일명(생략 시 URL에서 추출)
  • 반환값: 없음
  • 예시 
    syn.$w.fileDownload('/sample/syn/webforms.html', 'download.txt');

syn.$w.sleep(ms, callback)​

  • 설명: 지정한 시간(ms) 후 실행되는 지연 함수입니다. callback을 전달하면 setTimeout 방식으로 동작하고, 생략하면 Promise를 반환합니다.
  • 매개변수
    이름타입필수설명
    msnumberY대기 시간(ms)
    callbackfunction()N콜백 함수
  • 반환값: Promise<void> | number — 콜백 미지정 시 Promise, 지정 시 타이머 ID
  • 예시 
    await syn.$w.sleep(1500);

syn.$w.purge(el)​

  • 설명: 엘리먼트와 하위 노드에 연결된 on* 인라인 이벤트 핸들러를 재귀적으로 제거하고, syn.$l.events.removeAllForElement()로 등록된 이벤트 리스너도 함께 정리합니다(메모리 누수 방지 목적).
  • 매개변수
    이름타입필수설명
    elHTMLElementY정리할 엘리먼트
  • 반환값: 없음
  • 예시 
    syn.$w.purge(document.getElementById('temp'));

syn.$w.setServiceObject(value)​

  • 설명: 거래 전송 시 참고할 서비스 객체 값을 문자열로 저장합니다(syn.$w.serviceObject). value가 문자열이 아니면 JSON.stringify로 변환합니다.
  • 매개변수
    이름타입필수설명
    value`string \object`Y
  • 반환값: syn.$w
  • 예시 
    syn.$w.setServiceObject({ demo: true });

syn.$w.setServiceClientHeader(xhr)​

  • 설명: XMLHttpRequest에 인증 헤더(CertificationKey)를 설정합니다. loadJson() 등 내부 XHR 호출 전에 사용됩니다.
  • 매개변수
    이름타입필수설명
    xhrXMLHttpRequestY헤더를 설정할 XHR 인스턴스
  • 반환값: boolean — 항상 true
  • 예시 
    var xhr = syn.$w.xmlHttp();
    xhr.open('GET', url, true);
    syn.$w.setServiceClientHeader(xhr);

syn.$w.xmlHttp()​

  • 설명: 새 XMLHttpRequest 인스턴스를 생성해 반환합니다.
  • 매개변수: 없음
  • 반환값: XMLHttpRequest
  • 예시 
    var xhr = syn.$w.xmlHttp();

syn.$w.xmlParser(xmlString)​

  • 설명: XML 문자열을 DOMParser로 파싱해 Document 객체로 반환합니다.
  • 매개변수
    이름타입필수설명
    xmlStringstringY파싱할 XML 문자열
  • 반환값: Document | null — 파싱 결과, 미지원/오류 시 null
  • 예시 
    var xmlDoc = syn.$w.xmlParser('<root><item>hello</item></root>');

syn.$w.apiHttp(url)​

  • 설명: Proxy 기반으로 send(raw, options) 메서드를 제공하는 경량 fetch 래퍼를 반환합니다. raw가 객체(FormData 제외)이면 JSON으로 직렬화해 전송하고, 응답의 Content-Type에 따라 JSON/텍스트/Blob으로 파싱합니다.
  • 매개변수
    이름타입필수설명
    urlstringY요청 URL
  • 반환값: { send(raw?, options?): Promise<any> } — send() 호출 시 실제 요청 수행
  • 예시 
    var result = await syn.$w.apiHttp('sample.json').send();

syn.$w.loadScript/loadStyle와 함께 자주 쓰이는 리소스 조회 함수​

syn.$w.fetchText(url)​

  • 설명: fetch()로 url 응답을 텍스트로 조회합니다.
  • 매개변수
    이름타입필수설명
    urlstringY조회할 URL
  • 반환값: Promise<string>
  • 예시 
    var text = await syn.$w.fetchText('style.css');

syn.$w.fetchJson(url)​

  • 설명: fetch()로 url 응답을 JSON 객체로 조회합니다.
  • 매개변수
    이름타입필수설명
    urlstringY조회할 URL
  • 반환값: Promise<object>
  • 예시 
    var json = await syn.$w.fetchJson('sample.json');

syn.$w.loadJson(url, setting, success, callback, async, isForceCallback)​

  • 설명: XMLHttpRequest로 JSON 주소를 동기(async=false) 또는 비동기 방식으로 요청하고, 성공 시 success(setting, responseData)를, 완료(성공/강제) 시 callback()을 실행합니다.
  • 매개변수
    이름타입필수설명
    urlstringY요청 URL
    settinganyNsuccess 콜백에 그대로 전달되는 참조 값
    successfunction(setting, responseData)N파싱 성공 시 콜백
    callbackfunction()N완료 콜백(성공 또는 isForceCallback=true인 실패 시 실행)
    asyncbooleanN비동기 여부(기본값 true)
    isForceCallbackbooleanN실패 시에도 callback 강제 실행 여부(기본값 false)
  • 반환값: 없음
  • 예시 
    syn.$w.loadJson('sample.json', null, function (setting, json) {
        console.log(json);
    });

syn.$w.loadJsonAsync(url, options)​

  • 설명: loadJson의 Promise 버전. 항상 비동기로 요청하며 파싱 성공 시 JSON 데이터로 resolve, HTTP 오류/파싱 오류/네트워크 오류/시간 초과 시 Error로 reject 합니다.
  • 매개변수
    이름타입필수설명
    urlstringY요청 URL
    optionsobjectN{ timeout } — 요청 제한 시간(ms, 기본 0 = 무제한)
  • 반환값: Promise<any>
  • 예시 
    const data = await syn.$w.loadJsonAsync('sample.json', { timeout: 5000 });

syn.$w.fetchImage(url, fallbackUrl)​

  • 설명: 이미지를 미리 로드(preload)하고, 로드 실패 시 fallbackUrl 이미지로 1회 재시도합니다.
  • 매개변수
    이름타입필수설명
    urlstringY로드할 이미지 URL
    fallbackUrlstringN실패 시 대체 이미지 URL
  • 반환값: Promise<HTMLImageElement>
  • 예시 
    var img = await syn.$w.fetchImage('/img/logo.ico', '/img/logo.ico');

syn.$w.startIntersection(id, placeholder, loadMore, options)​

  • 설명: IntersectionObserver로 placeholder 엘리먼트가 뷰포트(또는 options.root)에 들어오면 loadMore(done)을 실행하는 무한 스크롤/지연 로딩 관찰자를 등록합니다. 이미 실행 중이면 중복 실행되지 않도록 isLoading 플래그로 제어됩니다.
  • 매개변수
    이름타입필수설명
    idstringY관찰자 고유 식별자
    placeholder`string \HTMLElement`Y
    loadMorefunction(done)Y교차 시 실행할 콜백. done(isFinished) 호출로 로딩 상태 해제/관찰 종료
    optionsobjectNIntersectionObserver 옵션(root, rootMargin, threshold 등), 기본값 { root: null, rootMargin: '0px', threshold: 0.01 }
  • 반환값: IntersectionObserver | null
  • 예시 
    syn.$w.startIntersection('list-scroll', '#loading-placeholder', function (done) {
        done(false);
    });

syn.$w.stopIntersection(id)​

  • 설명: id로 등록된 IntersectionObserver를 해제하고 목록에서 제거합니다.
  • 매개변수
    이름타입필수설명
    idstringY해제할 관찰자 식별자
  • 반환값: 없음
  • 예시 
    syn.$w.stopIntersection('list-scroll');

syn.$w.stopAllIntersections()​

  • 설명: 현재 등록된 모든 IntersectionObserver를 해제합니다.
  • 매개변수: 없음
  • 반환값: 없음
  • 예시 
    syn.$w.stopAllIntersections();