Micro Sidebar - A Reusable RTL Django Sidebar App

RTL lightweight, reusable django app that provides a dynamic sidebar for your django projects.

Requirements

• Django: >= 5.1
• Bootstrap: 5 (Required for consistent styling)

Installation

1. Install:

   pip install micro-sidebar
   # OR
   pip install git+https://github.com/debeski/micro-sidebar.git
   

2. Add to INSTALLED_APPS: In your settings.py:

   INSTALLED_APPS = [
       ...
       'sidebar',
       ...
   ]
   

3. Configure URLs: In your project's urls.py:

   from django.urls import path, include
   
   urlpatterns = [
       ...
       path('sidebar/', include('sidebar.urls')),
       ...
   ]
   

Auto-Discovery Mode (New in v2.0.0)

The sidebar can automatically discover your list views and generate navigation items!

Setup

1. Add context processor to settings.py:

   TEMPLATES = [{
       'OPTIONS': {
           'context_processors': [
               ...
               'sidebar.context_processors.sidebar_context',
           ],
       },
   }]
   

2. Use in your sidebar template:

   {% extends "sidebar/main.html" %}
   {% load sidebar_tags %}
   
   {% block items %}
       {% auto_sidebar %}
   {% endblock %}
   

That's it! The sidebar will automatically find all URLs with list in their name (e.g., decree_list), match them to models, and display verbose_name_plural as labels.

Configuration (Optional)

Add to settings.py:

SIDEBAR_AUTO = {
    'ENABLED': True,                    # Enable auto-discovery
    'URL_PATTERNS': ['list'],           # Keywords to match in URL names
    'EXCLUDE_APPS': ['admin', 'auth'],  # Apps to exclude
    'EXCLUDE_MODELS': [],               # Specific models to exclude
    'CACHE_TIMEOUT': 3600,              # Cache timeout in seconds
    'DEFAULT_ICON': 'bi-list',          # Default Bootstrap icon
    'DEFAULT_ITEMS': {},                # See "Default Items" section below
    'EXTRA_ITEMS': {},                  # See "Extra Items" section below
}

Default Items Configuration

Use DEFAULT_ITEMS to customize auto-discovered items (labels, icons, ordering) without modifying your models:

SIDEBAR_AUTO = {
    # ...
    'DEFAULT_ITEMS': {
        'decree_list': {          # Key is the URL name
            'label': 'Decisions', # Override display label
            'icon': 'bi-gavel',   # Override icon
            'order': 10,          # Sort order (lower = first)
        },
        'incoming_list': {
            'order': 20,          # Only setting order
        }
    }
}

Items not in DEFAULT_ITEMS will use defaults:

• Label: Model's verbose_name_plural
• Icon: DEFAULT_ICON
• Order: 100

Extra Items (Non-Model URLs)

For URLs that don't map to a model (e.g., management pages), use EXTRA_ITEMS:

SIDEBAR_AUTO = {
    # ... other config ...
    'EXTRA_ITEMS': {
        'الإدارة': {  # Group name (accordion header)
            'icon': 'bi-gear',
            'items': [
                {
                    'url_name': 'manage_sections',
                    'label': 'إدارة الأقسام',
                    'icon': 'bi-diagram-3',
                    'permission': 'documents.manage_sections',
                },
                {
                    'url_name': 'manage_users',
                    'label': 'إدارة المستخدمين',
                    'icon': 'bi-people',
                    'permission': 'is_staff',      # or a special check to Only show to staff users.
                },
            ]
        }
    }
}

Then in your sidebar template:

{% extends "sidebar/main.html" %}
{% load sidebar_tags %}

{% block items %}
    {% auto_sidebar %}
    {% extra_sidebar %}
{% endblock %}

Extra items appear at the bottom of the sidebar, grouped in Bootstrap accordions.

Customization

Override Default Menu

The sidebar uses a block-based template system. To define your own menu items:

1. Create a new template (e.g., templates/sidebar_menu.html).
2. Extend sidebar/main.html.
3. Override the {% block items %}.

Example sidebar_menu.html:

{% extends "sidebar/main.html" %}

{% block items %}
<a href="{% url 'home' %}" class="list-group-item list-group-item-action">
    <i class="bi bi-house me-2" style="font-size: 24px;"></i>
    <span>Home</span>
</a>
<a href="{% url 'settings' %}" class="list-group-item list-group-item-action">
    <i class="bi bi-gear me-2" style="font-size: 24px;"></i>
    <span>Settings</span>
</a>
{% endblock %}

Then, include your custom template in base.html:

{% include "sidebar_menu.html" %}

Positioning

The sidebar is sticky by default. If your app has a top navigation bar (titlebar), the sidebar will automatically adjust its position below it on small screens. If no titlebar is detected, it will stick to the top of the viewport.

RTL / LTR Support

This sidebar is primarily designed for RTL (Right-to-Left) interfaces (e.g., Arabic). While it may theoretically work in LTR environments if standard Bootstrap files are used instead of RTL versions, this has not been fully tested.

Future updates are planned to support dynamic language switching between RTL and LTR.

Version History