# Admin Template Modularization Plan

## 1) Goals

- Keep upstream JavaScript and TypeScript behavior intact to reduce upgrade friction.
- Modularize template markup by splitting each begin:: / end:: block in adminTmpl.php into a separate component file.
- Preserve backward compatibility so existing CSS selectors, data attributes, and plugin hooks continue to work.
- Create a repeatable upgrade workflow with fast diff review and rollback.

## 2) Scope and Constraints

- Primary target file: dist/adminTmpl.php.
- JS/TS source and build pipeline remain unchanged unless explicitly approved.
- Existing runtime contracts must remain stable:
  - class names used by JS plugins
  - data-lte-toggle and related data attributes
  - expected DOM ordering for sections that rely on siblings/parents

## 3) Proposed Architecture

### 3.1 High-level layout

- Keep a thin page shell template that only composes sections.
- Extract each begin:: / end:: block into an include/partial file.
- Keep component file names aligned with block names for traceability.

Example structure (PHP):

- dist/templates/adminTmpl.php (assembler only)
- dist/templates/sections/head.php
- dist/templates/sections/topbar.php
- dist/templates/sections/sidebar.php
- dist/templates/sections/content-header.php
- dist/templates/sections/content-body.php
- dist/templates/sections/footer.php
- dist/templates/sections/scripts.php

### 3.2 Component contract

Each section file should declare:

- Inputs: variables expected from parent template.
- Required DOM hooks: ids/classes/data attributes that must not change.
- Output boundary: which wrapper element the component owns.

This creates stable contracts and reduces accidental regressions.

### 3.3 Include strategy

- Use include/require from the assembler template in the original rendering order.
- Keep section includes deterministic and explicit.
- Prefer one section per file, not mixed concerns.

## 4) Backward Compatibility Rules

- Preserve all plugin-targeted selectors and attributes.
- Preserve element hierarchy where plugin logic depends on closest/querySelector behavior.
- Preserve script loading order and location for third-party dependencies.
- Preserve accessibility attributes and landmarks already present.

Compatibility checks before merge:

- Sidebar toggle behavior unchanged.
- Treeview open/close behavior unchanged.
- Card widget collapse/maximize/remove unchanged.
- Fullscreen toggle icons unchanged.
- Accessibility skip links, focus behavior, and announcements still work.

## 5) Predicted Risk Areas and How We Watch Them

### Risk A: Selector breakage after extraction

Why it can happen:

- A wrapper element is removed/renamed while moving markup into section files.

How to watch:

- Add a DOM contract checklist per section.
- Compare old/new rendered HTML for critical selectors.
- Smoke test all plugin toggles in browser.

### Risk B: Initialization timing/order regressions

Why it can happen:

- Script include order changes when scripts are moved into componentized files.

How to watch:

- Keep scripts section centralized initially.
- Verify no new console errors on load.
- Verify plugin actions after full page load and after resize.

### Risk C: Cross-section dependency regressions

Why it can happen:

- Section A assumes an element from Section B is present in a specific location.

How to watch:

- Document known cross-section dependencies.
- Maintain stable top-level composition order.
- Add page-level integration checks (not only section-level checks).

### Risk D: Accessibility regressions

Why it can happen:

- Landmark roles/ids/tabindex attributes are dropped during extraction.

How to watch:

- Run keyboard-only smoke tests (Tab, Shift+Tab, Escape).
- Verify skip links target existing elements.
- Check ARIA attributes and invalid form announcements.

## 6) Backup and Upgrade Traceability Policy

You requested fileNameOrig.ext backups. That can work, with guardrails.

### Option 1: Orig file copies (your requested pattern)

Policy:

- Before editing a file, copy current file to fileNameOrig.ext once.
- Never overwrite an existing Orig file; keep first baseline snapshot.
- Add a simple manifest listing each modified file and its Orig counterpart.

Pros:

- Very visible and simple for manual upgrades.

Cons:

- Can create duplication and drift if many files change over time.

Recommendation if using this option:

- Restrict Orig copies to files directly touched by modularization.
- Keep a MODULARIZATION-MANIFEST.md with reason/date per changed file.

### Option 2: Git-first baseline tags (recommended long-term)

Policy:

- Create a baseline branch/tag before modularization.
- Use git diffs/cherry-picks for upgrade comparison.

Pros:

- Cleaner history and easier long-term maintenance.

Cons:

- Less obvious than side-by-side files for quick visual inspection.

Practical recommendation:

- Use both: Git as source of truth, plus Orig copies only for high-risk templates.

## 7) Implementation Phases

### Phase 0: Preparation

- Identify all begin:: / end:: blocks in dist/adminTmpl.php.
- Build section inventory and dependency map.
- Define section naming convention.

### Phase 1: Non-functional extraction

- Extract one section at a time into section files.
- Replace block content in assembler with includes.
- No intentional markup changes; only movement.

### Phase 2: Validation and hardening

- Run smoke tests after each section extraction.
- Compare rendered output for high-risk sections.
- Fix any selector or ordering mismatch immediately.

### Phase 3: Optional enhancement

- Add optional component registry/fallback mechanism for replacements.
- Add lightweight tests/checklists to speed future upgrades.

## 8) Suggested Acceptance Checklist

- Page renders with no PHP include warnings/errors.
- No new browser console errors.
- Existing navigation/sidebar/treeview interactions work.
- Card widget actions work.
- Fullscreen toggle works.
- Accessibility keyboard flow works.
- Visual layout remains equivalent to baseline.

## 9) Section Inventory

Source note:

- adminTmpl.php is treated as the working template copy of the dashboard page.
- In this workspace, the equivalent full-page source content is the built file at dist/indexOrig.html.
- The root indexOrig.html in the repo is only a redirect wrapper and is not the page source for extraction.

Planned section split based on begin:: / end:: boundaries:

### Head

- Head wrapper
- Accessibility Meta Tags
- Primary Meta Tags
- Accessibility Features
- Fonts
- Third Party Plugin(OverlayScrollbars)
- Third Party Plugin(Bootstrap Icons)
- Required Plugin(AdminLTE)

### Body Shell

- Body wrapper
- App Wrapper

### Header

- Header
- Container
- Start Navbar Links
- End Navbar Links
- Navbar Search
- Messages Dropdown Menu
  - Message item 1
  - Message item 2
  - Message item 3
- Notifications Dropdown Menu
- Fullscreen Toggle
- Color Mode Toggle (#6010)
- User Menu Dropdown
  - User Image
  - Menu Body
    - Row
  - Menu Footer

### Sidebar

- Sidebar
- Sidebar Brand
  - Brand Link
    - Brand Image
    - Brand Text
- Sidebar Wrapper
- Sidebar Menu

### Main Content

- App Main
- App Content Header
  - Container
  - Row
- App Content
  - Container
  - Row 1
    - Small Box Widget 1
    - Small Box Widget 2
    - Small Box Widget 3
    - Small Box Widget 4
  - Row 2
  - Remaining content rows and cards

### Footer

- Footer
- To the end
- Copyright

### Script Block

- Script
- Third Party Plugin(OverlayScrollbars)
- Required Plugin(popperjs for Bootstrap 5)
- Required Plugin(Bootstrap 5)
- Required Plugin(AdminLTE)
- OverlayScrollbars Configure
- Color Mode Toggle (#6010)

Extraction priority recommendation:

1. Head
2. Script Block
3. Header
4. Sidebar
5. Footer
6. Main content rows and widgets

Reason:

- Head and scripts are easiest to isolate and lowest risk to DOM structure.
- Header/sidebar/footer are stable shell parts with clear boundaries.
- Main content has the most page-specific markup and should be broken into smaller pieces after the shell is proven.

## 10) What We Should Clarify Before Editing

- Confirm target path for modularized templates (inside dist or separate custom folder).
- Confirm whether we keep dist/adminTmpl.php as the assembler entrypoint.
- Confirm whether to create Orig backups for every changed file or only selected high-risk files.
- Confirm if we should add a manifest file and naming convention now.

## 11) Recommended Default Decisions

- Keep dist/adminTmpl.php as a thin assembler.
- Create dist/templates/sections for extracted blocks.
- Preserve script block centralization at first pass.
- Use Git baseline plus selective Orig backups for changed templates.
- Use per-section extraction with immediate smoke test after each move.