MOCA

U1.가이드 소개

MOCA는 업무 시스템의 화면 구성과 조작 방식을 일관되게 제공하는 UI/UX 프레임워크입니다. 적용 시스템마다 메뉴명과 업무 데이터는 다르지만, 조회·그리드·입력·팝업·모바일 조작은 같은 원칙으로 동작합니다.

U2.로그인과 화면 구성

로그인 후 화면은 일반적으로 다음 영역으로 구성됩니다. 적용 시스템의 업무 특성에 따라 일부 영역은 생략되거나 위치가 달라질 수 있습니다.

U3.메뉴와 작업 탭

• 메뉴 열기 — 메뉴의 업무 항목을 선택하면 작업 탭이 열립니다. 그룹 항목은 접고 펼칠 수 있습니다.
• 탭 전환 — 열린 탭을 선택하면 입력 상태와 스크롤 위치를 유지한 채 해당 화면으로 돌아갑니다.
• 탭 닫기 — 탭의 닫기 버튼을 사용합니다. 편집 중인 내용이 있으면 확인 메시지가 표시될 수 있습니다.
• 화면 분할 — 작업영역 오른쪽 위의 분할 버튼을 누르고 탭을 다른 영역으로 드래그하면 두 화면을 좌우로 함께 볼 수 있습니다. 가운데 경계를 드래그해 폭을 조절합니다.
• 화면 새로고침 — 화면의 새로고침 기능은 현재 업무 화면만 다시 불러옵니다.

U4.조회와 검색조건

검색영역에 조건을 입력한 뒤 [조회]를 선택합니다. 입력칸에서 Enter를 눌러 조회할 수도 있습니다.

• 조건을 비우면 전체 조회로 동작하는 화면이 많습니다.
• 조회 중에는 진행 표시가 나타나며, 완료 후 결과 건수와 처리시간을 확인할 수 있습니다.
• 재조회하면 기존 목록의 정렬·필터·선택 상태가 초기화될 수 있습니다.
• 조회 결과가 없으면 조건의 공백, 날짜 범위, 선택값을 먼저 확인합니다.

U5.그리드 기본 사용

그리드는 조회 결과를 표시하고 정렬·필터·페이징·엑셀·전체화면 기능을 제공하는 표입니다.

행 상세보기

컬럼이 많아 가로로 길게 늘어선 행은 상세보기로 한눈에 확인합니다. 행을 선택하고 툴바의 상세보기 버튼을 누르면 그 행의 모든 항목이 「항목명 — 값」 형태로 펼쳐집니다.

• 단 전환 — 기본은 3단(세 항목씩 나란히)이며, 위쪽의 3단·2단·1단 버튼으로 배치를 바꿀 수 있습니다. 좁은 모바일 화면에서는 1단으로 열립니다.
• 바로 수정 — 입력·선택형 항목은 상세 화면에서 그대로 고칠 수 있고, 수정한 값은 목록의 해당 행에 즉시 반영되어 저장 대상이 됩니다. 읽기 전용 항목은 값만 표시됩니다.
• 닫기 — ✕ 버튼으로 상세 화면을 닫고 목록으로 돌아갑니다.
• 행을 선택하지 않고 누르면 행을 먼저 선택하라는 안내가 표시됩니다.

U6.그리드 편집과 집계

편집 가능한 그리드는 셀을 직접 수정하고 변경된 행만 저장할 수 있습니다. 화면 설정에 따라 상태 컬럼과 삭제 선택 컬럼이 표시됩니다.

• 원래 값으로 되돌리면 수정 상태가 해제될 수 있습니다.
• 필수값이 비어 있으면 저장 전에 안내하고 해당 셀로 이동합니다.
• 소계·합계 행은 계산 결과이며 선택·편집·저장 대상이 아닙니다.
• 필터 적용 시 집계값은 화면에 남은 데이터 기준으로 다시 계산됩니다.

U7.입력 및 선택

표시 상태 — 필수 항목은 별도 테두리나 표식으로 구분되고, 읽기 전용 항목은 잠긴 형태로 표시됩니다.

U8.데이터 등록·수정·삭제

• 편집 중 다른 데이터를 선택하면 변경내용이 사라질 수 있다는 확인 메시지가 표시될 수 있습니다.
• 저장 버튼이 보이지 않으면 먼저 신규 또는 수정 상태로 전환해야 하는 화면인지 확인합니다.
• 저장이 완료되면 성공 메시지와 갱신된 목록을 확인합니다.

U9.파일 첨부와 다운로드

• 추가 — 업로드 버튼으로 파일을 선택하거나 지원되는 영역에 파일을 끌어 놓습니다.
• 진행 — 업로드 중에는 진행률과 처리 상태를 확인할 수 있습니다.
• 다운로드 — 첨부 목록의 파일명 또는 행을 선택합니다.
• 삭제 — 삭제 대상으로 선택한 뒤 업무 데이터와 함께 저장합니다.
• 제한 — 허용되지 않은 형식이나 크기의 파일은 안내 후 등록되지 않습니다.

U10.문서 파일 바로 보기

첨부 목록이나 게시물의 문서 파일은 내려받아 다른 프로그램으로 열지 않아도 화면에서 바로 확인할 수 있습니다. 파일명이나 [미리보기]를 선택하면 파일 형식에 맞는 뷰어가 열립니다. PC와 모바일에서 같은 방식으로 동작합니다.

뷰어 툴바는 형식이 달라도 같은 원칙으로 동작합니다.

• 확대·축소 — [−]·[＋]로 조절하고, 가운데 배율 숫자를 누르면 100%로 돌아옵니다.
• 찾기 — 텍스트·XML 뷰어에서 낱말을 입력하고 Enter 또는 입력칸 밖을 누르면 일치 항목으로 이동합니다. [▲]·[▼]로 이전·다음 항목을 오가며, 현재 항목은 다른 색으로 강조됩니다.
• 내려받기 — [⤓]로 원본 파일을 저장합니다.
• 도움말 — [?]를 누르면 해당 뷰어의 조작법을 확인할 수 있습니다.

모바일에서는 문서 스크롤이 뷰어 안에서만 움직여 화면 전체가 딸려 내려가지 않으며, 긴 문서는 오른쪽의 두꺼운 스크롤 막대를 잡아 끌어 원하는 위치로 바로 이동할 수 있습니다.

U11.팝업과 새 창

새 창이 열리지 않으면 주소창의 팝업 차단 표시를 확인하고 현재 사이트의 팝업을 허용합니다.

U12.대시보드와 위젯

대시보드는 KPI·차트·목록 등의 위젯을 한 화면에 배치합니다. 편집 기능이 제공되는 경우 다음과 같이 개인화할 수 있습니다.

1. [편집]을 선택합니다.
2. 위젯을 드래그하여 위치를 바꾸고 크기를 조절합니다.
3. 필요한 위젯을 추가하거나 사용하지 않는 위젯을 제거합니다.
4. [저장]으로 배치를 유지하거나 [취소]로 이전 상태로 돌아갑니다.

U13.달력과 일정

날짜 선택 달력

• 일·월·연 또는 일시 단위로 값을 선택할 수 있습니다.
• 선택할 수 없는 날짜는 흐리게 표시되고 선택되지 않습니다.
• 기간 입력은 시작일과 종료일이 역전되지 않도록 조정됩니다.

일정 달력

• 이전·다음 버튼이나 좌우 스와이프로 월을 이동합니다.
• 일정은 날짜 칸의 막대로 표시되며 여러 날 일정은 이어서 표현됩니다.
• 날짜를 선택하면 해당 날짜의 일정 목록을 확인할 수 있습니다.

U14.트리와 차트

트리

