======================
Admin Index for Django
======================
:Version: 3.1.1
:Download: https://pypi.python.org/pypi/django-admin-index
:Source: https://github.com/maykinmedia/django-admin-index
:Keywords: django, admin, dashboard
|build-status| |code-quality| |black| |coverage| |license| |python-versions| |django-versions| |pypi-version|
About
=====
This extension enables you to group, order and customize the Django admin
index page without too much hassle or visual changes.
There are 2 concepts: `Application groups` and `Application links`. You can
create an application group and add any model to it in the Django admin, under
``Admin index``. Whether the models are shown to the user, depends on the
regular Django permissions and whether it's registered in the admin.
An application link is simply a URL with a name that you can add to an
application group. It shows as a regular Django model.
One final change in the Django admin is the removal of the App lists, that
link to a list of models within an App. This concept became obsolete.
|screenshot-1| |screenshot-2| |screenshot-3|
Installation
============
You can install django_admin_index either via the Python Package Index (PyPI)
or from source.
To install using ``pip``:
.. code-block:: console
$ pip install -U django-admin-index
Usage
=====
To use this with your project you need to follow these steps:
#. Add ``django_admin_index`` and ``ordered_model`` to ``INSTALLED_APPS`` in
your Django project's ``settings.py``. Make sure that
``django_admin_index`` comes before ``django.contrib.admin``:
.. code-block:: python
INSTALLED_APPS = (
"django_admin_index",
"ordered_model",
...,
"django.contrib.admin",
)
Note that there is no dash in the module name, only underscores.
#. Create the database tables by performing a database migration:
.. code-block:: console
$ python manage.py migrate admin_index
#. Go to the Django admin of your site and look for the "Application groups"
section.
Configuration
=============
There are optional settings you can add to your ``settings.py``:
- ``ADMIN_INDEX_SHOW_REMAINING_APPS`` (defaults to ``False``)
Show all models that are not added to an `Application group` in a group
called "Miscellaneous" for **staff** users.
NOTE: If no `Application groups` are defined, it will show all models
regardless of this setting.
- ``ADMIN_INDEX_SHOW_REMAINING_APPS_TO_SUPERUSERS`` (defaults to ``True``)
Show all models that are not added a to an `Application group` in a group
called "Miscellaneous" for **super users** users.
NOTE: If no `Application groups` are defined, it will show all models
regardless of this setting.
- ``ADMIN_INDEX_AUTO_CREATE_APP_GROUP`` (defaults to ``False``)
Automaticly creates an `Application group`, based on the `app_label`, for
all the models that would be in the "Miscellaneous" group. If ``True``, your
Django admin will initially look as it normally would. It will not update
existing `Application groups`.
- ``ADMIN_INDEX_SHOW_MENU`` (defaults to: ``True``)
Show the admin index as a menu above the breadcrumbs. Submenu's are filled
with the registered models.
* ``ADMIN_INDEX_HIDE_APP_INDEX_PAGES`` (defaults to: ``True``)
Removes the links to the app index pages from the main index and the
breadcrumbs.
* ``ADMIN_INDEX_DISPLAY_DROP_DOWN_MENU_CONDITION_FUNCTION`` (defaults to
``django_admin_index.utils.should_display_dropdown_menu``)
A Python dotted path that can be imported to check when the dropdown menu should be
displayed in the admin. The default implementation displays this menu if the user is
a staff user and ``ADMIN_INDEX_SHOW_MENU`` is enabled.
Extra
=====
Theming
-------
By default, django-admin-index tabs/dropdowns are styled in the Django admin theme
colours. On Django 3.2+ these are controlled through CSS variables in the
``static/admin/css/base.css`` stylesheet. These CSS variables are used as defaults for
django-admin-index' own CSS variables.
See ``scss/_vars.scss`` for all the available CSS variables you can use to customize
the color palette. A simple example:
.. code-block:: css
:root {
--djai-tab-bg: #ff0080;
--djai-tab-bg--hover: #a91b60;
}
Any rules not supported by CSS vars can be overridden with regular CSS. All elements
have CSS class names following the BEM methodology, such as
``.djai-dropdown-menu__item`` and
``.djai-dropdown-menu__item.djai-dropdown-menu__item--active``.
Sticky header
-------------
The header (typically "Django administration") including the menu (added by this
library) become sticky (ie. they stay visible when you scroll down on large pages). If
you don't want this, you can add some CSS lines, like:
.. code-block:: css
#header { position: initial; }
.djai-dropdown-menu { position: initial; }
Breadcrumbs
-----------
You can also squeeze additional content in the breadcrumbs, just after
``Home``. Simply overwrite the block ``breadcrumbs_pre_changelist`` in the
admin templates you desire (``change_list.html``, ``change_form.html``, etc.)
.. code-block:: django
{% block breadcrumbs_pre_changelist %}
› Meaningful breadcrumb element
{% endblock %}
Contributors
============
Contributors and maintainers can install the project locally with all test dependencies
in a virtualenv:
.. code-block:: bash
(env) $ pip install -e .[tests,pep8,coverage,release]
Running the test suite
----------------------
To run the tests for a single environment (currently installed in your virtualenv), use
``pytest``:
.. code-block:: bash
(env) $ pytest
To run the complete build matrix, use ``tox``:
.. code-block:: bash
(env) $ tox
Developing the frontend
-----------------------
To develop the stylesheets, you can use the included test project:
.. code-block:: bash
(env) $ python manage.py runserver
You also want to install the frontend tooling and run the SCSS compilation to CSS in
watch mode:
.. code-block:: bash
npm install # one time to get the dependencies installed
npm run watch
Once the result is satisfactory, you can make a production build of the stylesheets:
.. code-block:: bash
npm run scss
Then, commit the changes and make a pull request.
.. |build-status| image:: https://github.com/maykinmedia/django-admin-index/actions/workflows/ci.yml/badge.svg
:alt: Build status
:target: https://github.com/maykinmedia/django-admin-index/actions/workflows/ci.yml
.. |code-quality| image:: https://github.com/maykinmedia/django-admin-index/workflows/Code%20quality%20checks/badge.svg
:alt: Code quality checks
:target: https://github.com/maykinmedia/django-admin-index/actions?query=workflow%3A%22Code+quality+checks%22
.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
.. |coverage| image:: https://codecov.io/github/maykinmedia/django-admin-index/coverage.svg?branch=master
:target: https://codecov.io/github/maykinmedia/django-admin-index?branch=master
.. |license| image:: https://img.shields.io/pypi/l/django-admin-index.svg
:alt: BSD License
:target: https://opensource.org/licenses/BSD-3-Clause
.. |python-versions| image:: https://img.shields.io/pypi/pyversions/django-admin-index.svg
:alt: Supported Python versions
:target: http://pypi.python.org/pypi/django-admin-index/
.. |django-versions| image:: https://img.shields.io/pypi/djversions/django-admin-index.svg
:alt: Supported Django versions
:target: http://pypi.python.org/pypi/django-admin-index/
.. |pypi-version| image:: https://img.shields.io/pypi/v/django-admin-index.svg
:target: https://pypi.org/project/django-admin-index/
.. |screenshot-1| image:: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/dashboard_with_menu_thumb.png
:alt: Ordered dashboard with dropdown menu.
:target: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/dashboard_with_menu.png
.. |screenshot-2| image:: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/application_groups_thumb.png
:alt: Manage Application groups.
:target: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/application_groups.png
.. |screenshot-3| image:: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/change_user_management_group_thumb.png
:alt: Configure application groups and add Application links.
:target: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/change_user_management_group.png
Raw data
{
"_id": null,
"home_page": "https://github.com/maykinmedia/django-admin-index",
"name": "django-admin-index",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "django,index,dashboard",
"author": "Joeri Bekker",
"author_email": "joeri@maykinmedia.nl",
"download_url": "https://files.pythonhosted.org/packages/a6/0c/f68ce5ddd8b1469a78b81f432f4fa51bdd74a9045c8cada7cc5a7e8a4914/django-admin-index-3.1.1.tar.gz",
"platform": null,
"description": "======================\nAdmin Index for Django\n======================\n\n:Version: 3.1.1\n:Download: https://pypi.python.org/pypi/django-admin-index\n:Source: https://github.com/maykinmedia/django-admin-index\n:Keywords: django, admin, dashboard\n\n|build-status| |code-quality| |black| |coverage| |license| |python-versions| |django-versions| |pypi-version|\n\nAbout\n=====\n\nThis extension enables you to group, order and customize the Django admin\nindex page without too much hassle or visual changes.\n\nThere are 2 concepts: `Application groups` and `Application links`. You can\ncreate an application group and add any model to it in the Django admin, under\n``Admin index``. Whether the models are shown to the user, depends on the\nregular Django permissions and whether it's registered in the admin.\n\nAn application link is simply a URL with a name that you can add to an\napplication group. It shows as a regular Django model.\n\nOne final change in the Django admin is the removal of the App lists, that\nlink to a list of models within an App. This concept became obsolete.\n\n|screenshot-1| |screenshot-2| |screenshot-3|\n\nInstallation\n============\n\nYou can install django_admin_index either via the Python Package Index (PyPI)\nor from source.\n\nTo install using ``pip``:\n\n.. code-block:: console\n\n $ pip install -U django-admin-index\n\nUsage\n=====\n\nTo use this with your project you need to follow these steps:\n\n#. Add ``django_admin_index`` and ``ordered_model`` to ``INSTALLED_APPS`` in\n your Django project's ``settings.py``. Make sure that\n ``django_admin_index`` comes before ``django.contrib.admin``:\n\n .. code-block:: python\n\n INSTALLED_APPS = (\n \"django_admin_index\",\n \"ordered_model\",\n ...,\n \"django.contrib.admin\",\n )\n\n Note that there is no dash in the module name, only underscores.\n\n#. Create the database tables by performing a database migration:\n\n .. code-block:: console\n\n $ python manage.py migrate admin_index\n\n#. Go to the Django admin of your site and look for the \"Application groups\"\n section.\n\nConfiguration\n=============\n\nThere are optional settings you can add to your ``settings.py``:\n\n- ``ADMIN_INDEX_SHOW_REMAINING_APPS`` (defaults to ``False``)\n\n Show all models that are not added to an `Application group` in a group\n called \"Miscellaneous\" for **staff** users.\n\n NOTE: If no `Application groups` are defined, it will show all models\n regardless of this setting.\n\n- ``ADMIN_INDEX_SHOW_REMAINING_APPS_TO_SUPERUSERS`` (defaults to ``True``)\n\n Show all models that are not added a to an `Application group` in a group\n called \"Miscellaneous\" for **super users** users.\n\n NOTE: If no `Application groups` are defined, it will show all models\n regardless of this setting.\n\n- ``ADMIN_INDEX_AUTO_CREATE_APP_GROUP`` (defaults to ``False``)\n\n Automaticly creates an `Application group`, based on the `app_label`, for\n all the models that would be in the \"Miscellaneous\" group. If ``True``, your\n Django admin will initially look as it normally would. It will not update\n existing `Application groups`.\n\n- ``ADMIN_INDEX_SHOW_MENU`` (defaults to: ``True``)\n\n Show the admin index as a menu above the breadcrumbs. Submenu's are filled\n with the registered models.\n\n* ``ADMIN_INDEX_HIDE_APP_INDEX_PAGES`` (defaults to: ``True``)\n\n Removes the links to the app index pages from the main index and the\n breadcrumbs.\n\n* ``ADMIN_INDEX_DISPLAY_DROP_DOWN_MENU_CONDITION_FUNCTION`` (defaults to\n ``django_admin_index.utils.should_display_dropdown_menu``)\n\n A Python dotted path that can be imported to check when the dropdown menu should be\n displayed in the admin. The default implementation displays this menu if the user is\n a staff user and ``ADMIN_INDEX_SHOW_MENU`` is enabled.\n\nExtra\n=====\n\nTheming\n-------\n\nBy default, django-admin-index tabs/dropdowns are styled in the Django admin theme\ncolours. On Django 3.2+ these are controlled through CSS variables in the\n``static/admin/css/base.css`` stylesheet. These CSS variables are used as defaults for\ndjango-admin-index' own CSS variables.\n\nSee ``scss/_vars.scss`` for all the available CSS variables you can use to customize\nthe color palette. A simple example:\n\n.. code-block:: css\n\n :root {\n --djai-tab-bg: #ff0080;\n --djai-tab-bg--hover: #a91b60;\n }\n\nAny rules not supported by CSS vars can be overridden with regular CSS. All elements\nhave CSS class names following the BEM methodology, such as\n``.djai-dropdown-menu__item`` and\n``.djai-dropdown-menu__item.djai-dropdown-menu__item--active``.\n\n\nSticky header\n-------------\n\nThe header (typically \"Django administration\") including the menu (added by this\nlibrary) become sticky (ie. they stay visible when you scroll down on large pages). If\nyou don't want this, you can add some CSS lines, like:\n\n.. code-block:: css\n\n #header { position: initial; }\n .djai-dropdown-menu { position: initial; }\n\n\nBreadcrumbs\n-----------\n\nYou can also squeeze additional content in the breadcrumbs, just after\n``Home``. Simply overwrite the block ``breadcrumbs_pre_changelist`` in the\nadmin templates you desire (``change_list.html``, ``change_form.html``, etc.)\n\n.. code-block:: django\n\n {% block breadcrumbs_pre_changelist %}\n › Meaningful breadcrumb element\n {% endblock %}\n\n\nContributors\n============\n\nContributors and maintainers can install the project locally with all test dependencies\nin a virtualenv:\n\n.. code-block:: bash\n\n (env) $ pip install -e .[tests,pep8,coverage,release]\n\nRunning the test suite\n----------------------\n\nTo run the tests for a single environment (currently installed in your virtualenv), use\n``pytest``:\n\n.. code-block:: bash\n\n (env) $ pytest\n\nTo run the complete build matrix, use ``tox``:\n\n.. code-block:: bash\n\n (env) $ tox\n\nDeveloping the frontend\n-----------------------\n\nTo develop the stylesheets, you can use the included test project:\n\n.. code-block:: bash\n\n (env) $ python manage.py runserver\n\nYou also want to install the frontend tooling and run the SCSS compilation to CSS in\nwatch mode:\n\n.. code-block:: bash\n\n npm install # one time to get the dependencies installed\n npm run watch\n\nOnce the result is satisfactory, you can make a production build of the stylesheets:\n\n.. code-block:: bash\n\n npm run scss\n\nThen, commit the changes and make a pull request.\n\n\n.. |build-status| image:: https://github.com/maykinmedia/django-admin-index/actions/workflows/ci.yml/badge.svg\n :alt: Build status\n :target: https://github.com/maykinmedia/django-admin-index/actions/workflows/ci.yml\n\n.. |code-quality| image:: https://github.com/maykinmedia/django-admin-index/workflows/Code%20quality%20checks/badge.svg\n :alt: Code quality checks\n :target: https://github.com/maykinmedia/django-admin-index/actions?query=workflow%3A%22Code+quality+checks%22\n\n.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n\n.. |coverage| image:: https://codecov.io/github/maykinmedia/django-admin-index/coverage.svg?branch=master\n :target: https://codecov.io/github/maykinmedia/django-admin-index?branch=master\n\n.. |license| image:: https://img.shields.io/pypi/l/django-admin-index.svg\n :alt: BSD License\n :target: https://opensource.org/licenses/BSD-3-Clause\n\n.. |python-versions| image:: https://img.shields.io/pypi/pyversions/django-admin-index.svg\n :alt: Supported Python versions\n :target: http://pypi.python.org/pypi/django-admin-index/\n\n.. |django-versions| image:: https://img.shields.io/pypi/djversions/django-admin-index.svg\n :alt: Supported Django versions\n :target: http://pypi.python.org/pypi/django-admin-index/\n\n.. |pypi-version| image:: https://img.shields.io/pypi/v/django-admin-index.svg\n :target: https://pypi.org/project/django-admin-index/\n\n.. |screenshot-1| image:: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/dashboard_with_menu_thumb.png\n :alt: Ordered dashboard with dropdown menu.\n :target: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/dashboard_with_menu.png\n\n.. |screenshot-2| image:: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/application_groups_thumb.png\n :alt: Manage Application groups.\n :target: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/application_groups.png\n\n.. |screenshot-3| image:: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/change_user_management_group_thumb.png\n :alt: Configure application groups and add Application links.\n :target: https://github.com/maykinmedia/django-admin-index/raw/master/docs/_assets/change_user_management_group.png\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Admin index for Django",
"version": "3.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/maykinmedia/django-admin-index/issues",
"Changelog": "https://github.com/maykinmedia/django-admin-index/blob/master/CHANGELOG.rst",
"Homepage": "https://github.com/maykinmedia/django-admin-index",
"Source Code": "https://github.com/maykinmedia/django-admin-index"
},
"split_keywords": [
"django",
"index",
"dashboard"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "80d20dafcc8cde0783b56126f790e551e3a644d7f7506161685ba7177054c78d",
"md5": "dae87b6fcdd274034303b9cd95188f31",
"sha256": "6efff9316af395507e6cbea280241ccf23682a0366947542d1b234b8cb643bbc"
},
"downloads": -1,
"filename": "django_admin_index-3.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dae87b6fcdd274034303b9cd95188f31",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 30539,
"upload_time": "2024-02-29T21:44:47",
"upload_time_iso_8601": "2024-02-29T21:44:47.566699Z",
"url": "https://files.pythonhosted.org/packages/80/d2/0dafcc8cde0783b56126f790e551e3a644d7f7506161685ba7177054c78d/django_admin_index-3.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a60cf68ce5ddd8b1469a78b81f432f4fa51bdd74a9045c8cada7cc5a7e8a4914",
"md5": "091040f4a936759e6e1b6c853eb0a221",
"sha256": "31ba8b68ec2c89a8872e2dce4dbc668031100ca8616d464efa2fa4467cc0f429"
},
"downloads": -1,
"filename": "django-admin-index-3.1.1.tar.gz",
"has_sig": false,
"md5_digest": "091040f4a936759e6e1b6c853eb0a221",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 28557,
"upload_time": "2024-02-29T21:44:49",
"upload_time_iso_8601": "2024-02-29T21:44:49.268758Z",
"url": "https://files.pythonhosted.org/packages/a6/0c/f68ce5ddd8b1469a78b81f432f4fa51bdd74a9045c8cada7cc5a7e8a4914/django-admin-index-3.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-29 21:44:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "maykinmedia",
"github_project": "django-admin-index",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-admin-index"
}
JSON
