django-dashub 4.0.0

A modern Django admin dashboard with enhanced customization options, inspired by Jazzmin but featuring a fresh theme and additional functionality.

Dashub

A modern Django admin dashboard with enhanced customization options, inspired by Jazzmin but featuring a fresh theme and additional functionality.

Features

• Customizable site title, logo, and favicon
• Custom theme color support
• Ordered menu and submenu management
• Custom links for side menu apps
• Custom sidebar menu support
• Related modal support for improved usability
• Enhanced UI tweaks with collapsible and tab-based change views

Installation

Since Dashub is available on PyPI, you can install it directly using pip.

pip install django-dashub

Configuration

To use Dashub, add it to your Django project's installed apps:

INSTALLED_APPS = [
    'dashub',
    'django.contrib.admin',
    ...
]

Customization

All the configuration settings for Dashub are defined in the DASHHUB_SETTINGS dictionary in your Django settings file. You can customize the appearance and behavior of the admin dashboard by modifying these settings.

1. Site Identification

site_logo

Defines the path to the site logo image.

• Example:

  "site_logo": "/static/logo.svg"
  

site_icon

Defines the path to the site's favicon.

• Example:

  "site_icon": "/static/favicon.ico"
  

theme_color

Sets the theme color for the site. This will reflect in the browser's address bar or UI elements.

• Example:

  "theme_color": "#31aa98"
  

2. Hide Models

hide_models

This setting allows you to hide specific models in the Django admin panel. Models are specified using the {app_name}.{model_name} format, in lowercase. You can hide multiple models by listing them in an array.

• Format:

  "hide_models": [
      "app_name.model_name",
      "another_app.another_model"
  ]
  

• Example:

  "hide_models": [
      "user.group",
  ]
  

This configuration hides the group model from the user app.

---

3. Custom Links

custom_links

Custom links are used to add new sections or menus to the sidebar of the admin interface. You can create custom sections by providing an array of menus under specific app names.

Each menu item can have the following options:

• name (optional): The name of the menu item.
• url (optional): The URL to be linked to.
• icon (optional): The icon to display for the menu item (using Font Awesome classes).
• order (optional): Defines the order of the menu item (higher numbers appear higher).
• submenu (optional): A list of submenus within the menu. Each submenu can contain either a model key or an entire submenu structure.
• model (optional): If a model is passed, it will link directly to that model, removing the need to provide a name or url. Models are specified in lowercase as {app_name}.{model_name}.

Either model or name and URL are required for each menu item.

If the app specified in custom_links does not exist, it will create a new section for that app in the sidebar.

Example:

"custom_links": {
    "advance": [
        {"name": "File Manager", "url": "/admin/filemanager/", "icon": "fa-solid fa-folder", "order": 1},
        {"model": "user.group", "icon": "fa-solid fa-user", "order": 2}
    ]
}

In this example:

• The "advance" section contains two menu items: "File Manager" and "User". If the "advance" section does not exist, it will be created. If exists then it will add the menu items to the existing section.

4. Submenus with Models

If you want a submenu to link to specific models, you can specify the model directly. This removes the need for a url or name in the submenu item.

Example:

"core": [
    {
        "name": "User Management",
        "icon": "fa-solid fa-users",
        "submenu": [
            {"model": "auth.user", "order": 1},
            {"model": "auth.group", "order": 2}
        ]
    }
]

In this example, the submenu under "User Management" links directly to auth.user and auth.group models.

---

5. Model Submenus

model_submenus

The model_submenus setting allows you to link specific models to submenus under other models or app sections. The configuration for model submenus is similar to that of custom_links, allowing you to specify both model and submenu for any app.

Each submenu can also contain a model key and/or a submenu structure.

• Format:

  "model_submenus": {
      "app_name.model_name": [
          {"model": "app_name.model_name", "order": 1},
          {"model": "another_app.another_model", "order": 2}
      ]
  }
  

• Example:

  "model_submenus": {
      "core.post": [
          {"model": "core.postcategory", "order": 1}
      ]
  }
  

In this configuration:

• The core.post model has a submenu linking to the core.postcategory model.

Submenus can also have their own submenu structure, just like the custom_links setting.

---

6. Default Orders

default_orders

The default_orders setting defines the order in which menus and models are displayed in the admin interface. This helps control the sequence of items shown in the sidebar and the admin list views. A higher value indicates higher priority (i.e., the item appears at the top).

• Format:

  "default_orders": {
      "app_name": order_value,
      "app_name.model_name": order_value
  }
  

• Example:

  "default_orders": {
      "core": 10,
      "core.page": 2,
      "core.post": 1,
      "user": 20
  }
  

In this example:

• The user app has the highest priority (order 20) so appear it first.
• The core.page model has the highest order (1), meaning it will be shown first.

---

7. Icons

icons