• 확장·축소 아이콘으로 하위 항목을 접고 펼칩니다.
• 항목을 선택하면 연결된 상세정보가 표시됩니다.
• 대용량 트리는 화면에 보이는 항목만 처리하여 빠르게 스크롤할 수 있습니다.

차트

• 막대·선·영역 위에 포인터를 두면 정확한 값이 표시됩니다.
• 범례를 선택하면 데이터 계열을 숨기거나 다시 표시할 수 있습니다.
• 화면 크기가 바뀌면 차트 크기도 자동으로 조정됩니다.

U15.모바일과 반응형 화면

좁은 화면에서는 목록과 상세가 한 화면에 모두 표시되지 않고 단계적으로 전환될 수 있습니다.

1. 목록에서 항목을 선택합니다.
2. 상세가 전체 화면 형태로 열립니다.
3. 상세의 [목록] 버튼으로 이전 목록에 돌아갑니다.

• 넓은 그리드는 좌우 스와이프나 드래그로 이동합니다.
• 페이징 버튼 수와 도구 배치는 화면 폭에 맞게 줄어듭니다.
• 터치 대상은 모바일에서 누르기 쉬운 크기로 조정됩니다.

U16.테마·키보드·접근성

테마

다크·라이트·고대비 테마는 같은 기능을 서로 다른 명도와 색상으로 제공합니다. 선택한 테마는 다음 접속에도 유지될 수 있습니다.

키보드

• Tab과 Shift+Tab으로 입력요소와 버튼 사이를 이동합니다.
• Enter로 조회·선택·검색을 실행할 수 있는 화면이 있습니다.
• 슬라이더와 선택 목록은 방향키로 조작할 수 있습니다.

고대비

글자와 배경, 선택 상태와 경계를 더 명확하게 구분해야 할 때 고대비 테마를 사용합니다.

U17.메시지와 문제 해결

D1.MOCA 소개

MOCA는 표준 HTML·CSS·JavaScript 위에서 동작하는 프론트엔드 UI/UX 프레임워크입니다. 선언형 속성으로 업무 화면을 구성하고, 화면별 스코프와 공통 컴포넌트로 반복 코드를 줄입니다.

D2.MOCA Portable 시작하기

MOCA Portable은 제품 평가·학습·화면 개발을 위한 무설치 통합 개발환경입니다. 압축을 해제한 폴더 안에 실행도구, 편집기, IntelliSense와 샘플 프로젝트가 함께 들어 있습니다.

빠른 시작

1. 제공받은 ZIP 파일을 쓰기 가능한 폴더에 압축 해제합니다.
2. MOCA-시작.bat을 실행하여 샘플 애플리케이션과 브라우저를 엽니다.
3. MOCA-개발도구.bat을 실행하여 무설치 편집기와 작업공간을 엽니다.
4. HTML 화면을 수정하고 저장한 뒤 브라우저를 새로고침하여 결과를 확인합니다.

패키지 구성

MOCA-시작.bat          샘플 애플리케이션 실행
MOCA-개발도구.bat       MOCA IntelliSense가 설치된 편집기 실행
README-사용법.txt      시작 방법과 라이선스 안내
editor\                무설치 편집기와 확장
runtime\               실행에 필요한 내장 런타임
workspace\             샘플 프로젝트와 MOCA 엔진
  src\main\webapp\
    vendor\moca\       MOCA 엔진·문서
    system\demo\       샘플 화면
      ui\page\         업무 화면 HTML

폴더별 책임

첫 화면 수정 실습

1. 편집기에서 ui\page 아래의 HTML 화면 하나를 엽니다.
2. data-m-label 또는 검색영역의 문구를 바꾸고 저장합니다.
3. 브라우저에서 해당 화면만 새로고침하여 변경 결과를 확인합니다.
4. IntelliSense로 새 Input을 추가하고 data-m-placeholder를 입력합니다.
5. 레이아웃 미리보기에서 새 컴포넌트가 어느 칸에 들어갔는지 확인합니다.

시작 문제 확인

D3.MOCA IntelliSense

MOCA IntelliSense는 선언형 마크업과 공개 API를 편집기 안에서 탐색·작성·미리보기할 수 있게 하는 개발 도구입니다. VS Code 계열 편집기와 이클립스를 지원합니다. Portable에는 사전 설치되어 있으며, HTML 또는 JavaScript 파일을 열면 활성화됩니다. 아래 기능 표는 VS Code 확장 기준이고, 이클립스 지원 범위는 이 절 끝의 이클립스에서를 참고합니다.

VS Code에서 설치

MOCA IntelliSense는 마켓플레이스에 등록된 확장이 아니라 MOCA 소스 패키지의 vscode-moca 폴더에 소스로 포함되어 있습니다. Portable이 아닌 환경(소스 패키지를 직접 받은 PC)에서는 다음 순서로 설치합니다. 별도의 빌드나 의존성 설치는 필요 없습니다.

1. 소스 패키지의 루트 폴더에서 PowerShell로 설치 스크립트를 실행합니다.

   powershell -ExecutionPolicy Bypass -File vscode-mocainstall.ps1

   확장이 %USERPROFILE%.vscodeextensionsmoca-intellisense-<버전>에 복사되며, 이전 버전이 있으면 함께 정리됩니다.
2. VS Code에서 Ctrl+Shift+P → Developer: Reload Window를 실행합니다. 새 명령·메뉴가 보이지 않으면 한 번 더 실행합니다.
3. 상태표시줄 오른쪽에 MOCA 24가 표시되면 정상입니다. 이 표시를 클릭하면 읽어들인 카탈로그 파일이 열립니다.

자동완성 후보의 출처 — 확장은 워크스페이스 안의 vendor/moca/js/catalog.js를 읽습니다. MOCA 소스 패키지를 열지 않은 창에서는 후보가 없으며, 다른 위치의 카탈로그를 쓰려면 설정 moca.catalogPath 또는 명령 팔레트의 MOCA: catalog.js 위치 지정으로 경로를 지정합니다. 제거는 설치 스크립트에 -Uninstall을 붙여 실행하거나 확장 폴더를 삭제합니다.

권장 사용 순서

1. 명령 팔레트에서 MOCA: 새 화면 만들기를 실행합니다.
2. 레이아웃 방향·비율과 칸별 컴포넌트를 선택합니다.
3. Outline에서 화면 구조를 확인하고 각 컴포넌트의 속성을 자동완성으로 작성합니다.
4. MOCA: 레이아웃 미리보기에서 골격과 실행 결과를 확인합니다.
5. 정확한 세부 규격이 필요하면 API 문서를 엽니다.

자동완성 범위

새 화면 만들기

1. 화면 ID와 제목을 입력합니다.
2. 루트 Layout을 가로 또는 세로로 분할하고 비율·fit·auto 토큰을 지정합니다.
3. 필요하면 각 칸을 다시 분할하여 중첩 구조를 만듭니다.
4. 칸별로 검색영역·Grid·Form·Frame·빈 영역 등 기본 콘텐츠를 선택합니다.
5. 생성 전 미리보기에서 HTML 골격을 확인하고 파일을 생성합니다.

레이아웃 미리보기의 세 모드

편집 즉시 반영 — 실행 모드는 편집기에 열린 소스를 저장하기 전에도 그대로 그립니다. 타이핑, 속성 뷰의 값 변경, 미리보기 안의 텍스트 수정이 잠시 뒤 화면에 반영되며, 새 화면은 보이지 않는 곳에서 그려진 뒤 바꿔치기되므로 깜박이지 않습니다. 저장은 평소처럼 Ctrl+S로 하고, 공통 화면이나 서버 쪽을 고쳤을 때는 새로고침(↻)으로 전체를 다시 불러옵니다.

