# Development Guide Detailed documentation for developing with the Metis Bootstrap 5 Admin Template. ## Table of Contents - [Getting Started](#getting-started) - [Project Structure](#project-structure) - [Architecture](#architecture) - [Adding New Features](#adding-new-features) - [Component Patterns](#component-patterns) - [Sidebar & Responsive Layout](#sidebar--responsive-layout) - [Styling Guide](#styling-guide) - [Build Configuration](#build-configuration) ## Getting Started ### Prerequisites - Node.js 18+ - npm or yarn ### Installation ```bash npm install npm run dev # Start dev server at http://localhost:3000 npm run build # Production build to dist-modern/ npm run preview # Preview production build npm run lint # Run ESLint npm run format # Format with Prettier ``` ## Project Structure ```text src-modern/ ├── *.html # Page templates (each requires data-page attribute) ├── scripts/ │ ├── main.js # Application entry point │ ├── components/ # Page-specific components │ │ ├── analytics.js │ │ ├── calendar.js │ │ ├── dashboard.js │ │ ├── files.js │ │ ├── forms.js │ │ ├── help.js │ │ ├── messages.js │ │ ├── orders.js │ │ ├── products.js │ │ ├── reports.js │ │ ├── security.js │ │ ├── settings.js │ │ ├── sidebar.js # SidebarManager (desktop collapse + mobile overlay) │ │ └── users.js │ └── utils/ │ ├── theme-manager.js # Dark/light mode handling │ ├── notifications.js # SweetAlert2 wrapper │ └── icon-manager.js # Icon library abstraction ├── styles/ │ └── scss/ │ ├── abstracts/ # Variables, mixins, functions │ ├── components/ # UI component styles │ ├── layout/ # Header, sidebar, footer │ ├── pages/ # Page-specific styles │ ├── themes/ # Theme variants │ └── main.scss # Main entry point └── assets/ # Static assets (images, icons) ``` ## Architecture ### Application Bootstrap The `AdminApp` class in `main.js` orchestrates initialization: 1. **Core Managers** - ThemeManager, NotificationManager, IconManager 2. **Bootstrap Components** - Dropdowns, modals, tooltips, popovers 3. **Page Detection** - Routes to correct component via `data-page` attribute 4. **Alpine.js** - Registers global data components and starts Alpine ### Page Detection Pattern Each HTML page must have `data-page="pagename"` on the `` tag: ```html ``` This triggers the corresponding component loader in `main.js`: ```javascript // main.js initPageComponents() switch (currentPage) { case 'users': await import('./components/users.js'); break; // ... } ``` ### SidebarManager The `SidebarManager` class in `scripts/components/sidebar.js` is the single source of truth for all sidebar toggle behavior. It is initialized by `main.js` on every page and handles two distinct modes: - **Desktop (>=992px):** Toggles between full-width (280px) and collapsed (70px) sidebar via the `sidebar-collapsed` class on `#admin-wrapper`. State is persisted in `localStorage`. - **Mobile (<992px):** Opens the sidebar as a slide-in overlay with a backdrop. Supports closing via backdrop click, Escape key, and scroll-lock on the body. **Key elements:** | Selector | Role | |----------|------| | `#admin-wrapper` | Receives `sidebar-collapsed` class on desktop | | `#admin-sidebar` | The sidebar element; receives `show` class on mobile | | `[data-sidebar-toggle]` | The hamburger button that triggers `toggle()` | | `.sidebar-backdrop` | Semi-transparent overlay behind mobile sidebar | **Important:** Do not add inline `