How to Add a Sidebar Menu in Horilla (v2)

In this guide, we’ll guide you through how to add a custom sidebar menu item in the Horilla v2 codebase. This is useful when you’re building out new features or modules and want to integrate them into the left navigation menu of the Horilla HRMS dashboard.

Before you begin, make sure:

You’re working with the dev/v2.0 branch of Horilla.

Your environment is properly set up, and the development server is running.

Let’s get started.

Step 1: Ensure You Are on the Correct Git Branch

Before adding any new feature, always make sure you’re on the correct branch:

If you are doing it for the first time, initialize git

git init

Check out the branch if it exists

git checkout v2

Or run the command below to create a new branch

git checkout -b v2

Then pull the latest code from the dev/v2.0 branch

git pull https://github.com/horilla-opensource/horilla.git dev/v2.0

This ensures you’re working with the latest stable version of the Horilla v2 codebase.

Step 2: Start the Development Server

Run the development server using:

python3 manage.py runserver

Once the server is running, open the application in the browser to view the current sidebar structure and verify it’s functioning.

Step 3: Understand the Sidebar Structure

In Horilla, the sidebar is configured using Python files under each module. For example, the Leave module has a sidebar configuration located in:

leave/sidebar.py

This file contains:

• Main menu name
• Sidebar icon source
• Submenu list (title, redirect route, accessibility/permissions)
• Accessibility function for permission control

Example:

from django.urls import reverse

MENU = trans("Leave")
IMG_SRC = "images/ui/leave.svg"

SUBMENUS = [
    {
        "menu":"Dashboard",
        "redirect": reverse("leave-dashboard"),
        "accessibility": "leave.sidebar.dashboard_accessibility",
    },
    ...
]

The accessibility function helps control user-level visibility and permissions for each menu item.

Step 4: Create a New App and Sidebar Entry

Let’s create a new app and add it to the sidebar.

a. Create a New Django App

Use the following command:

python3 manage.py startapp custom_app

Once created, you’ll see files like views.py, models.py, and admin.py inside custom_app/.

b. Add the App to Settings

Open horilla/settings.py and add your new app to INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'custom_app',
]

Step 5: Set Up URLs

Create a new file urls.py inside custom_app/ and define a simple route:

# custom_app/urls.py

from django.urls import path
from custom_app import views

urlpatterns = [
    path('hello/', views.hello_view, name='custom_hello'),
]

Now edit the global urls.py (usually horilla/urls.py) to include the custom app’s routes:

# horilla/urls.py

from django.urls import path, include

urlpatterns = [
    ...
    path('custom/', include('custom_app.urls')),
]

Step 6: Create a View

Inside custom_app/views.py, add:

from django.shortcuts import render

def hello_view(request):
    return render(request, 'custom_app/hello.html')

Also, create the corresponding HTML template in:

custom_app/templates/custom_app/hello.html

Example content:

{% extends 'index.html' %}
{% block content %}
<h1>Hello from Custom App</h1>
{% endblock content %}

Step 7: Add the Sidebar Entry

Now that the app is set up and renders a basic page, let’s integrate it into the Horilla sidebar.

Create a sidebar.py file inside your custom_app/ directory.

Add the following sidebar config:

# custom_app/sidebar.py
from django.urls import reverse_lazy

def has_custom_access(request, submenu, user_perms, *args, **kwargs):
    # Example: check user role or permission
    return request.user.is_authenticated


MENU ="Custom App"
IMG_SRC = "images/ui/info.png" # menu icon

SUBMENUS = [
    {
        "menu":"Hello Page",
        "redirect": reverse_lazy("custom_hello"),
        "accessibility": "custom_app.sidebar.has_custom_access",
    },
    ...
]

This ensures that:

• The sidebar item appears as “Custom App”
• The submenu links to your hello_view
• The menu is visible only to authenticated users (customize as needed)

Step 8: Register Sidebar

Now let’s register the app label inside horilla/horilla_apps.py sidebars list

# horilla/horilla_apps.py

SIDEBARS = [
   ...
    "custom_app",
]

Final Step: Restart Server and Verify

Restart your development server to apply all changes:

python3 manage.py runserver

Visit the Horilla dashboard in your browser. You should now see a new “Custom App” menu icon (images/ui/info.png) in the sidebar. Clicking on “Hello Page” should navigate you to the view you created.

When you click on the Hello Page submenu (Marked as 2), you will be redirected to the Hello World template

Conclusion

Adding a custom sidebar menu in Horilla is a straightforward yet powerful way to extend the platform’s functionality and tailor the interface to your organization’s needs. By creating a new Django app, configuring routes and views, and integrating them through Horilla’s modular sidebar system, you enable seamless navigation and a more organized user experience. This approach keeps your codebase clean, scalable, and role-aware, making it easy to introduce new features while maintaining control over who can access what. Whether you’re building internal HR modules, dashboards, or administrative tools, sidebar integration is a key step in aligning Horilla with your business workflows.