실행 모드와 로그인 — 실행 모드는 로컬 서버가 미리보기 인증 모드로 기동되어 있어야 로그인 없이 화면을 그립니다. 편집기 태스크 MOCA: 서버 기동이나 F5 디버그로 띄운 서버는 이 모드로 시작되며, 직접 기동할 때는 환경변수 MOCA_PREVIEW=1을 줍니다. 이 모드는 같은 PC 에서 온 미리보기 요청에만 적용되고, 샘플 애플리케이션 런처로 띄운 서버는 로그인이 필요한 제품 모드로 동작합니다.

세 방향 선택 동기화 — 소스 커서, 미리보기에서 선택한 칸·컴포넌트, MOCA Outline 항목은 같은 대상을 가리킵니다. HTML이 길어져도 현재 작업 위치와 화면 구조를 잃지 않게 해줍니다.

이클립스에서 — MOCA IntelliSense for Eclipse

SI 현장의 표준 개발환경인 이클립스(전자정부표준프레임워크 포함)를 위한 플러그인입니다. VS Code 확장과 같은 컴포넌트 규격(카탈로그)을 읽으므로, 어느 편집기에서 작성하든 제안 내용이 서로 어긋나지 않습니다.

설치

1. 플러그인 파일(jar)을 내려받아 이클립스 설치 폴더의 dropins 폴더에 복사합니다.
2. 이클립스를 완전히 종료했다가 다시 시작합니다.
3. HTML 편집기에서 moca를 입력하고 Ctrl+Space — 설치된 버전과 규격 파일 경로가 표시되면 정상입니다.

규격 자동 반영 — 플러그인은 프로젝트의 vendor/moca/docs/moca-catalog.json을 실행 중에 읽습니다. 엔진 규격이 갱신되면 재설치 없이 자동완성에 반영되며, 프로젝트에서 규격 파일을 찾지 못하면 플러그인에 내장된 사본으로 동작합니다.

D4.화면 구성 모델

MOCA 화면은 Layout 안에 Frame과 컴포넌트를 배치하고, 각 Frame에 독립된 화면 스코프를 부여하는 구조입니다.

<div data-m-type="layout" data-m-layout="vfit:auto" data-m-layout-part="root">
  <div data-m-layout-part="1">검색영역</div>
  <div data-m-layout-part="2" data-m-type="grid" id="grd_main">...</div>
</div>

구성 흐름

업무 화면 HTML
  └─ Layout: 화면 공간과 반응형 규칙
      ├─ Frame: 공통·자식 화면과 독립 Scope
      ├─ Form / Input 계열: 상세 데이터와 상태
      ├─ Grid: 목록·편집·선택·집계
      └─ Calendar / Tree / Widget / Echart: 고급 표현

화면 스크립트
  ├─ $p: 현재 화면
  ├─ $p.get(id): 현재 화면의 컴포넌트
  ├─ moca.$g: 공통 기능
  └─ moca.$t: 데이터 통신

선언과 명령의 역할

D5.스코프와 화면 생명주기

SPA에는 여러 화면이 동시에 존재하므로 전역 함수나 전역 DOM 탐색을 사용하면 같은 ID가 충돌할 수 있습니다. 모든 화면 함수와 컴포넌트 접근은 현재 화면의 $p를 기준으로 작성합니다.

공개 생명주기

애플리케이션 시작
  → Frame 화면 로드
  → 화면별 $p 스코프 생성
  → 컴포넌트 초기화
  → 자식 Frame 로딩 완료
  → 부모 $p.onpageload
  → 화면 표시 시 $p.onactivate
  → 화면 비활성화 시 $p.ondeactivate

$p.onpageload = function() {
  $p.grid = $p.get('grd_main');
  $p.fn_search();
};
$p.onactivate = function() { /* 화면이 다시 보일 때 */ };
$p.ondeactivate = function() { /* 화면이 가려질 때 */ };

주요 $p API

부모·자식 화면 접근

// 부모가 자식 Frame의 Grid 사용
var child = $p.get('frm_list').getScope();
var grid = child.get('grd_child');

// 자식이 부모 화면의 공개 함수 호출
var parent = $p.getParent().getScope();
parent.fn_refresh();

D6.표준 화면 개발 사이클

1. 화면 유형 결정 — 조회·목록, 배치편집, 목록·상세, 팝업, 대시보드 중 하나를 고릅니다.
2. 화면 생성 — 새 화면 만들기로 표준 HTML과 루트 Layout을 생성합니다.
3. 레이아웃 구성 — 검색·목록·상세 영역의 방향과 비율을 선언합니다.
4. 컴포넌트 선택 — 값을 입력·선택·표시하는 목적에 맞는 기존 컴포넌트를 고릅니다.
5. 스코프 코드 작성 — 함수와 상태를 $p에 두고 공개 API로 컴포넌트에 접근합니다.
6. 데이터 연동 — moca.$t 또는 프로젝트 통신 어댑터를 사용해 JSON 데이터를 연결합니다.
7. 상태·검증 연결 — Form·Grid·ButtonGroup의 상태관리와 필수값 검증을 활용합니다.
8. 품질 확인 — 넓은 화면·좁은 화면과 다크·라이트·고대비 테마에서 확인합니다.

D7.레이아웃과 반응형 설계

업무 화면의 골격은 Layout 컴포넌트로 작성합니다. 선언은 방향 문자 + 칸별 크기 토큰 하나로 끝납니다 — v는 세로(위·아래) 분할, h는 가로(좌·우) 분할이고, 토큰을 :로 나열한 개수가 곧 칸 수입니다. 2분할뿐 아니라 h4:3:3처럼 3칸 이상도 같은 방식으로 선언합니다.

크기 토큰 4종

• 비율 분할은 숫자끼리(2:1), 고정+나머지는 px·fit 칸과 auto의 짝으로 선언합니다. auto를 비율 숫자와 섞으면 의도가 읽히지 않습니다.
• 분할 없이 한 칸이 전체를 채우는 화면은 v1로 선언합니다(칸이 하나면 비율값은 의미가 없습니다).
• 토큰이 다른 종류끼리도 혼합됩니다 — vfit:auto:fit은 검색영역·본문·버튼줄 3칸 골격입니다.
• 더 복잡한 골격은 칸 안에 다른 Layout을 선언하는 중첩으로 구성합니다(검색·목록·상세·하위목록 복합화면).

실행 중 비율 변경

조회 조건이나 사용자 조작에 따라 분할을 바꿔야 하면 setRatio()를 사용합니다. 같은 문법의 토큰을 넘기며, 방향 문자를 붙이면 방향까지 바뀝니다. 한쪽을 0으로 주면 그 칸이 접혀 사이드 영역 토글에 쓸 수 있습니다.

$p.get('lay_body').setRatio('7:3');    // 비율만 변경
$p.get('lay_body').setRatio('v3:7');   // 방향까지 변경
$p.get('lay_body').setRatio('h0:10');  // 왼쪽 칸 접기

모바일 상세 전환

목록·상세 화면의 상세 칸에 data-m-mobileview="pop"을 지정하면 좁은 화면에서 목록을 우선 표시하고, 행 선택 시 상세를 전체화면 오버레이로 전환할 수 있습니다.

자주 쓰는 골격

레이아웃 점검

• 검색·헤더처럼 높이가 내용으로 결정되는 영역은 fit을 사용합니다.
• Grid·Tree·Chart처럼 남은 공간을 채워야 하는 영역은 auto 또는 비율 토큰을 사용합니다.
• 고정 px는 업무상 크기가 실제로 고정되어야 할 때만 사용합니다.
• 모바일에서 상세가 별도 단계가 되어야 하면 상세 칸에만 data-m-mobileview="pop"을 지정합니다.
• 골격 미리보기에서 칸 수와 토큰 수가 같은지 확인합니다.

