orion/docs/frontend/shared/sidebar.md

Admin Sidebar Navigation

Overview

The admin sidebar provides navigation across all admin pages. It features collapsible sections with state persistence, active page indicators, and responsive mobile support.

File Location: app/templates/admin/partials/sidebar.html

---

Sidebar Structure

The sidebar is organized into the following sections:

Section	Collapsible	Pages
Dashboard	No	Dashboard
Platform Administration	Yes	Merchants, Stores, Users, Customers
Product Catalog	Yes	Marketplace Products, Store Products, Import
Content Management	Yes	Platform Homepage, Content Pages, Store Themes
Developer Tools	Yes	Components, Icons
Platform Health	Yes	Testing Hub, Code Quality, Background Tasks
Platform Monitoring	Yes	Import Jobs, Application Logs
Settings	Yes	General, Profile, API Keys, Notifications

---

Collapsible Sections

How It Works

Sections can be expanded/collapsed by clicking the section header. The state is persisted to localStorage so sections remain open/closed across page navigation and browser sessions.

State Management

File: static/admin/js/init-alpine.js

// Default state: Platform Administration open, others closed
const defaultSections = {
    platformAdmin: true,
    productCatalog: false,
    contentMgmt: false,
    devTools: false,
    platformHealth: false,
    monitoring: false,
    settingsSection: false
};

// State stored in localStorage under this key
const SIDEBAR_STORAGE_KEY = 'admin_sidebar_sections';

Available Methods

Method	Description
toggleSection(section)	Toggle a section open/closed
expandSectionForCurrentPage()	Auto-expand section containing current page
openSections.platformAdmin	Check if Platform Administration is open
openSections.productCatalog	Check if Product Catalog is open
openSections.contentMgmt	Check if Content Management is open
openSections.devTools	Check if Developer Tools is open
openSections.platformHealth	Check if Platform Health is open
openSections.monitoring	Check if Platform Monitoring is open
openSections.settingsSection	Check if Settings is open

CSS Transitions

Sections animate smoothly using CSS transitions (no plugins required):

<ul
    x-show="openSections.platformAdmin"
    x-transition:enter="transition-all duration-200 ease-out"
    x-transition:enter-start="opacity-0 -translate-y-2"
    x-transition:enter-end="opacity-100 translate-y-0"
    x-transition:leave="transition-all duration-150 ease-in"
    x-transition:leave-start="opacity-100 translate-y-0"
    x-transition:leave-end="opacity-0 -translate-y-2"
    class="mt-1 overflow-hidden"
>

Chevron Icon Rotation

The chevron icon rotates 180 degrees when a section is expanded:

<span
    x-html="$icon('chevron-down', 'w-4 h-4 transition-transform duration-200')"
    :class="{ 'rotate-180': openSections.platformAdmin }"
></span>

---

Page-to-Section Mapping

Pages are mapped to their parent sections for auto-expansion:

const pageSectionMap = {
    // Platform Administration
    merchants: 'platformAdmin',
    stores: 'platformAdmin',
    users: 'platformAdmin',
    customers: 'platformAdmin',
    // Product Catalog
    'marketplace-products': 'productCatalog',
    'store-products': 'productCatalog',
    marketplace: 'productCatalog',
    // Content Management
    'platform-homepage': 'contentMgmt',
    'content-pages': 'contentMgmt',
    'store-theme': 'contentMgmt',
    // Developer Tools
    components: 'devTools',
    icons: 'devTools',
    // Platform Health
    testing: 'platformHealth',
    'code-quality': 'platformHealth',
    'background-tasks': 'platformHealth',
    // Platform Monitoring
    imports: 'monitoring',
    logs: 'monitoring',
    // Settings
    settings: 'settingsSection',
    profile: 'settingsSection',
    'api-keys': 'settingsSection',
    'notifications-settings': 'settingsSection'
};

---

Complete Page Mapping

Page	currentPage Value	Section	URL
Dashboard	'dashboard'	(always visible)	/admin/dashboard
Merchants	'merchants'	Platform Administration	/admin/merchants
Stores	'stores'	Platform Administration	/admin/stores
Users	'users'	Platform Administration	/admin/users
Customers	'customers'	Platform Administration	/admin/customers
Marketplace Products	'marketplace-products'	Product Catalog	/admin/marketplace-products
Store Products	'store-products'	Product Catalog	/admin/store-products
Import	'marketplace'	Product Catalog	/admin/marketplace
Platform Homepage	'platform-homepage'	Content Management	/admin/platform-homepage
Content Pages	'content-pages'	Content Management	/admin/content-pages
Store Themes	'store-theme'	Content Management	/admin/store-themes
Components	'components'	Developer Tools	/admin/components
Icons	'icons'	Developer Tools	/admin/icons
Testing Hub	'testing'	Platform Health	/admin/testing
Code Quality	'code-quality'	Platform Health	/admin/code-quality
Background Tasks	'background-tasks'	Platform Health	/admin/background-tasks
Import Jobs	'imports'	Platform Monitoring	/admin/imports
Application Logs	'logs'	Platform Monitoring	/admin/logs
General Settings	'settings'	Settings	/admin/settings
Profile	'profile'	Settings	/admin/profile
API Keys	'api-keys'	Settings	/admin/api-keys
Notifications	'notifications-settings'	Settings	/admin/notifications-settings

