# Programmer Guide ## Scope This guide describes implementation workflow for developers extending or maintaining the template. ## How To Use This File 1. Use this file when adding pages, changing routing, or updating frontend behavior. 2. Follow process gates in [../CONTRIBUTING.md](../CONTRIBUTING.md), [../SECURITY.md](../SECURITY.md), and [docs/TESTING_RULES.md](TESTING_RULES.md). 3. Keep this file updated when development workflow changes. ## Setup 1. Place project in any PHP-enabled web root. 2. Open in browser via endpoint that executes PHP. 3. Ensure internet access for CDN dependencies (Bootstrap, Font Awesome, Chart.js, Google Fonts). ## Core Files 1. `templ.php`: routing, shell render, error handling. 2. `sidebar.php`: nav tree and link rendering helper. 3. `header.php`: topbar controls and breadcrumb. 4. `footer.php`: footer metadata and utility links. 5. `assets/app.js`: navigation runtime and UI interactions. 6. `assets/app.css`: design tokens and component styles. ## Add A New Page 1. Create fragment file in project root, for example `reports.php`. 2. Register route in `resolveContentFile()` allow-list in `templ.php`. 3. Add navigation link with `data-page="reports"` and `data-label="Reports"`. 4. Ensure fragment excludes ``, ``, and `` wrappers. 5. Verify both paths: - `templ.php?page=reports` - `templ.php?page=reports&ajax=1` ## Frontend Integration Pattern 1. Use `App.navigate(page, label)` for programmatic navigation. 2. Use `App.spinner.show(msg)` and `App.spinner.hide()` for long actions. 3. Use `App.toast.show(message, type)` for user notifications. 4. Use `data-spinner-action` and `data-spinner-msg` for spinner trigger wiring. ## Settings And Persistence Model 1. System settings are server-owned and should be sourced from runtime/config values. 2. Application settings are server-owned defaults that shape global app behavior. 3. User preferences are browser-owned by default and may use localStorage for persistence. 4. Theme selection should support `light`, `dark`, and `auto`. 5. Debug and footer timing are separate controls, with footer timing defaulting on when debug is on. 6. New user-facing toggles should be documented before implementation. ## Error Handling Model 1. AJAX failures return error fragments. 2. Full-page failures return minimal error page. 3. Frontend fetch failures render retry UI and show toast. ## Must (Implementation Gate) - [ ] Fragment output is escaped and route-safe. - [ ] Behavior works in SSR and AJAX modes. - [ ] Browser history behavior remains correct. - [ ] Related docs are updated. ## Should (Expected Practices) - [ ] Keep page fragments idempotent and self-contained. - [ ] Minimize inline styles and inline scripts. - [ ] Keep reusable logic in `assets/app.js`. - [ ] Keep reusable styling in `assets/app.css`. ## Could (Optional Improvements) - [ ] Move route map to dedicated config file. - [ ] Add per-page JS module initialization hooks. - [ ] Add basic smoke tests for route loading.