D8.컴포넌트 소개

MOCA 컴포넌트는 화면을 구성하는 표준 UI 단위입니다. 표준 HTML의 div에 타입과 속성을 선언하고, $p.get()으로 인스턴스를 가져와 사용합니다. 이 장에서는 개별 컴포넌트를 살펴보기 전에 공통 사용법을 설명합니다.

<div data-m-type="input" id="ipt_title"
     data-m-required="true"></div>

<script>
$p.fn_read = function() {
  return $p.get('ipt_title').getValue();
};
</script>

속성·이벤트·메서드 구분

공통 연결 규칙

• id는 현재 화면 안에서 컴포넌트를 찾는 식별자입니다. 타입 접두사를 사용하면 소스와 자동완성을 읽기 쉽습니다.
• data-m-ref는 Input·Selectbox·Calendar 등의 값을 Form 행 데이터 필드와 연결합니다.
• data-m-required="true"는 Form·Grid의 validate()와 연결됩니다.
• data-m-readonly는 선언 초기값이며, 런타임 변경은 각 컴포넌트의 setReadOnly()를 사용합니다.
• 이벤트 함수는 전역 이름이 아니라 $p.fn_* 형태로 선언합니다.

표준 class는 MOCA가 부여합니다

컴포넌트의 표준 스타일 class는 타입에 맞춰 MOCA가 자동으로 부여하므로 화면에서 적지 않습니다. 화면이 class에 적는 것은 정렬·여백 같은 프로젝트 전용 class뿐입니다. 표시나 동작을 바꾸는 값은 class가 아니라 속성으로 지정합니다. 속성은 값이 정해져 있어 잘못 쓰면 콘솔이 알려주지만, class는 틀려도 아무 알림 없이 모양만 달라집니다.

컴포넌트 도판 위치

하나의 화면에 함께 배치되는 입력 컴포넌트는 공통 도판으로 묶고, 구조·업무·시각화 컴포넌트는 대표 동작이 보이는 도판에 연결했습니다.

D9.화면 구조 컴포넌트

화면 구조 컴포넌트는 콘텐츠를 직접 입력받기보다 화면의 공간과 이동 단위를 정의합니다. Layout과 Frame은 모든 업무 화면의 기반이며, Tab과 MDI는 여러 화면을 전환하는 컨테이너입니다.

D9-1. Layout — 화면 골격

layout은 화면을 상하·좌우·중첩 구조로 나누는 필수 골격 컴포넌트입니다. 직접 flex 비율이나 높이를 계산하지 않고 화면의 의도를 토큰으로 선언합니다.

<div data-m-type="layout" id="lay_page"
     data-m-layout="vfit:auto" data-m-layout-part="root">
  <div data-m-layout-part="1">검색영역</div>
  <div data-m-layout-part="2" id="lay_body"
       data-m-type="layout" data-m-layout="h4:6">
    <div data-m-layout-part="2.1">목록</div>
    <div data-m-layout-part="2.2" data-m-mobileview="pop">상세</div>
  </div>
</div>

<script>
// 본문 Layout의 좌측 칸을 접고 우측 칸을 확장
$p.get('lay_body').setRatio('h0:1');
</script>

레이아웃 구조 확인

루트 Layout 오른쪽 아래의 [레이아웃 구조 보기] 버튼을 누르면 현재 화면의 중첩 방향과 비율 토큰이 각 영역 위에 표시됩니다. 화면 골격을 확인한 뒤 같은 버튼을 다시 누르면 원래 업무 화면으로 돌아옵니다.

D9-2. Frame — 자식 화면 로드와 스코프 생성

frame은 다른 HTML 화면을 현재 화면에 포함하고, 포함된 화면마다 독립된 $p 스코프를 생성합니다.

<div data-m-type="frame" id="frm_title"
     data-m-src="./common/title.html"
     data-m-label="사용자 관리"></div>

<script>
// 자식 화면 로드 완료 후 자식 스코프의 공개 함수 호출
var childScope = $p.get('frm_title').getScope();
if (childScope) childScope.fn_refresh();
</script>

초기화 순서 — 자식 Frame의 컴포넌트와 onpageload가 끝난 뒤 부모 화면의 onpageload가 실행됩니다. 따라서 부모 초기화 시 자식의 스코프와 컴포넌트를 바로 가져올 수 있습니다.

D9-3. Tab — 화면 내부 패널 전환

tab은 하나의 업무 화면 안에서 여러 패널을 전환합니다. 선언 탭과 동적 탭을 함께 사용할 수 있습니다.

var tab = $p.get('tab_detail');

tab.addTab({
  id: 'tabHistory',
  text: '변경이력',
  src: './history.html',
  closable: true,
  select: true
});

tab.setTabDisabled('tabHistory', true);
tab.setTabTitle('tabHistory', '변경이력(12)');

D9-4. MDI — 애플리케이션 업무 탭

mdi는 애플리케이션 전체의 업무 화면 탭을 관리하는 셸 전용 컴포넌트입니다. 일반 업무 화면 안에서는 직접 만들기보다 이미 구성된 MDI의 공개 메서드를 사용합니다.

D10.폼·입력 컴포넌트

입력 컴포넌트는 값의 종류와 선택 방식에 맞게 고릅니다. Form의 data-m-ref 매핑을 사용하면 한 행의 데이터를 필드에 일괄 설정하고 수정값을 Grid와 자동으로 동기화할 수 있습니다.

D10-1. Form — 입력영역·상태·검증

<div data-m-type="form" id="fom_detail"
     data-m-variant="form"
     data-m-refgrid="grd_main"
     data-m-readonly="true">
  <div data-m-type="input" id="ipt_name"
       data-m-ref="NAME"
       data-m-required="true"></div>
</div>

D10-2. Input — 한 줄 입력

<div data-m-type="input" id="ipt_amount"
     data-m-keymask="onlyNumber"
     data-m-displayfunction="moca.$g.comma"
     data-m-required="true" data-m-maxlength="12"></div>

D10-3. Textarea — 여러 줄 입력

getValue(), setValue(), setReadOnly()로 값을 관리합니다.

D10-4. Selectbox — 정해진 목록 선택

<div data-m-type="selectbox" id="cmb_useYn"
     data-m-itemset='[{"cd":"Y","nm":"사용"},{"cd":"N","nm":"미사용"}]'
     data-m-defaultvalue="Y"
     data-m-onchange="$p.fn_useChanged"></div>

D10-5. Combobox — 검색 가능한 목록 선택

후보가 많아 사용자가 글자를 입력해 좁혀야 할 때 사용합니다. 기본 목록 키와 부모 연동 규칙은 Selectbox와 같습니다.

getValue(), getLabel(), getList(), setValue(), setReadOnly(), draw(), setList()를 제공합니다.

D10-6. Radio — 단일 선택

getValue(), getLabel(), setValue(), setReadOnly(), redraw()를 제공합니다.

D10-7. CheckboxGroup — 복수·독립 선택

getValue()는 단일형이면 boolean, 그룹형이면 선택된 값의 배열을 반환합니다. setValue(), setReadOnly(), redraw()도 제공합니다.

D10-8. Toggle — 두 상태 전환

isOn(), getValue(), setValue(), setReadOnly()를 제공합니다.

<div data-m-type="toggle" id="tog_use"
     data-m-label="사용"
     data-m-truevalue="Y" data-m-falsevalue="N"
     data-m-onchange="$p.fn_toggleChanged"></div>

D10-9. Slider — 범위값 선택

