관리자 화면 제작

관리자 화면은 코어가 스타일을 전부 제공합니다. 모듈 개발자는 컨벤션에 맞는 마크업만 쓰면 코어 관리자와 같은 모양이 나오고, 코어가 디자인을 바꿔도 모듈 화면이 함께 따라갑니다.

기본 원칙

• 관리자 화면의 색·간격·서체는 코어의 디자인 토큰(--zm-* CSS 변수)이 정합니다. 모듈에서 색상값을 직접 박지 말고 토큰을 참조하세요.
• 예전 XE부터 내려오는 x_* 클래스는 그대로 씁니다. 클래스는 유지한 채 코어가 스타일만 새로 입혀 두었기 때문에, 기존 모듈은 고치지 않아도 새 디자인이 적용됩니다.
• 모듈 고유의 UI가 필요하면 모듈 전용 접두어를 만들어 쓰세요. 코어 클래스를 덮어쓰는 방식은 다음 코어 업데이트에서 깨집니다.

디자인 토큰

관리자 화면 전체에서 쓸 수 있는 CSS 변수입니다. 라이트/다크 값이 모두 정의되어 있어 토큰만 쓰면 다크 모드가 저절로 됩니다.

/* 모듈 관리자 화면 예 */
.mymod-note {
	padding: 12px 16px;
	border: 1px solid var(--zm-line);
	border-radius: var(--zm-radius-sm);
	background: var(--zm-surface-2);
	color: var(--zm-ink-soft);
}

x_* 컴포넌트

관리자 마크업의 기본 부품입니다. 아래 클래스를 조합하면 별도 CSS 없이 코어와 같은 화면이 나옵니다.

• 폼: .x_form-horizontal > .x_control-group > .x_control-label + .x_controls
• 버튼: .x_btn, 강조는 .x_btn.x_btn-primary, 위험 동작은 .x_btn-danger, 크기는 -large -small -mini
• 표: .x_table, 행 구분이 필요하면 .x_table-striped, 호버는 .x_table-hover
• 알림: .x_alert와 -info -success -error 변형
• 배지: .x_badge와 상태 변형, 도움말: .x_help-block .x_help-inline
• 탭: .x_nav.x_nav-tabs > li > a, 활성 항목은 li.x_active

<form class="x_form-horizontal" method="post" action="./">
	<div class="x_control-group">
		<label class="x_control-label">{$lang->title}</label>
		<div class="x_controls">
			<input type="text" name="title" value="{$config->title}" />
			<p class="x_help-block">{$lang->about_title}</p>
		</div>
	</div>
	<div class="x_clearfix" style="text-align:right">
		<button type="submit" class="x_btn x_btn-primary">{$lang->cmd_save}</button>
	</div>
</form>

레거시 .btn .table 등 접두어 없는 부트스트랩 클래스도 관리자 화면 안에서는 x_*와 동일하게 처리되지만, 새 코드에서는 x_*를 쓰세요.

모듈 전용 화면과 접두어

목록 카드, 대시보드처럼 x_* 부품으로 표현하기 어려운 화면은 모듈 접두어를 정해 직접 만듭니다. 코어 모듈들이 쓰는 방식과 같습니다.

• 접두어는 모듈마다 하나로 통일합니다. 예: 스토어 관리자는 zmst-, 결제 모듈은 zpay-
• 접두어 안에서도 색·간격은 --zm-* 토큰을 참조합니다. 그래야 다크 모드와 향후 리디자인을 공짜로 따라갑니다.
• 상위 요소 선택자(.x .something)로 코어 규칙을 덮어쓰는 방식은 피하세요. 코어 CSS의 우선순위가 바뀌면 함께 깨집니다.

관리자 템플릿 위치와 등록

현대식 구조의 모듈은 관리자 템플릿을 views/admin/*.blade.php(템플릿 v2)로 둡니다.

modules/mymodule/
├── views/admin/
│   ├── _tabs.blade.php   ← 탭 공통 조각
│   ├── config.blade.php
│   └── list.blade.php
└── controllers/Admin.php

• 화면이 여러 개면 탭 조각(_tabs.blade.php)을 만들어 각 화면에서 @include 합니다.
• 관리자 메뉴 등록은 module.xml 액션 선언의 menu_name 속성으로 합니다. 자세한 것은 모듈 제작 문서를 보세요.
• 관리자 화면에서는 mid가 없으므로 다른 화면으로 가는 링크는 getUrl('', 'module', 'admin', 'act', ...) 형태로 만듭니다. 첫 인자를 비우지 않으면 현재 요청 변수가 모두 따라붙습니다.

하지 말아야 할 것

• 색상 하드코딩. 특히 흰 배경(#fff)을 직접 쓰면 다크 모드에서 깨집니다. var(--zm-card) 같은 토큰을 쓰세요.
• 부트스트랩 등 외부 CSS 프레임워크를 관리자 화면에 로드하는 것. 코어 스타일과 충돌합니다.
• 다른 모듈의 관리자 화면을 CSS로 덮어쓰는 것. 필요한 개선이라면 코어에 제안하세요.
• 인라인 스크립트 남용. 코어는 관리자 화면에 CSP 적용을 넓혀 가고 있으므로, 스크립트는 별도 js 파일로 분리하는 것이 안전합니다.