# **Chapter 14: Menu System & Permission-Aware Navigation in SartajPHP** ## Menu System & Permission-Aware Navigation in SartajPHP This chapter explains **how SartajPHP manages menus with permissions**, and how **menu rendering is separated from menu definition**. The framework provides **menu data**, while **design and HTML generation are fully customizable**. --- ## 14.1 Menu System Philosophy SartajPHP follows a clear principle: > **Framework provides menu data, not design.** This means: * Framework manages **menu list, hierarchy, permissions** * Renderer (like BootstrapMenu) decides **HTML output** * Developers can replace renderer without changing Gate logic This design keeps **UI flexible** and **logic centralized**. --- ## 14.2 Menu Data vs Menu Renderer There are two distinct layers: ### 1. Menu Data Layer (Framework) Handled by `Sphp\core\SphpAPI` Responsibilities: * Store menus * Store menu links * Apply permission rules * Provide structured menu lists ### 2. Menu Renderer Layer Handled by classes like `BootstrapMenu` Responsibilities: * Convert menu lists to HTML * Apply CSS framework (Bootstrap) * Handle dropdowns, icons, keyboard shortcuts * Inject JS & CSS when required --- ## 14.3 Menu API Overview The framework exposes **menu APIs** through `SphpAPI`. ### addMenu() Creates a menu container (can have sub-menus and links). Key parameters: * `$text` → Menu label * `$link` → Optional URL * `$parent` → Parent menu (default `root`) * `$roles` → Role or permission filter Menus can exist **without links**, acting as dropdown containers. --- ### addMenuLink() Adds an actual clickable item under a menu. Key parameters: * `$text` → Link label * `$link` → URL or JavaScript action * `$parent` → Menu name * `$roles` → Role or permission string Permissions can be: * Login types (`ADMIN`, `MEMBER`) * Permission keys (`mebProfile-view`) * Or empty (public) --- ## 14.4 Permission Filtering in Menu System Permission filtering is **not handled in the menu file**. It is handled **inside the renderer** using framework permission services. Example logic used internally: * If role/permission is empty → show menu * Else → check via `sphp_permissions()->isPermission()` This ensures: * Unauthorized users never see restricted menus * No manual checks required in HTML * Menu adapts dynamically per user --- ## 14.5 BootstrapMenu: A Reference Renderer `BootstrapMenu` is a **menu renderer**, not a framework requirement. Its responsibilities include: * Building Bootstrap 4 / 5 compatible navigation * Supporting nested menus * Supporting AJAX links * Supporting keyboard shortcuts * Highlighting active menu automatically Important: > **All permission logic is respected automatically**, because renderer reads filtered menu lists. --- ## 14.6 Keyboard Shortcut Support Menu links can define keyboard shortcuts using `$akey`. Examples: * `f7` * `v,alt+shift` BootstrapMenu: * Converts shortcut into JavaScript listeners * Adds visual hint to menu text * Triggers menu click programmatically This feature is **optional** and renderer-dependent. --- ## 14.7 menu.php: Project-Level Menu Definition The `menu.php` file is **project-specific**, not framework-specific. Responsibilities: * Define menus based on project needs * Apply role-based navigation * Include plugin menus conditionally Example behavior: * Guest users see Login * Logged-in users see User, Tools, Dashboard * Admin-only menus are protected via roles or permissions This file **does not render HTML** — it only **declares menus**. --- ## 14.8 Dynamic Menu Extension via Plugins Menu system supports modular extension: ```php include_once(PROJ_PATH . "/plugin/cmenu.php"); include_once(PROJ_PATH . "/plugin/cmebmenu.php"); include_once(PROJ_PATH . "/plugin/cadmmenu.php"); ``` Benefits: * Plugins can register menus independently * Core menu remains clean * Easy enable/disable features This makes SartajPHP **plugin-friendly by design**. --- ## 14.9 Master File Role in Rendering The **master file controls layout**, not logic. Key facts: * Master file is always PHP * It decides: * Where menu appears * Where Gate output appears * Which CSS/JS is global The master file does **not**: * Decide permissions * Generate menus * Control Gate logic --- ## 14.10 FrontPlace: Component Injection System FrontPlace is a **layout-level component system**. In the master file: * Components are registered using `addFrontPlace` * Executed using `runFrontPlace` * Rendered using `renderFrontPlace` This allows: * Menu as reusable component * Sidebar, header, footer injection * Clean layout composition --- ## 14.11 Rendering Pipeline in Master File The correct execution order is: 1. Register FrontPlaces 2. Run FrontPlaces (logic execution) 3. Output HTML layout 4. Render FrontPlaces at desired positions 5. Render Gate output 6. Inject framework JS & CSS 7. Send final HTML to browser `SphpBase::getAppOutput()` always renders **Gate output only**, never menu or layout. --- ## 14.12 Framework Asset Injection Framework manages assets centrally: * `getHeaderHTML()` → JS & CSS headers * `getFooterHTML()` → Footer scripts * Bootstrap & jQuery can be loaded once at master level This avoids: * Duplicate asset loading * App-level dependency conflicts --- ## 14.13 Why This Design Matters This architecture provides: * Permission-aware navigation * Fully customizable UI * Zero logic inside layout * Plugin-ready menu system * Clean separation of concerns SartajPHP does **not lock developers** into a UI system — it only provides **data and control**. --- ## 14.14 Summary In this chapter, you learned: * How SartajPHP menu system really works * Difference between menu data and menu renderer * How permissions control navigation visibility * Role of `menu.php` * Role of `master.php` * How FrontPlace composes final output This system is **framework-light, developer-powerful**, and suitable for **small to enterprise-scale projects**. ---