getValue(), setValue(), setReadOnly()를 제공합니다.

D10-10. InputCalendar·InputMultiCalendar — 날짜·기간 입력

<div data-m-type="inputCalendar" id="cal_workDt"
     data-m-datetype="yyyyMMdd"
     data-m-displayformat="####-##-##"
     data-m-datemin="20260101" data-m-datemax="20261231"></div>

D10-11. InputPop — 팝업 검색 입력

openPop(option), getValue(), setValue(), setReadOnly()를 제공합니다.

D10-12. Ckeditor — 리치 텍스트(HTML) 본문

게시글·공지·메일 본문처럼 글꼴·표·이미지가 들어가는 본문은 data-m-type="ckeditor"로 넣습니다. CKEditor 4를 감싼 컴포넌트이므로 화면에 <script> 태그를 넣지 않습니다 — 화면에 선언이 있으면 MOCA가 필요할 때 불러옵니다. 값은 HTML 문자열로 주고받습니다.

1) 넣는 자리 — 상세 폼의 한 행. 에디터는 상세 폼(data-m-variant="form")의 td에 넣고 폭과 높이를 적지 않습니다(style="width:…; height:…" 없이). 에디터는 칸의 가로를 끝까지 채우고, 상세 폼은 칸의 남는 높이를 스스로 채우면서 에디터·Textarea가 든 행에 그 높이를 줍니다. 그래서 창 크기가 바뀌거나 모바일로 넘어가도 에디터가 카드에 맞춰 가로·세로로 늘고 줄어듭니다.

<div data-m-type="form" data-m-variant="form" id="fom_detail" data-m-label="게시글">
  <div data-m-body="tbody">
    <div data-m-row="tr">
      <div data-m-cell="th">제목</div>
      <div data-m-cell="td"><div data-m-type="input" id="ipt_title" data-m-ref="TITLE"></div></div>
    </div>
    <div data-m-row="tr">
      <div data-m-cell="th">내용</div>
      <div data-m-cell="td"><div data-m-type="ckeditor" id="edt_body"></div></div>   <!-- 높이 없음 — 이 행이 늘어난다 -->
    </div>
  </div>
</div>

에디터가 아닌 다른 행을 늘리고 싶을 때만 폼에 class="flex", 늘릴 행에 class="flex-grow1"을 줍니다. 화면 전체는 레이아웃 컴포넌트로 짜고, 에디터 폼이 든 칸은 auto(남는 높이)로 둡니다 — 예: data-m-layout="vfit:auto"의 두 번째 칸, 좌우 분할이면 h5:5의 한쪽.

2) 값 다루기. 조회한 본문은 setValue(html), 저장할 본문은 getValue()로 받습니다. 본문은 다른 필드와 달리 data-m-ref로 묶지 않고 저장 직전에 따로 읽어 요청에 싣습니다.

$p.onpageload = function () {
  $p.edt = $p.get('edt_body');
  $p.edt.getEditor();                       // 빈 본문으로 시작하는 화면이면 에디터를 바로 만든다
};
$p.fn_save = function () {
  var _row = $p.get('fom_detail').getRowJSON();
  _row.CONTENT = $p.edt.getValue();         // 본문 HTML
  // … 저장 요청
};

3) 기본 본문·서명. 본문을 미리 채우려면 화면이 열릴 때 setValue()로 넣습니다(예: 빈 줄 + 서명 이미지). 메일처럼 밖으로 보내는 HTML에 이미지를 넣을 때는 받는 쪽이 인터넷에서 읽을 수 있도록 https://로 시작하는 절대주소를 쓰고, 메일 프로그램은 스타일시트를 읽지 않으므로 크기는 <img width="360" style="max-width:100%">처럼 태그에 직접 적습니다.

4) 보기 전용(data-m-toolbar="View"). 남이 쓴 HTML(받은 메일, 외부에서 온 본문)은 편집하지 않는 에디터로 보여 줍니다. 에디터는 자기 iframe 안에 본문을 그리므로 본문의 스타일이 화면을 흔들지 않고, 화면의 스타일도 본문을 흔들지 않습니다. 넣기 전에 moca.$g.sanitizeHtml(html)로 실행되는 것(script·이벤트 속성)을 걷어낸 뒤 setValue()합니다. 보기 전용 에디터는 폼 td가 아니라 레이아웃 칸에 바로 두어도 칸의 가로·세로를 채웁니다 — 팝업에서 머리 정보(폼) 아래 본문 칸을 auto로 두면 본문이 남는 높이를 가져갑니다.

<div data-m-type="layout" data-m-layout="vfit:auto:fit" data-m-layout-part="root" data-m-height="680">
  <div data-m-layout-part="1"> … 보낸 사람·날짜 보기 폼 … </div>
  <div data-m-layout-part="2"><div data-m-type="ckeditor" id="edt_view" data-m-toolbar="View"></div></div>
  <div data-m-layout-part="3" class="bd_modal_btns pop_btn_area"> … [삭제] [목록] … </div>
</div>
$p.get('edt_view').setValue(moca.$g.sanitizeHtml(mailHtml));

5) 테마·모바일. 다크·라이트·고대비 테마 색은 MOCA가 에디터 안쪽까지 맞추므로 화면이 색을 정하지 않습니다. 좁은 화면에서는 툴바가 짧은 구성으로 바뀌고, 폼이 세로로 쌓이면서 에디터 행이 남는 높이를 계속 채웁니다.

D11.업무 처리 컴포넌트

Grid, ButtonGroup, FileUpload, FloatingButton은 조회·편집·저장 중심의 업무 화면을 구성합니다. 이 가운데 Grid는 속성이 가장 많으므로 그리드 전체, 헤더, 데이터 셀로 나누어 이해하는 것이 좋습니다.

D11-1. Grid — 선언 구조

<div data-m-type="grid" id="grd_main"
     data-m-label="사용자 목록"
     data-m-rownum="true"
     data-m-rowstatus="true"
     data-m-delcheck="true"
     data-m-toolbarbtnpc='{"addrow":"true","delrow":"true","exdn":"true","full":"true"}'
     data-m-onrowselected="$p.fn_rowSelected">
  <div data-m-body="tbody">
    <div data-m-row="tr">
      <div data-m-cell="th" data-m-sortable="true">이름</div>
      <div data-m-cell="th" data-m-filterable="true">상태</div>
    </div>
    <div data-m-row="tr">
      <div data-m-cell="td" id="NAME"
           data-m-celltype="input"
           data-m-required="true"
           data-m-maxlength="50"></div>
      <div data-m-cell="td" id="USE_YN"
           data-m-celltype="selectbox"
           data-m-itemset='[{"code":"Y","codeNm":"사용"},{"code":"N","codeNm":"미사용"}]'></div>
    </div>
  </div>
</div>

Grid 전체 속성

툴바 속성

툴바의 행 상세보기는 detail 키로 켭니다. 값에 따라 동작이 갈립니다.

<div data-m-type="grid" id="grd_main"
     data-m-toolbarbtnpc='{"detail":"true","exdn":"true","full":"true"}'
     data-m-toolbarbtnmobile='{"detail":"true"}'>