---

Active Page Indicator

Each menu item shows a purple vertical bar when active:

<li class="relative px-6 py-3">
    <!-- Purple bar indicator (shows when page is active) -->
    <span x-show="currentPage === 'stores'"
          class="absolute inset-y-0 left-0 w-1 bg-purple-600 rounded-tr-lg rounded-br-lg"
          aria-hidden="true"></span>

    <!-- Link with active text styling -->
    <a class="inline-flex items-center w-full text-sm font-semibold transition-colors duration-150 hover:text-gray-800 dark:hover:text-gray-200"
       :class="currentPage === 'stores' ? 'text-gray-800 dark:text-gray-100' : ''"
       href="/admin/stores">
        <span x-html="$icon('shopping-bag')"></span>
        <span class="ml-4">Stores</span>
    </a>
</li>

Setting currentPage in Components

Each page component must set currentPage to match the sidebar:

function adminStores() {
    return {
        ...data(),                    // Inherit base (includes openSections)
        currentPage: 'stores',       // Must match sidebar check
        // ... rest of component
    };
}

---

Jinja2 Macros

The sidebar uses Jinja2 macros for DRY code:

section_header

Creates a collapsible section header with chevron:

{% macro section_header(title, section_key) %}
<button
    @click="toggleSection('{{ section_key }}')"
    class="flex items-center justify-between w-full px-6 py-2 ..."
>
    <span>{{ title }}</span>
    <span x-html="$icon('chevron-down', '...')"
          :class="{ 'rotate-180': openSections.{{ section_key }} }"></span>
</button>
{% endmacro %}

section_content

Wraps section items with collapse animation:

{% macro section_content(section_key) %}
<ul x-show="openSections.{{ section_key }}" x-transition:...>
    {{ caller() }}
</ul>
{% endmacro %}

menu_item

Creates a menu item with active indicator:

{% macro menu_item(page_id, url, icon, label) %}
<li class="relative px-6 py-3">
    <span x-show="currentPage === '{{ page_id }}'" class="..."></span>
    <a href="{{ url }}">
        <span x-html="$icon('{{ icon }}')"></span>
        <span class="ml-4">{{ label }}</span>
    </a>
</li>
{% endmacro %}

Usage Example

{{ section_header('Platform Administration', 'platformAdmin') }}
{% call section_content('platformAdmin') %}
    {{ menu_item('merchants', '/admin/merchants', 'office-building', 'Merchants') }}
    {{ menu_item('stores', '/admin/stores', 'shopping-bag', 'Stores') }}
{% endcall %}

---

Adding a New Page

Step 1: Add Route

Add the route in app/routes/admin_pages.py:

@router.get("/new-page", response_class=HTMLResponse, include_in_schema=False)
async def admin_new_page(
    request: Request,
    current_user: User = Depends(get_current_admin_from_cookie_or_header),
):
    return templates.TemplateResponse(
        "admin/new-page.html",
        {"request": request, "user": current_user},
    )

Step 2: Create Template

Create app/templates/admin/new-page.html:

{% extends "admin/base.html" %}
{% block title %}New Page{% endblock %}
{% block alpine_data %}adminNewPage(){% endblock %}
{% block content %}
    <!-- Your content -->
{% endblock %}

Step 3: Create JavaScript Component

Create static/admin/js/new-page.js:

function adminNewPage() {
    return {
        ...data(),
        currentPage: 'new-page',  // Must match sidebar
        // ...
    };
}

Step 4: Add to Sidebar

Edit app/templates/admin/partials/sidebar.html:

{# Add to appropriate section #}
{{ menu_item('new-page', '/admin/new-page', 'icon-name', 'New Page') }}

Step 5: Update Page-Section Map (if in collapsible section)

Edit static/admin/js/init-alpine.js:

const pageSectionMap = {
    // ... existing mappings
    'new-page': 'platformAdmin',  // Add mapping
};

---

Mobile Sidebar

The sidebar has a mobile version that slides in from the left:

• Toggle: Click hamburger menu in header
• Close: Click outside, press Escape, or navigate
• State: Controlled by isSideMenuOpen

// In base data()
isSideMenuOpen: false,
toggleSideMenu() {
    this.isSideMenuOpen = !this.isSideMenuOpen
},
closeSideMenu() {
    this.isSideMenuOpen = false
}

---

Testing Checklist

• Sections expand/collapse on header click
• Chevron rotates when section opens/closes
• Section state persists after page reload
• Section state persists across different pages
• Active page shows purple bar indicator
• Active page text is highlighted
• Mobile sidebar opens/closes correctly
• Collapsible sections work on mobile
• All navigation links work correctly