diff --git a/LICENSE b/LICENSE index 0cd1ad39..81f990d6 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2019 wuyue +Copyright (c) 2020 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index d46f1b9d..438ccca8 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![PyPI pyversions](https://img.shields.io/pypi/pyversions/django-jazzmin.svg)](https://pypi.python.org/pypi/django-jazzmin/) [![Coverage Status](https://coveralls.io/repos/github/farridav/django-jazzmin/badge.svg?branch=master)](https://coveralls.io/github/farridav/django-jazzmin?branch=master) -Drop-in theme for django admin, that utilises AdminLTE 3 & Bootstrap 4 to make yo' admin looky jazzy +Drop-in theme for django admin, that utilises AdminLTE 3 & Bootstrap 4 to make yo' admin look jazzy ## Installation ``` @@ -21,6 +21,7 @@ See [Documentation](https://django-jazzmin.readthedocs.io/) or [Test App](./test - Drop-in, configure only if you want to - Customisable side menu - Customisable top menu +- Customisable user menu - Customisable UI (via Live UI changes, or custom CSS/JS) - Based on the latest [adminlte](https://adminlte.io/) + [bootstrap](https://getbootstrap.com/) diff --git a/README.rst b/README.rst index b282b43c..ceb9cb44 100644 --- a/README.rst +++ b/README.rst @@ -23,9 +23,14 @@ See https://django-jazzmin.readthedocs.io also see `Test App`_ Features -------- - Drop-in admin skin, all configuration optional +- Select2 drop-downs +- Bootstrap 4 & AdminLTE UI components - Customisable `side menu`_ - Customisable `top menu`_ +- Customisable `user menu`_ +- Search bar for any given model admin - Customisable UI (via `Live UI changes`_, or `custom CSS/JS`_) +- Responsive - Based on the latest `adminlte`_ + `bootstrap`_ Screenshots @@ -51,10 +56,20 @@ UI Customiser ~~~~~~~~~~~~~ .. image:: https://django-jazzmin.readthedocs.io/img/ui_customiser.png +Mobile/Tablet layouts +~~~~~~~~~~~~~~~~~~~~~ +.. image:: https://django-jazzmin.readthedocs.io/img/dashboard_mobile.png +.. image:: https://django-jazzmin.readthedocs.io/img/dashboard_table.png + +Admin Docs (if installed) +~~~~~~~~~~~~~~~~~~~~~~~~~ +.. image:: https://django-jazzmin.readthedocs.io/img/admin_docs.png + .. _adminlte: https://adminlte.io/ .. _bootstrap: https://getbootstrap.com .. _Test App: https://github.com/farridav/django-jazzmin/tree/master/tests/test_app -.. _top menu: https://github.com/farridav/django-jazzmin/blob/master/tests/test_app/settings.py#L61 +.. _top menu: https://github.com/farridav/django-jazzmin/blob/master/tests/test_app/settings.py#L62 .. _side menu: https://github.com/farridav/django-jazzmin/blob/master/tests/test_app/settings.py#L92 -.. _Live UI changes: https://github.com/farridav/django-jazzmin/blob/master/tests/test_app/settings.py#L90 -.. _custom CSS/JS: https://github.com/farridav/django-jazzmin/blob/master/tests/test_app/settings.py#L86 +.. _user menu: https://github.com/farridav/django-jazzmin/blob/master/tests/test_app/settings.py#L86 +.. _Live UI changes: https://github.com/farridav/django-jazzmin/blob/master/tests/test_app/settings.py#L133 +.. _custom CSS/JS: https://github.com/farridav/django-jazzmin/blob/master/tests/test_app/settings.py#L129 diff --git a/docs/configuration.md b/docs/configuration.md index 494bf362..a9d60a9f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -27,6 +27,10 @@ JAZZMIN_SETTINGS = { # Field name on user model that contains avatar image 'user_avatar': None, + ############ + # Top Menu # + ############ + # Links to put along the top menu 'topmenu_links': [ @@ -43,6 +47,20 @@ JAZZMIN_SETTINGS = { {'app': 'polls'}, ], + ############# + # User Menu # + ############# + + # Additional links to include in the user menu on the top right ('app' url type is not allowed) + 'usermenu_links': [ + {'name': 'Support', 'url': 'https://github.com/farridav/django-jazzmin/issues', 'new_window': True}, + {'model': 'auth.user'} + ], + + ############# + # Side Menu # + ############# + # Whether to display the side menu 'show_sidebar': True, @@ -85,6 +103,11 @@ You can enable the top menu by specifying `'topmenu_links'` in your `JAZZMIN_SET The top menu can be styled with the UI Customiser (See below) +## User menu +You can add links to the user menu on the top right of the screen using the `'usermenu_links'` settings key, the format +of these links is the same as with top menu (above), though submenus via 'app' are not currently supported and will not +be rendered. + ## Side menu ### How its generated @@ -98,7 +121,7 @@ model is like `auth.user` Ordering of the menu can be done using `order_with_respect_to`, which is a list of apps you want to base the ordering off of, it can be a partial list -### Adding custom links +### Side menu custom links Custom links can be added using `custom_links`, this is a dictionary of links, keyed on the app they will live under. Example: diff --git a/docs/img/admin_docs.png b/docs/img/admin_docs.png new file mode 100644 index 00000000..37a741ef Binary files /dev/null and b/docs/img/admin_docs.png differ diff --git a/docs/img/dashboard_mobile.png b/docs/img/dashboard_mobile.png new file mode 100644 index 00000000..cd06fa24 Binary files /dev/null and b/docs/img/dashboard_mobile.png differ diff --git a/docs/img/dashboard_tablet.png b/docs/img/dashboard_tablet.png new file mode 100644 index 00000000..e3dd2b66 Binary files /dev/null and b/docs/img/dashboard_tablet.png differ diff --git a/docs/index.md b/docs/index.md index 46915cd3..ce655498 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,32 +1,21 @@ # Jazzmin -## Installation - -Install the latest [pypi](https://pypi.org/project/django-jazzmin/) release with `pip install -U django-jazzmin` - -Add `jazzmin` to your `INSTALLED_APPS` before `django.contrib.admin`, and voila! - -```python -INSTALLED_APPS = [ - 'jazzmin', - - 'django.contrib.admin', - [...] -] -``` +Welcome to Jazzmin, intended as a drop-in app to jazz up your django admin site, with plenty of things you can easily +customise, including a built-in UI customizer ## Features - Drop-in, configure only if you want to +- Select2 drop-downs +- Bootstrap 4 & AdminLTE UI components +- Search bar for any given model admin - Customisable side menu - Customisable top menu +- Customisable user menu +- Responsive - Customisable UI (via Live UI changes, or custom CSS/JS) - Based on the latest [adminlte](https://adminlte.io/) + [bootstrap](https://getbootstrap.com/) -See [configuration](./configuration.md) for optional customisation of the theme - -See [development](./development.md) for notes on setting up for development - ## Screenshots ### Dashboard @@ -42,7 +31,14 @@ See [development](./development.md) for notes on setting up for development ![login](./img/login.png) ### UI Customiser -![login](./img/ui_customiser.png) +![UI Customiser](./img/ui_customiser.png) + +### Mobile/Tablet layouts +![Admin docs](./img/dashboard_mobile.png) +![Admin docs](./img/dashboard_tablet.png) + +### Admin docs (if installed) +![Admin docs](./img/admin_docs.png) ## Thanks This was initially a Fork of https://github.com/wuyue92tree/django-adminlte-ui that we refactored so much we thought it diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..7ff539d1 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,18 @@ +# Installation + +Install the latest [pypi](https://pypi.org/project/django-jazzmin/) release with `pip install -U django-jazzmin` + +Add `jazzmin` to your `INSTALLED_APPS` before `django.contrib.admin`, and Voila! + +```python +INSTALLED_APPS = [ + 'jazzmin', + + 'django.contrib.admin', + [...] +] +``` + +See [configuration](./configuration.md) for optional customisation of the theme + +See [development](./development.md) for notes on setting up for development diff --git a/jazzmin/settings.py b/jazzmin/settings.py index b77f7de8..1128131b 100644 --- a/jazzmin/settings.py +++ b/jazzmin/settings.py @@ -3,7 +3,7 @@ from django.conf import settings from django.contrib.admin import AdminSite -from .utils import get_admin_url, get_custom_url, get_model_meta, get_app_admin_urls +from .utils import get_admin_url, get_model_meta DEFAULT_SETTINGS = { # title of the window @@ -35,15 +35,11 @@ 'topmenu_links': [], ############# - # UI Tweaks # + # User Menu # ############# - # Relative paths to custom CSS/JS scripts (must be present in static files) - 'custom_css': None, - 'custom_js': None, - - # Whether to show the UI customizer on the sidebar - 'show_ui_builder': False, + # Additional links to include in the user menu on the top right ('app' url type is not allowed) + 'usermenu_links': [], ############# # Side Menu # @@ -71,7 +67,18 @@ # for a list of icon classes 'icons': { 'auth.user': 'fa-user', - } + }, + + ############# + # UI Tweaks # + ############# + + # Relative paths to custom CSS/JS scripts (must be present in static files) + 'custom_css': None, + 'custom_js': None, + + # Whether to show the UI customizer on the sidebar + 'show_ui_builder': False, } ####################################### @@ -133,21 +140,16 @@ def get_settings(): user_settings = {x: y for x, y in getattr(settings, 'JAZZMIN_SETTINGS', {}).items() if y is not None} jazzmin_settings.update(user_settings) + # Extract search url from search model if jazzmin_settings['search_model']: jazzmin_settings['search_url'] = get_admin_url(jazzmin_settings['search_model'].lower()) - jazzmin_settings['search_name'] = jazzmin_settings['search_model'].split('.')[-1] + 's' - - for link in jazzmin_settings.get('topmenu_links', []): - if 'url' in link: - link['url'] = get_custom_url(link['url']) - elif 'model' in link: - model_meta = get_model_meta(link['model']) - link['name'] = model_meta.verbose_name_plural.title() if model_meta else link['model'] - link['url'] = get_admin_url(link['model']) - elif 'app' in link: - link['name'] = link['app'].title() - link['app_children'] = get_app_admin_urls(link['app']) + model_meta = get_model_meta(jazzmin_settings['search_model']) + if model_meta: + jazzmin_settings['search_name'] = model_meta.verbose_name_plural.title() + else: + jazzmin_settings['search_name'] = jazzmin_settings['search_model'].split('.')[-1] + 's' + # Deal with single strings in hide_apps/hide_models and make sure we lower case 'em if type(jazzmin_settings['hide_apps']) == str: jazzmin_settings['hide_apps'] = [jazzmin_settings['hide_apps']] jazzmin_settings['hide_apps'] = [x.lower() for x in jazzmin_settings['hide_apps']] diff --git a/jazzmin/static/jazzmin/css/django.css b/jazzmin/static/jazzmin/css/django.css index 51e7a517..0ce1f0d0 100644 --- a/jazzmin/static/jazzmin/css/django.css +++ b/jazzmin/static/jazzmin/css/django.css @@ -634,7 +634,7 @@ body.no-sidebar .content-wrapper, body.no-sidebar .main-footer, body.no-sidebar word-break: break-word; } -.brand-link { +.navbar-nav .brand-link { padding-top: 3px; } diff --git a/jazzmin/templates/admin/base.html b/jazzmin/templates/admin/base.html index 05e36473..22b184a8 100644 --- a/jazzmin/templates/admin/base.html +++ b/jazzmin/templates/admin/base.html @@ -105,7 +105,7 @@ {% endif %} -
+ diff --git a/jazzmin/templatetags/jazzmin.py b/jazzmin/templatetags/jazzmin.py index 24f34f38..32d4b214 100644 --- a/jazzmin/templatetags/jazzmin.py +++ b/jazzmin/templatetags/jazzmin.py @@ -14,7 +14,9 @@ from .. import version from ..settings import get_settings, get_ui_tweaks -from ..utils import order_with_respect_to, get_filter_id, get_custom_url, get_admin_url, get_view_permissions +from ..utils import ( + order_with_respect_to, get_filter_id, get_custom_url, get_admin_url, get_view_permissions, make_menu +) User = get_user_model() register = Library() @@ -80,33 +82,20 @@ def get_side_menu(context): @register.simple_tag def get_top_menu(user): - if not user: - return [] - - model_permissions = get_view_permissions(user) + """ + Produce the menu for the top nav bar + """ options = get_settings() + return make_menu(user, options.get('topmenu_links', [])) - menu = [] - for item in options.get('topmenu_links', []): - - perm_matches = [] - for perm in item.get('permissions', []): - perm_matches.append(user.has_perm(perm)) - - if not all(perm_matches): - continue - - if item.get('model') and item.get('model').lower() not in model_permissions: - continue - - if item.get('app'): - item['app_children'] = list(filter(lambda x: x['model'] in model_permissions, item['app_children'])) - if len(item['app_children']) == 0: - continue - - menu.append(item) - return menu +@register.simple_tag +def get_user_menu(user): + """ + Produce the menu for the user dropdown + """ + options = get_settings() + return make_menu(user, options.get('usermenu_links', []), allow_appmenus=False) @register.simple_tag @@ -253,9 +242,8 @@ def sidebar_status(request): @register.filter def can_view_self(perms): view_perm = '{}.view_{}'.format(User._meta.app_label, User._meta.model_name) - change_perm = '{}.change_{}'.format(User._meta.app_label, User._meta.model_name) - return perms[User._meta.app_label][view_perm] or perms[User._meta.app_label][change_perm] + return perms[User._meta.app_label][view_perm] @register.simple_tag diff --git a/jazzmin/utils.py b/jazzmin/utils.py index 0849439e..3f244bf0 100644 --- a/jazzmin/utils.py +++ b/jazzmin/utils.py @@ -86,7 +86,7 @@ def get_custom_url(url): def get_model_meta(model_str): """ - Get the plural name + Get model meta class """ try: app, model = model_str.split('.') @@ -126,3 +126,49 @@ def get_view_permissions(user): Get model names based on a users view permissions """ return {x.replace('view_', '') for x in user.get_all_permissions() if 'view' in x} + + +def make_menu(user, links, allow_appmenus=True): + """ + Make a menu from a list of user supplied links + """ + if not user: + return [] + + model_permissions = get_view_permissions(user) + + menu = [] + for link in links: + + perm_matches = [] + for perm in link.get('permissions', []): + perm_matches.append(user.has_perm(perm)) + + if not all(perm_matches): + continue + + if 'url' in link: + link['url'] = get_custom_url(link['url']) + + elif 'model' in link: + if link['model'].lower() not in model_permissions: + continue + + model_meta = get_model_meta(link['model']) + link['name'] = model_meta.verbose_name_plural.title() if model_meta else link['model'] + link['url'] = get_admin_url(link['model']) + + elif 'app' in link and allow_appmenus: + link['name'] = link['app'].title() + link['app_children'] = list( + filter(lambda x: x['model'] in model_permissions, get_app_admin_urls(link['app'])) + ) + if len(link['app_children']) == 0: + continue + + else: + continue + + menu.append(link) + + return menu diff --git a/mkdocs.yml b/mkdocs.yml index 8c62dc02..eaddadf7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,7 @@ site_name: Jazzmin nav: - Home: index.md + - Installation: installation.md - Configuration: configuration.md - Development: development.md theme: readthedocs diff --git a/setup.cfg b/setup.cfg index 86ff892d..6ce48548 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,32 @@ [metadata] +name = Django Jazzmin description-file = README.md +version = attr: jazzmin.version +url = https://github.com/farridav/django-jazzmin +author = farridav +description = Drop-in theme for django admin, that utilises AdminLTE 3 & Bootstrap 4 to make yo' admin look jazzy +long_description = file: README.rst +license = MIT +classifiers = + Environment :: Web Environment + License :: MIT License + Operating System :: OS Independent + Programming Language :: Python + Programming Language :: Python :: 3 + Programming Language :: Python :: 3 :: Only + Programming Language :: Python :: 3.5 + Programming Language :: Python :: 3.6 + Programming Language :: Python :: 3.7 + Programming Language :: Python :: 3.8 + Topic :: Internet :: WWW/HTTP + Topic :: Internet :: WWW/HTTP :: Dynamic Content + Topic :: Internet :: WWW/HTTP :: WSGI + Topic :: Software Development :: Libraries :: Application Frameworks + Topic :: Software Development :: Libraries :: Python Modules +project_urls = + Documentation = https://django-jazzmin.readthedocs.io/ + Release notes = https://github.com/farridav/django-jazzmin/releases + Source = https://github.com/farridav/django-jazzmin/ [bdist_wheel] universal = 1 diff --git a/setup.py b/setup.py index 1e623ed9..e49bed9c 100644 --- a/setup.py +++ b/setup.py @@ -5,12 +5,14 @@ from jazzmin import version +REQUIRED_PYTHON = (3, 5) + setup( name='django-jazzmin', version=version, python_requires='>3.5', url='https://github.com/farridav/django-jazzmin', - description='Django admin theme based adminlte & bootstrap', + description="Drop-in theme for django admin, that utilises AdminLTE 3 & Bootstrap 4 to make yo' admin look jazzy", long_description=open('README.rst').read(), author='farridav', maintainer='farridav', diff --git a/tests/test_app/settings.py b/tests/test_app/settings.py index ef923f64..932626a3 100644 --- a/tests/test_app/settings.py +++ b/tests/test_app/settings.py @@ -79,15 +79,14 @@ ], ############# - # UI Tweaks # + # User Menu # ############# - # Relative paths to custom CSS/JS scripts (must be present in static files) - 'custom_css': None, - 'custom_js': None, - - # Whether to show the UI customizer on the sidebar - 'show_ui_builder': False, + # Additional links to include in the user menu on the top right ('app' url type is not allowed) + 'usermenu_links': [ + {'name': 'Support', 'url': 'https://github.com/farridav/django-jazzmin/issues', 'new_window': True}, + {'model': 'auth.user'} + ], ############# # Side Menu # @@ -120,7 +119,18 @@ # for a list of icon classes 'icons': { 'auth.user': 'fa-user', - } + }, + + ############# + # UI Tweaks # + ############# + + # Relative paths to custom CSS/JS scripts (must be present in static files) + 'custom_css': None, + 'custom_js': None, + + # Whether to show the UI customizer on the sidebar + 'show_ui_builder': False, } TEMPLATES = [{ diff --git a/tests/test_jazzmin.py b/tests/test_jazzmin.py index d7d72a1b..59b33cc1 100644 --- a/tests/test_jazzmin.py +++ b/tests/test_jazzmin.py @@ -2,7 +2,7 @@ from bs4 import BeautifulSoup from django.urls import reverse -from tests.utils import parse_sidemenu, user_with_permissions, parse_topmenu +from tests.utils import parse_sidemenu, user_with_permissions, parse_topmenu, parse_usermenu @pytest.mark.django_db @@ -72,6 +72,7 @@ def test_permissions_on_custom_links(client, settings): assert parse_sidemenu(response) == {'Global': ['/admin/'], 'Polls': ['/admin/polls/poll/', '/make_messages/']} +@pytest.mark.django_db def test_top_menu(admin_client, settings): """ Top menu renders out as expected @@ -97,3 +98,29 @@ def test_top_menu(admin_client, settings): {'name': 'Votes', 'link': '/admin/polls/vote/'}, ]} ] + + +@pytest.mark.django_db +def test_user_menu(admin_user, client, settings): + """ + The User menu renders out as expected + """ + url = reverse('admin:index') + + settings.JAZZMIN_SETTINGS['usermenu_links'] = [ + {'name': 'Home', 'url': 'admin:index', 'permissions': ['auth.view_user']}, + {'name': 'Support', 'url': 'https://github.com/farridav/django-jazzmin/issues', 'new_window': True}, + {'model': 'auth.User'}, + ] + + client.force_login(admin_user) + response = client.get(url) + + assert parse_usermenu(response) == [ + {'link': '/admin/password_change/', 'name': 'Change password'}, + {'link': '/admin/logout/', 'name': 'Log out'}, + {'link': '/admin/auth/user/{}/change/'.format(admin_user.pk), 'name': 'See Profile'}, + {'link': '/admin/', 'name': 'Home'}, + {'link': 'https://github.com/farridav/django-jazzmin/issues', 'name': 'Support'}, + {'link': '/admin/auth/user/', 'name': 'Users'} + ] diff --git a/tests/utils.py b/tests/utils.py index 0318b6d5..f1c76058 100644 --- a/tests/utils.py +++ b/tests/utils.py @@ -43,7 +43,8 @@ def parse_sidemenu(response): for li in soup.find(id='jazzy-sidebar').find('ul').find_all('li'): if 'nav-header' in li['class']: - current_app = li.contents[0] + current_app = li.text.strip() + elif 'nav-item' in li['class']: href = li.find('a')['href'] menu[current_app].append(href) @@ -65,11 +66,25 @@ def parse_topmenu(response): if type(anchor.contents[0]) == Tag: continue - item = {'name': anchor.contents[0].strip(), 'link': anchor['href']} + item = {'name': anchor.text.strip(), 'link': anchor['href']} dropdown = li.find('div', class_='dropdown-menu') if dropdown: - item['children'] = [{'name': a.contents[0], 'link': a['href']} for a in dropdown.find_all('a')] + item['children'] = [{'name': a.text.strip(), 'link': a['href']} for a in dropdown.find_all('a')] + + menu.append(item) + + return menu + + +def parse_usermenu(response): + """ + Convert the user menu to a list of dicts representing menus + """ + menu = [] + soup = BeautifulSoup(response.content, 'html.parser') + for link in soup.find(id='jazzy-usermenu').find_all('a'): + item = {'name': link.text.strip(), 'link': link['href']} menu.append(item) return menu