• "detail":"true" — 내장 상세뷰를 엽니다. 선택 행의 모든 컬럼이 「라벨 — 값」으로 펼쳐지며 기본 3단(버튼 순서 3·2·1단, 모바일은 1단 고정)입니다. 입력·콤보·검색콤보·라디오·체크박스 셀타입은 상세뷰에서 실제 컴포넌트로 렌더되어 편집할 수 있고, 수정한 값은 setCellData() 경로로 그리드 행에 반영되어 행상태(U)와 저장 대상에 포함됩니다. 읽기 전용(data-m-readonly)이나 표시함수(data-m-displayfunction)가 있는 컬럼, 그 밖의 셀타입은 값만 표시됩니다.
• "detail":"dblclick" — 내장 상세뷰 대신 버튼이 화면의 data-m-ondblclick 함수를 호출합니다. 목록·상세 패턴(D13-3)처럼 화면이 자체 상세 UI(폼·팝업)를 가진 경우, 더블클릭과 같은 진입을 툴바 버튼으로도 제공할 때 씁니다.
• 행을 선택하지 않은 상태에서 누르면 선택 안내 메시지가 표시됩니다.

컬럼·헤더 속성

데이터 셀 속성

Grid 이벤트

Grid 주요 메서드

집계 예

<div data-m-type="grid" id="grd_sales"
     data-m-subtotal="REGION_NM"
     data-m-total="top"
     data-m-subtotallabel="소계"
     data-m-totallabel="총계">
  ...
  <div data-m-cell="td" id="SALE_QTY"
       data-m-celltype="input" data-m-readonly="true"
       data-m-displayfunction="moca.$g.comma"
       data-m-calc="sum"></div>
</div>

D11-2. ButtonGroup — Form 상태 기반 버튼

applyStatus()는 Form 상태를 다시 읽어 버튼과 제목을 갱신하고, getButton(label)은 특정 버튼 엘리먼트를 반환합니다.

<div data-m-type="buttonGroup" id="btg_detail"
     data-m-form="fom_detail" data-m-title="detailTitle"
     data-m-buttons="신규|$p.fn_new,수정,저장|$p.fn_save,취소,삭제|$p.fn_delete"></div>

D11-3. FileUpload — 첨부파일 목록과 저장

D11-4. FloatingButton — 화면 위에 떠 있는 액션 버튼

FloatingButton은 화면 위에 떠 있는 원형·알약형 액션 버튼(FAB)입니다. 기본은 우측 하단 고정이며, 라벨을 지정하면 아이콘 옆에 텍스트가 붙는 알약형이 됩니다. 버튼을 길게 누르면 드래그 모드로 전환되어 원하는 위치로 옮길 수 있고, 짧게 누르면 그대로 클릭으로 동작합니다. ButtonGroup이 모바일 목록 위에 자동으로 만드는 신규 버튼과 레이아웃 골격 미리보기 버튼도 이 컴포넌트로 렌더링됩니다.

show()·hide() 메서드로 표시 여부를 제어합니다.

<div data-m-type="floatingButton" id="fab_new" data-m-label="신규"
     data-m-icon="plus" data-m-onclick="$p.fn_new"></div>

<!-- 파일 아이콘 + 테마 색 자동 추종 -->
<div data-m-type="floatingButton" id="fab_search" aria-label="일정 찾기"
     data-m-icon="/vendor/moca/images/icon_search.svg" data-m-iconmode="mask"
     data-m-onclick="$p.fn_searchOpen"></div>

D12.시각화·계층 컴포넌트

날짜·일정·계층·대시보드·차트는 복잡한 렌더링을 컴포넌트가 담당하도록 데이터와 표시 옵션을 분리합니다.

D12-1. Calendar — 붙박이 날짜 선택

D12-2. ScheduleCalendar — 월간 일정

setData({schedules,dayInfo,hideOutside})로 일정과 날짜 메타를 그립니다. getDayItems(), getDayInfo(), getYm(), setYm(), today(), next(), prev(), refresh(), setDayRenderer()를 제공합니다.

$p.get('sch_plan').setData({
  schedules: [
    { start:'20260810', end:'20260812', title:'제품 심사', crucial:true },
    { start:'20260815', title:'결과 정리', done:true }
  ],
  dayInfo: {
    '20260815': { holi:'광복절' }
  }
});

D12-3. Treeview — 일반 계층

전체 노드를 한 번에 렌더링해도 부담이 없는 메뉴·조직·분류 데이터에 사용합니다.

D12-4. VirtualTree — 대용량 계층

setData(), getData(), getSelectedNode(), selectById(), scrollToId(), expand/collapse/toggle(), expandAll/collapseAll(), getVisibleCount(), getTotalCount(), getRenderedCount(), refresh(), destroy()를 제공합니다.

D12-5. Widget — 개인화 대시보드

D12-6. Echart — 데이터 시각화

$p.get('cht_sales').setData({
  tooltip: { trigger:'axis' },
  xAxis: { type:'category', data:['1월','2월','3월'] },
  yAxis: { type:'value' },
  series: [{ name:'매출', type:'bar', data:[120,180,150] }]
});

D13.문서·파일 뷰어 컴포넌트

뷰어 컴포넌트는 업무 파일을 내려받지 않고 화면 안에서 바로 보여줍니다. 다른 컴포넌트와 같이 div에 타입을 선언하면 장착이 끝나며, 형식별로 필요한 렌더링 라이브러리는 엔진이 해당 뷰어를 처음 사용할 때 자동으로 로드하므로 화면에 <script src>를 추가하지 않습니다.

D13-1. 장착 방법

가장 기본은 화면 레이아웃 칸에 직접 배치하는 것입니다. 뷰어는 부모가 준 높이를 100% 채우므로 높이가 관리되는 레이아웃 칸에 두면 별도 크기 계산이 필요 없습니다.

<div data-m-layout-part="1" data-m-type="pdfviewer" id="pdv_main"
     data-m-src="/files/manual.pdf"></div>

문서를 실행 중에 바꿀 때는 load()를 사용합니다. 조회 결과의 파일 경로를 그대로 전달합니다.

$p.get('pdv_main').load('/common/download.do?fileId=' + row.FILE_ID);

첨부 목록처럼 여러 형식의 파일을 다루는 화면은 형식 판별과 팝업 구성을 직접 만들지 않고 공용 API 한 줄로 엽니다. 확장자에 맞는 뷰어를 골라 레이어 팝업으로 띄우며, 소스·설정·전문처럼 담당 뷰어가 따로 없는 텍스트성 파일과 미지의 확장자는 텍스트 뷰어로 열립니다 — 내용이 바이너리로 판별되면 뷰어가 안내와 함께 스스로 내려받기로 전환합니다. 확장자만으로 바이너리가 확실한 파일(실행 파일·동영상 등)만 false를 반환하므로 그때 내려받기로 폴백합니다.

if (!moca.$g.openFileViewer({ url: _url, name: row.FILE_NAME })) {
  $p.fn_download(row);   // 확장자만으로 바이너리가 확실한 형식(실행 파일 등)만 여기로 온다
}

모달 대신 화면 안에서 열 수도 있습니다 — target에 영역(요소 또는 id)을 주면 확장자에 맞는 뷰어가 그 자리에 열리고, 다른 파일을 다시 열면 이전 뷰어를 정리한 뒤 교체합니다. 목록 옆 미리보기 패널처럼 행을 옮길 때마다 바로바로 보여주는 화면에 적합하며, 영역은 레이아웃 칸처럼 높이가 관리되는 자리에 둡니다.

moca.$g.openFileViewer({ url: _url, name: row.FILE_NAME, target: 'pnl_preview' });

D13-2. 공통 규약

D13-3. 형식별 대표 옵션

속성·이벤트·메서드의 전체 규격은 MOCA API 문서의 각 뷰어 항목에서 확인합니다.

D14.표준 화면 패턴

표준 화면 패턴은 화면마다 조회·선택·편집 상태를 새로 구현하지 않기 위한 조합 규칙입니다. 먼저 사용자가 처리할 데이터 단위와 편집 위치를 결정한 뒤 가장 가까운 패턴을 선택합니다.

D14-1. 조회·목록