The icons setting allows you to define icons for models and their submenus using Font Awesome class names. Icons are applied to models directly and help improve the visual presentation of the dashboard.

• Format:

  "icons": {
      "app_name.model_name": "fa-icon-class"
  }
  

• Example:

  "icons": {
      "core.page": "fa-regular fa-file",
      "core.post": "fa-regular fa-newspaper",
  }
  

This configuration assigns icons to core.page, core.post, and healthpackage.lab using Font Awesome icon classes.

• Note: Icons are only applied to models. Submenus do not have icons.

8. Analytics Configuration

analytics_models

By default, Dashub automatically detects the top 5 largest models with date fields to display in the growth charts. You can strictly configure which models appear using the analytics_models setting.

• Format:

  "analytics_models": [
      {
          "model": "app_name.model_name",
          "date_field": "field_name",
          "label": "Custom Label"
      }
  ]
  

• Example:

  "analytics_models": [
      {
          "model": "auth.user",
          "date_field": "date_joined",
          "label": "New Signups"
      },
      {
          "model": "orders.order",
          "date_field": "created_at",
          "label": "Sales"
      }
  ]
  

When configured, the dashboard charts will only show data from these specified models.

9. Custom Template Tags & Filters

Dashub provides several template tags to enhance your admin templates. Load them using {% load dashub %}.

get_side_menu

Generates the sidebar menu structure.

{% load dashub %}
{% get_side_menu as menu_list %}

get_dashub_settings

Retrieves the current Dashub configuration settings.

{% get_dashub_settings as settings %}
{{ settings.site_logo }}

get_user_avatar

Fetches the avatar for the current user. It respects the user_avatar setting.

{% get_user_avatar request.user as avatar_url %}
<img src="{{ avatar_url }}">

get_analytics_data

Retrieves analytics stats (Total Apps, Models, Records) and time-series data for the dashboard.

{% get_analytics_data as analytics %}
{{ analytics.total_records }}

10. Custom Filters

Dashub includes a set of enhanced filters for the Django admin changelist.

Standard Filters

• RadioFilter: Renders standard list filter as radio buttons.
• CheckboxFilter: Renders standard list filter as checkboxes.
• DropdownFilter: Renders standard list filter as a dropdown (select).
• MultipleDropdownFilter: Dropdown allowing multiple selections.

Choice Field Filters

For fields with choices defined:

• ChoicesRadioFilter
• ChoicesCheckboxFilter
• ChoicesDropdownFilter
• ChoicesMultipleDropdownFilter

Boolean Filters

• BooleanRadioFilter: Radio buttons for Boolean fields (Yes/No/All).

Related Field Filters

For ForeignKey/ManyToManyField fields:

• RelatedCheckboxFilter
• RelatedDropdownFilter
• MultipleRelatedDropdownFilter
• AutocompleteSelectFilter: Uses Django's autocomplete widget in filter.
• AutocompleteSelectMultipleFilter: Autocomplete allowing multiple selections.

Date/Time Filters

• RangeDateFilter: Date picker range input (From - To).
• RangeDateTimeFilter: DateTime picker range input.

Usage Example:

from dashub.contrib.filters import (
    BooleanRadioFilter, 
    AutocompleteSelectFilter, 
    RangeDateFilter
)

class MyModelAdmin(admin.ModelAdmin):
    list_filter = (
        ("is_active", BooleanRadioFilter),
        ("user", AutocompleteSelectFilter),
        ("created_at", RangeDateFilter),
    )

11. Full Configuration Example

Here is an example of a complete DASHHUB_SETTINGS configuration:

DASHUB_SETTINGS = {
    "site_logo": "/static/logo.svg",
    "site_icon": "/static/favicon.ico",
    "theme_color": "#31aa98",
    "border_radius": "5px",
    "hide_models": [
        "auth",  # Hides all models in the auth app
        "auth.group"  # Hides the group model in the auth app
    ],
    "custom_links": {
        "auth": [
            {
                "model": "auth.post" # Links directly to the auth.post model
            },
            {
                "name": "User Management",
                "icon": "fa-solid fa-users",
                "submenu": [
                    {"model": "auth.user", "order": 1},
                    {"model": "auth.group", "order": 2}
                ]
            }
        ],
    },
    "submenus_models": ["auth.group"],
    "default_orders": {
        "auth": 10,
        "auth.group": 4,
    },
    "icons": {
        "auth": "fa-regular fa-user",
        "auth.user": "fa-regular fa-user",
    },
    "custom_js": [
        "/static/js/admin.js",
    ],
    "custom_css": [
        "/static/css/admin.css",
    ]
}

Dependencies

• Django 3.2+
• Bootstrap 5
• Font Awesome 5
• jQuery

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Submit a Pull Request

GitHub Repository: https://github.com/klixsoft/django-dashub

License

This project is licensed under the MIT License - see the LICENSE file for details.