README

A sophisticated sidebar navigation module for Howard University's Drupal sites that provides intelligent, context-aware menu navigation based on the current page's position in the site hierarchy.

✨ Features

🎯 Context-Aware Navigation: Automatically determines current page position and displays relevant submenu items
⚡ Performance Optimized: Efficient menu tree manipulation with intelligent caching
🎨 Flexible Theming: Custom Twig templates with complete design control
♿ Accessibility Compliant: WCAG guidelines support with proper ARIA labels
📱 Responsive Design: Mobile-friendly navigation with responsive breakpoints
🔒 Security Focused: Proper access control and XSS prevention

🚀 Quick Start

Installation

Composer (Recommended):

composer require howard/howard_sidebar_menu_block
drush en howard_sidebar_menu_block

Manual Installation:

Download from GitHub releases
Extract to modules/contrib/howard_sidebar_menu_block
Enable: drush en howard_sidebar_menu_block

Basic Setup

Enable the module: Admin → Extend → Howard Sidebar Menu Block
Place the block: Admin → Structure → Block layout → Place "Howard Sidebar Menu Block"
Configure: Choose your sidebar region and configure visibility settings

📋 Requirements

Drupal: 10.0+ or 11.0+
PHP: 8.1+
Dependencies: Block (Core), Menu (Core)

🔧 How It Works

The module intelligently analyzes your current page's position in the main menu hierarchy:

Detects Current Position: Determines where you are in the menu structure
Finds Parent Context: Identifies the parent menu item for contextual navigation
Builds Relevant Tree: Constructs a menu tree showing siblings and children
Renders Contextually: Displays only relevant navigation options

Example Behavior

Main Menu:                    On "About → History" page, sidebar shows:
├── Home                      ├── History ← (current page)
├── About                     ├── Leadership
│   ├── History              ├── Mission
│   ├── Leadership           └── Contact
│   └── Mission
├── Programs
└── Contact

📚 Documentation

Comprehensive documentation is available in the docs/ folder:

📖 Documentation Index - Overview of all documentation
🛠️ Installation Guide - Detailed setup instructions
⚙️ API Documentation - Technical specifications for developers
👩‍💻 Developer Guide - Customization and development
📝 Changelog - Version history and release notes
📏 Coding Standards - Code quality guidelines
📋 Release Checklist - Release management

🎨 Customization

Template Override

Copy templates to your theme for customization:

cp modules/contrib/howard_sidebar_menu_block/templates/* themes/your_theme/templates/

CSS Styling

Basic styling example:

.sidebar-menu {
  background: #f8f9fa;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
  padding: 1rem;
}

.sidebar-menu .nav-link {
  display: block;
  padding: 0.5rem 0.75rem;
  color: #495057;
  text-decoration: none;
}

.sidebar-menu .nav-link:hover {
  background-color: #e9ecef;
}

🧪 Testing

Run Tests

# Unit tests
vendor/bin/phpunit modules/contrib/howard_sidebar_menu_block/tests/src/Unit/

# Functional tests
vendor/bin/phpunit modules/contrib/howard_sidebar_menu_block/tests/src/Functional/

Manual Testing

Create a multi-level menu structure
Place the sidebar block in a region
Navigate to different pages and verify contextual display
Test with different user permissions
Verify cache invalidation works correctly

🔍 Troubleshooting

Common Issues

Block not appearing:

Check block placement and region configuration
Verify theme has the target region
Clear all caches: drush cr

Wrong menu items showing:

Verify main menu structure
Check menu item access permissions
Review active trail detection

Performance issues:

Enable page caching
Check for large menu structures (>100 items)
Monitor memory usage

For detailed troubleshooting, see the Installation Guide.

🤝 Contributing

We welcome contributions! Please see our Developer Guide and Coding Standards.

Development Setup

git clone https://github.com/howard-university-web-services/howard_sidebar_menu_block.git
composer install
drush en howard_sidebar_menu_block

Code Quality

# Check coding standards
vendor/bin/phpcs --standard=Drupal,DrupalPractice src/

# Run tests
vendor/bin/phpunit tests/

📊 Version Information

Current Version: 11.0.3
Drupal Compatibility: 10.0+ | 11.0+
Release Date: July 7, 2025
Next Release: View Milestone

📞 Support

🐛 Report Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📚 Documentation: Project Docs
👨‍💻 Maintainer: Dan Rogers (Drupal.org)

📄 License

This project is licensed under the GPL-2.0+ License - see the LICENSE file for details.

🏛️ About Howard University

This module is developed and maintained by Howard University Web Services for use across Howard University's digital properties. Howard University is a leading research university providing an educational experience of exceptional value to students of high academic standing.

🌟 Star this repository if you find it useful!

howard / howard_sidebar_menu_block

Maintainers

Details