검색조건은 Form으로 묶고 결과는 Grid에 전달합니다. 검색 버튼과 Enter 입력은 같은 조회 함수를 호출하게 하여 검색 경로가 달라도 결과와 진행 상태가 같도록 구성합니다.

$p.fn_search = async function(page) {
  var _form = $p.get('fom_search');
  var _grid = $p.get('grd_main');
  var _res = await moca.$t.exe({
    url: '/api/items',
    data: {
      page: page || 1,
      keyword: $p.get('ipt_keyword').getValue(),
      useYn: $p.get('cmb_useYn').getValue()
    },
    progressMsg: '조회 중입니다.'
  });

  _grid.draw(_res.items || [], _res);
};

D14-2. Grid 배치편집

한 행이 하나의 처리 단위이고 별도 상세 Form이 필요 없다면 Grid 안에서 편집합니다. Grid가 관리하는 C(신규)·U(수정)·D(삭제) 상태를 저장 요청의 변경분으로 사용합니다.

$p.fn_add = function() {
  $p.get('grd_main').addRow(0, { USE_YN:'Y' });
};

$p.fn_save = async function() {
  var _grid = $p.get('grd_main');
  if (!_grid.validate()) return;

  var _changes = _grid.getModifiedJSON();
  if (!_changes.length) {
    moca.$g.alert('변경된 내용이 없습니다.');
    return;
  }
  await moca.$t.exe({ url:'/api/items/batch', data:{ items:_changes } });
  await $p.fn_search();
};

행 삭제는 DOM을 직접 제거하지 않고 removeRow()를 사용합니다. 신규행은 목록에서 제거되고, 기존행은 삭제 상태로 관리되어 저장 대상에 포함됩니다.

D14-3. 목록·상세 자동 연동

Form의 참조 Grid와 ButtonGroup을 연결하면 행 선택에 따른 폼 채움, 읽기·편집 상태, 버튼 전환과 취소 복구를 공통 컴포넌트가 처리합니다.

<div data-m-type="grid" id="grd_main" data-m-editguard="true">...</div>

<div data-m-type="form" id="fom_detail" data-m-variant="form"
     data-m-refgrid="grd_main" data-m-readonly="true">...</div>

<div data-m-type="buttonGroup" id="btg_detail"
     data-m-form="fom_detail"
     data-m-buttons="신규|$p.fn_new,수정,저장|$p.fn_save,취소,삭제|$p.fn_delete"></div>

D14-4. 팝업 검색

팝업은 독립된 MOCA 화면입니다. 여는 화면은 초기 조건을 data로 보내고, 팝업은 $p.getParameter()로 읽습니다. 사용자가 확정한 경우에만 $p.close(result)로 값을 반환합니다.

// 여는 화면
$p.openPop({
  url: '/ui/POP_ITEM.html',
  title: '품목 검색',
  width: '720px',
  data: { keyword: $p.get('ipt_itemNm').getValue() },
  callback: function(row) {
    $p.get('ipt_itemCd').setValue(row.ITEM_CD);
    $p.get('ipt_itemNm').setValue(row.ITEM_NM);
  }
});

// 팝업 화면
$p.onpageload = function() {
  var _param = $p.getParameter();
  $p.get('ipt_keyword').setValue(_param.keyword || '');
  $p.fn_search();
};
$p.fn_select = function() {
  var _row = $p.get('grd_result').getSelectedRowJSON();
  if (_row) $p.close(_row);
};

D14-5. 대시보드

Widget은 배치와 편집 상태를 관리하고, 각 카드의 실제 내용은 독립 Frame 화면으로 구성합니다. 목록·KPI·차트는 자신의 조회와 렌더링만 책임지며, 크기가 바뀔 때 필요한 처리는 생명주기 훅에 둡니다.

$p.onwidgetrefresh = function(ctx) {
  $p.fn_loadWidget(ctx.id);
};

$p.onwidgetresize = function() {
  var _chart = $p.get('cht_summary');
  if (_chart) _chart.resize();
};

$p.onwidgetdestroy = function() {
  clearInterval($p.refreshTimer);
};

패턴 선택 체크

1. 사용자가 저장하는 최소 데이터 단위가 행인지 상세 객체인지 정합니다.
2. 읽기와 편집 상태가 분리되어야 하면 Form과 ButtonGroup 조합을 사용합니다.
3. 다른 화면에 값을 돌려주어야 하면 팝업 검색 패턴을 사용합니다.
4. 크기 변경과 부분 새로고침이 독립적이어야 하면 Widget 카드로 분리합니다.
5. 직접 상태 전환 코드를 만들기 전에 컴포넌트의 참조·검증·변경분 API를 확인합니다.

D15.공개 API와 데이터 연동

화면 코드는 전역 DOM 탐색보다 현재 화면 스코프의 공개 API를 사용합니다. 컴포넌트 접근은 $p, 공통 표현과 검증은 moca.$g, 날짜는 moca.$g.date, 서버 통신은 moca.$t가 담당합니다.

D15-1. $p — 현재 화면의 경계

$p.onpageload = function() {
  var _param = $p.getParameter();
  $p.get('ipt_keyword').setValue(_param.keyword || '');

  $p.code({
    'cmb_useYn': { code: 'USE_YN' },
    'cmb_type':  { queryId: 'selectItemTypeCombo', allOption: { value: '', label: '전체' } }
  }, $p.fn_search);
};

D15-2. moca.$g — 메시지·값·표시 유틸리티

$p.fn_delete = function() {
  moca.$g.confirm('선택한 항목을 삭제하시겠습니까?', async function() {
    try {
      await moca.$t.delete({
        url: '/api/items',
        data: { list: $p.get('grd_main').getSelectedRowJSON() }
      });
      await $p.fn_search();
    } catch (e) {
      moca.$g.error('삭제 처리 중 오류가 발생했습니다.');
    }
  });
};

D15-3. moca.$g.date — 숫자 문자열 날짜 규약

날짜 값은 yyyyMMdd, 연월은 yyyyMM, 일시는 yyyyMMddHHmmss 숫자 문자열을 사용합니다. 화면 표시 형식은 값 자체와 분리하고 format() 또는 컴포넌트 표시 속성으로 지정합니다.

var _today = moca.$g.date.getToday();
$p.get('cal_from').setValue(moca.$g.date.addDay(_today, -7));
$p.get('cal_to').setValue(_today);

var _label = moca.$g.date.format(_today, 'yyyy년 M월 d일 (E)');

D15-4. moca.$t — 공통 통신

$p.fn_load = async function() {
  var _result = await moca.$t.exe({
    url: '/api/items',
    data: { keyword: $p.get('ipt_keyword').getValue() },
    progressMsg: '조회 중입니다.'
  });
  $p.get('grd_main').drawGrid(_result.items || []);
};

callback과 await를 모두 지원하지만 한 함수 안에서는 한 방식을 선택합니다. 여러 요청을 순서대로 처리하거나 오류를 한 곳에서 다룰 때는 async/await가 읽기 쉽습니다.

D15-5. 데이터 계약과 오류 처리

연동 원칙

• MOCA 화면은 JSON 요청·응답 계약을 기준으로 하며 서버 구현 기술과 분리합니다.
• 공통 통신 API를 사용하면 진행 표시, 오류 처리, CSRF 헤더와 응답 처리를 일관되게 적용할 수 있습니다.
• 특정 시스템의 URL·필드·인증 규칙은 프로젝트 설정이나 연동 어댑터에서 관리합니다.
• 화면마다 진행 레이어와 오류 알림을 새로 만들지 말고 공통 통신 흐름을 사용합니다.
• 전체 옵션과 반환 형식은 MOCA API 문서에서 확인합니다.

D16.설정·테마·접근성

프로젝트 공통값은 화면마다 반복하지 않고 MOCA 설정에 둡니다. 개별 화면 속성은 해당 화면만 달라야 할 때 사용하며, 테마와 접근성은 기능 구현이 끝난 뒤가 아니라 컴포넌트 선택과 화면 구조 단계에서 함께 결정합니다.

프로젝트 설정

var mconfig = {
  mocaHome: '/vendor/moca',
  vendorHome: '/vendor',
  componentSize: {
    input: '180px',
    selectbox: '180px',
    inputCalendar: '150px'
  },
  calendarDateRange: { min:'20000101', max:'20991231' },
  loginUrl: '/login.html'
};

테마

색상은 의미 기반 테마 변수로 정의하고 컴포넌트는 동일한 변수를 사용합니다. 새 화면은 다크·라이트·고대비에서 텍스트, 경계, 선택, 오류 상태가 구분되는지 확인합니다.

반응형 화면

CSS와 JavaScript가 서로 다른 폭 기준을 사용하면 같은 화면에서 표시와 동작이 어긋납니다. 코드에서 폭 기반 동작을 결정할 때는 moca.$g.isMobileView(element)를 사용합니다.

• 목록·상세 화면의 상세 칸에는 data-m-mobileview="pop"을 적용합니다.
• 좁은 화면에서 중요도가 낮은 Grid 열은 data-m-mobilehide="true"로 숨깁니다.
• 가로 Layout을 세로로 전환할 때 필요한 칸 높이는 data-m-mobileheight로 지정합니다.
• 모바일에 같은 정보를 별도 마크업으로 복제하지 말고 동일한 컴포넌트의 배치와 표시 속성을 조정합니다.

접근성

화면 완료 전 조합 검사

1. 프로젝트 공통값을 화면마다 중복 선언하지 않았는지 확인합니다.
2. 넓은 화면과 좁은 화면에서 정보 우선순위와 동작이 유지되는지 확인합니다.
3. 라이트·다크·고대비 테마에서 선택·오류·포커스를 구분합니다.
4. 키보드만으로 검색, 행 선택, 편집, 저장, 팝업 닫기를 수행합니다.

D17.프론트엔드 보안과 서버 연동 계약

MOCA는 화면 렌더링과 공통 통신에서 반복되는 보안 처리를 제공합니다. 서버는 인증·권한·토큰 검증과 업로드 정책을 반드시 별도로 적용해야 하며, 화면에서 버튼을 숨기는 것만으로 권한을 보장할 수 없습니다.

보안 책임 경계

XSS 무해화

• Grid·Form·Input·팝업·탭·위젯 등 공통 렌더링 경로는 외부 값을 무해화합니다.
• 화면에서 직접 문자열을 그릴 때 일반 텍스트는 textContent를 사용합니다.
• 표시용 HTML이 필요하면 moca.$g.sanitizeHtml(), 속성값은 moca.$g.escapeAttr()을 사용합니다.

// 일반 텍스트
element.textContent = row.TITLE;

// 제한된 표시 마크업
element.innerHTML = moca.$g.sanitizeHtml(row.CONTENT);

CSRF 연동

// 공통 통신을 사용할 때 토큰 헤더는 자동 적용됩니다.
await moca.$t.exe({
  url: '/api/items',
  data: { item: _item }
});

// 직접 요청이 불가피한 경우에만 헤더를 명시합니다.
await fetch('/api/items', {
  method: 'POST',
  headers: moca.$g.csrfHeaders({ 'Content-Type':'application/json' }),
  body: JSON.stringify({ item:_item })
});

인증과 권한

• 인증 만료 응답은 공통 처리하여 로그인 화면으로 이동할 수 있습니다.
• 조회·저장·삭제·파일 요청의 최종 권한은 서버에서 판정합니다.
• 공개 데이터는 명시적으로 구분하고, 기본값은 인증이 필요한 상태로 설계합니다.

파일 업로드

• 클라이언트 제한은 사용성 보조이며 최종 파일형식·크기·경로 검증은 서버에서 수행합니다.
• 실행 가능한 형식, 이중확장자, 경로 이탈을 차단하고 저장 파일명은 안전하게 변환합니다.
• 화면에 표시하는 원본 파일명도 외부 입력값으로 취급합니다.

민감정보와 오류 메시지

• 비밀번호, 토큰, 개인식별정보를 URL 파라미터나 화면 로그에 넣지 않습니다.
• 오류 알림에는 사용자가 다음 행동을 결정하는 데 필요한 정보만 표시합니다.
• 통신 실패 응답의 원문을 그대로 HTML로 출력하지 않습니다.
• 브라우저 저장소에는 화면 기능에 꼭 필요한 최소 정보만 보관하고 만료 흐름을 둡니다.

보안 연동 완료 체크

1. 외부 값이 들어가는 모든 위치를 텍스트·속성·HTML 문맥으로 구분했는가?
2. 상태를 바꾸는 요청이 공통 통신 또는 CSRF 헤더를 사용하는가?
3. 화면의 버튼 표시와 별개로 서버가 조회·저장·삭제 권한을 검증하는가?
4. 인증 만료 시 부분 화면에 오류만 남지 않고 공통 로그인 흐름으로 이동하는가?
5. 업로드 제한이 화면 안내에만 머물지 않고 서버에서도 검증되는가?
6. 오류 메시지와 로그에 민감정보가 포함되지 않는가?

D18.문제 해결과 체크리스트

증상부터 코드를 넓게 바꾸기보다 로드 → 스코프 → 선언 → 데이터 → 상태 → 반응형 순서로 범위를 좁힙니다. 같은 ID가 여러 화면에 있을 수 있으므로 오류가 발생한 Frame과 그 화면의 $p를 먼저 확인합니다.

D18-1. 진단 순서

1. 화면 로드 — HTML과 필요한 리소스 요청이 성공했고 $p.onpageload까지 실행되었는지 확인합니다.
2. 화면 스코프 — 현재 화면의 $p.get(id)가 기대한 컴포넌트를 반환하는지 확인합니다.
3. 컴포넌트 선언 — data-m-type, 구조 태그와 연결 ID를 확인합니다.
4. 입력 데이터 — API 응답의 필드명·자료형·배열 위치가 컴포넌트 계약과 맞는지 확인합니다.
5. 상태 전환 — 읽기·신규·수정 상태와 선택행, Grid의 C/U/D 상태를 확인합니다.
6. 폭과 테마 — 넓은 화면에서 정상인 뒤 좁은 화면과 각 테마에서 같은 기능을 확인합니다.

D18-2. 증상별 확인표

D18-3. 구현 단계별 완료 체크리스트

최종 확인

1. 화면 골격을 Layout으로 구성했는가?
2. 기존 34종 컴포넌트에서 필요한 기능을 먼저 찾았는가?
3. 함수와 상태를 $p에 두고 공개 API로 접근했는가?
4. data-m-* 속성을 자동완성 또는 API 문서에서 확인했는가?
5. 직접 DOM에 외부 값을 넣는 위치를 안전하게 처리했는가?
6. 넓은 화면과 좁은 화면에서 목록·상세 전환을 확인했는가?
7. 다크·라이트·고대비에서 텍스트·아이콘·상태가 구분되는가?
8. 키보드만으로 주요 입력과 버튼에 접근할 수 있는가?
9. 조회 결과가 0건이거나 요청이 실패해도 화면 상태가 일관되는가?
10. 팝업 취소, 편집 취소, 탭 전환 뒤 복귀 흐름을 확인했는가?
11. 콘솔 오류 없이 화면 로드와 주요 사용자 흐름이 끝나는가?