======================
Django Admin Toolbox
======================
This package provides bunch of useful tools for default django admin site, such as:
- `Sidebar`_
- `Smart breadcrumbs`_
All configuration is held in ``ADMIN_TOOLBOX`` dict that should be placed in your ``settings.py`` file.
.. warning:: This package is still in development and all API is considered unstable. This means that anything may
change without notice and without backwards compatibility!
Installation
============
1. Install admin toolbox (if not installed already)
2. add ``admin_toolbox`` at the top of your ``INSTALLED_APPS`` (at least above ``django.contrib.admin``)
Configuration
=============
All configuration of this application is held in one dictionary in django settings, named ``ADMIN_TOOLBOX``. Below you
can see default configuration:
.. code-block:: python
ADMIN_TOOLBOX = {
'sidebar': {
'default': ('admin_toolbox.builders.AppsListBuilder', {}),
},
'breadcrumbs': 'auto',
}
If you want to customize any setting, you don't have to copy whole defaults. Anything that is not set, will be filled
in with default values.
Below you can find description of how to configure each module.
Sidebar
-------
This module adds sidebar to the left of standard django admin template. This module cannot be disabled for now, as other
modules depend on it's configuration. Purpose of this sidebar is to replace default list of models in django admin with
something more customizable and useful.
By default, sidebar will just contain categories for all apps with models inside of them, which just corresponds to
list of apps and models on standard django admin dashboard. But you can customize that menu using builders.
``sidebar`` element inside ``ADMIN_TOOLBOX`` settings contains all defined menus (like for ``DATABASES``, you can
specify more than one menu). For now, only ``default`` menu is used, other ones will be ignored. Each menu consists of
root element. Each element is specified by tuple containing string and dictionary. String should be valid python dot
path to builder class, dictionary contains all default arguments that will be passed to that class when initializing.
Each builder is one of ``ListBuilder`` or ``ItemBuilder`` from ``admin_toolbox.builders`` module or any subclass
of them. For root element, only ``ListBuilder`` and it's subclasses are allowed.
Root element of each menu is a container for whole menu, but it's logic is still invoked, but it won't be rendered as
a whole, only it's sub-items will be. How to nest items is explained below.
Also, each element, except of root one, should have specified name (if specified builder cannot generate it
automatically).
There is default limit for nesting set to 3 levels. It is enforced on template level, so if you want to create menu
with more nested levels, simply overwrite template (and probably CSS) and implement displaying more than 3 levels in it.
Built-in builders
*****************
Each builder can take ``name`` and ``icon`` parameter. For builders that cannot generate ``name`` by themselves (by for
example taking them from model or app name), ``name`` must be specified, unless builder is used as root element
``ListBuilder``
+++++++++++++++
Builder that contains sub-elements. It's just a container, so by default, does nothing. ``name`` argument is required if
not used as root element. ``items`` argument is required and should be a list or tuple of 2-tuples defined like root
element.
``ItemBuilder``
+++++++++++++++
Builder that represents simple url. ``name`` argument is required. ``url`` argument is required. It also can take
``permissions_check`` that should be either callable or dotted path to callable that will return True or False
determining if user can see this option in menu. It should take ``request``, ``context`` and ``menu_name`` parameters.
``ModelBuilder``
++++++++++++++++
Builder that represents ``ModelAdmin``. It simply looks for ``ModelAdmin`` for specified model and puts URL to it's
changelist in menu. ``model`` is required and should be in form of ``app_name.ModelName`` or ``path_to_app.ModelName``,
there should be no ``.models`` inside path to model. ``name`` is optional, if not provided will default to model's
name. If icon is not provided, builder will try to get it from ``_menu_icon`` attribute of Model's ``Meta`` class and if
it fails, will default to one based on navigation level.
``ModelsBuilder``
+++++++++++++++++
Builder that represents all model admins from specified app. It will scan for models in specified app and put them as
sub-elements, using ``ModelBuilder`` for each of them. You can also specify ``items`` that can contain any sub-items.
Any sub-item manually specified in ``items`` will come before items automatically added from scanning app. If Model or
path to Model admin is referenced in ``items`` it will be automatically skipped later on, when creating automatic
list of app models, so every model is used only once. This is global behaviour for every URL You can also set
``models`` or ``exclude`` parameters that will limit which models should be used. They can't be used together. If
``models`` is used, only models specified in ``models`` will be used. ``models`` and ``exclude`` should be just in form
of list of model names (without app name). As for model, ``name`` is optional and if not provided, will default to
app name. Also, similarly to model, builder will try to fetch icon from ``AppConfig``'s ``_menu_icon`` attribute and
fall back to default one based on navigation level.
``AppsBuilder``
+++++++++++++++
Builder that represents all apps with their models. It will scan for apps in project and put every app as sub-item
using ``ModelsBuilder`` (which will build sub-item for every model in app). You can specify ``apps`` and ``exclude``
which works like ``models`` and ``exclude`` in ``ModelsBuilder``, but instead put app names as list (without full path).
You can also specify single models in ``apps`` and ``exclude`` together with app names. Models should be in form of
``app_name.ModelName``, models specified without app name will be treated like apps and may result in unexpected
behaviour. ``name`` is required if item is not used as root item, because there is no place from which we can get
default name. ``icon`` may be customized like in other items, but there is no special place for defining it.
Icons
*****
You can use any icon from font awesome icons in menu, just by providing it's name. Version 4.6.2 is embedded, if you
need newer one, just edit base template and put there your own version (or replace font awesome files in staticfiles,
that works too). Icon can be defined in every builder, using ``icon`` argument (icon for root element will be ignored,
for obvious reasons) or in case of models and apps (and using ``ModelBuilder``, ``ModelsBuilder`` or ``AppsBuilder``),
you can set default icon accordingly in models ``Meta`` or in apps ``AppConfig`` using ``_menu_icon`` attribute. If no
icon is defined for particular item, it defaults to icon based on navigation level (``angle-right`` for 1st level,
``angle-double-right`` for 2nd level and no icon for 3rd level).
Smart Breadcrumbs
-----------------
This module gives you ability to rewrite default admin breadcrumbs to match structure defined with admin menu.
Generation of smart breadcrumbs requires ``beautifulsoup4`` library, which you can install by installing
``django-admin-toolbox[smart-breadcrumbs]``.
You can enable or disable this feature, by using ``'breadcrumbs'`` in settings dict. Allowed values are:
- ``None`` - Disables breadcrumbs alltogether. This option will hide default breadcrumbs generated by Django.
- ``'auto'`` - Breadcrumbs will be automatically enabled if ``beautifulsoup4`` is available. Otherwise, default django
admin breadcrumbs will be used.
- ``'auto-smart'`` - Breadcrumbs will be automatically enabled if ``beautifulsoup4`` is available. Otherwise, no
breadcrumbs will be used.
- ``'smart'`` - Breadcrumbs will be explicitly enabled. This option will trigger exception if ``beautifulsoup4`` is not
installed
- ``'force-smart'`` - Similar to ``'smart'``, but breadcrumbs will be also visible on pages, where they don't exist
in default django admin.
Raw data
{
"_id": null,
"home_page": "https://github.com/gbdlin/django-admin-toolbox",
"name": "django-admin-toolbox",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, <4",
"maintainer_email": "",
"keywords": "django admin toolbox sidebar tools improvements",
"author": "GwynBleidD",
"author_email": "gbd.lin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f9/b6/cdec52ab131d1f06f748ad1c84b58d77fde73e8b074ed193237c8c2395d0/django-admin-toolbox-1.0.0.dev29.tar.gz",
"platform": null,
"description": "======================\n Django Admin Toolbox\n======================\n\nThis package provides bunch of useful tools for default django admin site, such as:\n\n- `Sidebar`_\n- `Smart breadcrumbs`_\n\nAll configuration is held in ``ADMIN_TOOLBOX`` dict that should be placed in your ``settings.py`` file.\n\n\n.. warning:: This package is still in development and all API is considered unstable. This means that anything may\n change without notice and without backwards compatibility!\n\nInstallation\n============\n\n1. Install admin toolbox (if not installed already)\n2. add ``admin_toolbox`` at the top of your ``INSTALLED_APPS`` (at least above ``django.contrib.admin``)\n\nConfiguration\n=============\n\nAll configuration of this application is held in one dictionary in django settings, named ``ADMIN_TOOLBOX``. Below you\ncan see default configuration:\n\n.. code-block:: python\n\n ADMIN_TOOLBOX = {\n 'sidebar': {\n 'default': ('admin_toolbox.builders.AppsListBuilder', {}),\n },\n 'breadcrumbs': 'auto',\n }\n\nIf you want to customize any setting, you don't have to copy whole defaults. Anything that is not set, will be filled\nin with default values.\n\nBelow you can find description of how to configure each module.\n\nSidebar\n-------\n\nThis module adds sidebar to the left of standard django admin template. This module cannot be disabled for now, as other\nmodules depend on it's configuration. Purpose of this sidebar is to replace default list of models in django admin with\nsomething more customizable and useful.\n\nBy default, sidebar will just contain categories for all apps with models inside of them, which just corresponds to\nlist of apps and models on standard django admin dashboard. But you can customize that menu using builders.\n\n``sidebar`` element inside ``ADMIN_TOOLBOX`` settings contains all defined menus (like for ``DATABASES``, you can\nspecify more than one menu). For now, only ``default`` menu is used, other ones will be ignored. Each menu consists of\nroot element. Each element is specified by tuple containing string and dictionary. String should be valid python dot\npath to builder class, dictionary contains all default arguments that will be passed to that class when initializing.\n\nEach builder is one of ``ListBuilder`` or ``ItemBuilder`` from ``admin_toolbox.builders`` module or any subclass\nof them. For root element, only ``ListBuilder`` and it's subclasses are allowed.\n\nRoot element of each menu is a container for whole menu, but it's logic is still invoked, but it won't be rendered as\na whole, only it's sub-items will be. How to nest items is explained below.\n\nAlso, each element, except of root one, should have specified name (if specified builder cannot generate it\nautomatically).\n\nThere is default limit for nesting set to 3 levels. It is enforced on template level, so if you want to create menu\nwith more nested levels, simply overwrite template (and probably CSS) and implement displaying more than 3 levels in it.\n\nBuilt-in builders\n*****************\n\nEach builder can take ``name`` and ``icon`` parameter. For builders that cannot generate ``name`` by themselves (by for\nexample taking them from model or app name), ``name`` must be specified, unless builder is used as root element\n\n``ListBuilder``\n+++++++++++++++\n\nBuilder that contains sub-elements. It's just a container, so by default, does nothing. ``name`` argument is required if\nnot used as root element. ``items`` argument is required and should be a list or tuple of 2-tuples defined like root\nelement.\n\n``ItemBuilder``\n+++++++++++++++\n\nBuilder that represents simple url. ``name`` argument is required. ``url`` argument is required. It also can take\n``permissions_check`` that should be either callable or dotted path to callable that will return True or False\ndetermining if user can see this option in menu. It should take ``request``, ``context`` and ``menu_name`` parameters.\n\n``ModelBuilder``\n++++++++++++++++\n\nBuilder that represents ``ModelAdmin``. It simply looks for ``ModelAdmin`` for specified model and puts URL to it's\nchangelist in menu. ``model`` is required and should be in form of ``app_name.ModelName`` or ``path_to_app.ModelName``,\nthere should be no ``.models`` inside path to model. ``name`` is optional, if not provided will default to model's\nname. If icon is not provided, builder will try to get it from ``_menu_icon`` attribute of Model's ``Meta`` class and if\nit fails, will default to one based on navigation level.\n\n``ModelsBuilder``\n+++++++++++++++++\n\nBuilder that represents all model admins from specified app. It will scan for models in specified app and put them as\nsub-elements, using ``ModelBuilder`` for each of them. You can also specify ``items`` that can contain any sub-items.\nAny sub-item manually specified in ``items`` will come before items automatically added from scanning app. If Model or\npath to Model admin is referenced in ``items`` it will be automatically skipped later on, when creating automatic\nlist of app models, so every model is used only once. This is global behaviour for every URL You can also set\n``models`` or ``exclude`` parameters that will limit which models should be used. They can't be used together. If\n``models`` is used, only models specified in ``models`` will be used. ``models`` and ``exclude`` should be just in form\nof list of model names (without app name). As for model, ``name`` is optional and if not provided, will default to\napp name. Also, similarly to model, builder will try to fetch icon from ``AppConfig``'s ``_menu_icon`` attribute and\nfall back to default one based on navigation level.\n\n``AppsBuilder``\n+++++++++++++++\n\nBuilder that represents all apps with their models. It will scan for apps in project and put every app as sub-item\nusing ``ModelsBuilder`` (which will build sub-item for every model in app). You can specify ``apps`` and ``exclude``\nwhich works like ``models`` and ``exclude`` in ``ModelsBuilder``, but instead put app names as list (without full path).\nYou can also specify single models in ``apps`` and ``exclude`` together with app names. Models should be in form of\n``app_name.ModelName``, models specified without app name will be treated like apps and may result in unexpected\nbehaviour. ``name`` is required if item is not used as root item, because there is no place from which we can get\ndefault name. ``icon`` may be customized like in other items, but there is no special place for defining it.\n\nIcons\n*****\n\nYou can use any icon from font awesome icons in menu, just by providing it's name. Version 4.6.2 is embedded, if you\nneed newer one, just edit base template and put there your own version (or replace font awesome files in staticfiles,\nthat works too). Icon can be defined in every builder, using ``icon`` argument (icon for root element will be ignored,\nfor obvious reasons) or in case of models and apps (and using ``ModelBuilder``, ``ModelsBuilder`` or ``AppsBuilder``),\nyou can set default icon accordingly in models ``Meta`` or in apps ``AppConfig`` using ``_menu_icon`` attribute. If no\nicon is defined for particular item, it defaults to icon based on navigation level (``angle-right`` for 1st level,\n``angle-double-right`` for 2nd level and no icon for 3rd level).\n\nSmart Breadcrumbs\n-----------------\n\nThis module gives you ability to rewrite default admin breadcrumbs to match structure defined with admin menu.\nGeneration of smart breadcrumbs requires ``beautifulsoup4`` library, which you can install by installing\n``django-admin-toolbox[smart-breadcrumbs]``.\n\nYou can enable or disable this feature, by using ``'breadcrumbs'`` in settings dict. Allowed values are:\n\n- ``None`` - Disables breadcrumbs alltogether. This option will hide default breadcrumbs generated by Django.\n- ``'auto'`` - Breadcrumbs will be automatically enabled if ``beautifulsoup4`` is available. Otherwise, default django\n admin breadcrumbs will be used.\n- ``'auto-smart'`` - Breadcrumbs will be automatically enabled if ``beautifulsoup4`` is available. Otherwise, no\n breadcrumbs will be used.\n- ``'smart'`` - Breadcrumbs will be explicitly enabled. This option will trigger exception if ``beautifulsoup4`` is not\n installed\n- ``'force-smart'`` - Similar to ``'smart'``, but breadcrumbs will be also visible on pages, where they don't exist\n in default django admin.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django admin toolbox - bunch of improvements for default django admin",
"version": "1.0.0.dev29",
"project_urls": {
"Homepage": "https://github.com/gbdlin/django-admin-toolbox"
},
"split_keywords": [
"django",
"admin",
"toolbox",
"sidebar",
"tools",
"improvements"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cf755c13f175f36af6781c4a7894f846a8ef84767970fd75f182bebd78308628",
"md5": "80875f19e9192f3b7bde96ad6cbd7ed1",
"sha256": "3943fefff3ac29f74227245dbade51b941c0995c7c2ef37a7834faaffa672b31"
},
"downloads": -1,
"filename": "django_admin_toolbox-1.0.0.dev29-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "80875f19e9192f3b7bde96ad6cbd7ed1",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, <4",
"size": 1754645,
"upload_time": "2023-09-24T14:02:19",
"upload_time_iso_8601": "2023-09-24T14:02:19.653751Z",
"url": "https://files.pythonhosted.org/packages/cf/75/5c13f175f36af6781c4a7894f846a8ef84767970fd75f182bebd78308628/django_admin_toolbox-1.0.0.dev29-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f9b6cdec52ab131d1f06f748ad1c84b58d77fde73e8b074ed193237c8c2395d0",
"md5": "b61f987d5d59f3fb8aa2e85dd00ee4bb",
"sha256": "82092fe6b5e80e273e1abbfc6618c9c13c2fd471487fc24c976cf8781d4f0992"
},
"downloads": -1,
"filename": "django-admin-toolbox-1.0.0.dev29.tar.gz",
"has_sig": false,
"md5_digest": "b61f987d5d59f3fb8aa2e85dd00ee4bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, <4",
"size": 1756760,
"upload_time": "2023-09-24T14:02:22",
"upload_time_iso_8601": "2023-09-24T14:02:22.521945Z",
"url": "https://files.pythonhosted.org/packages/f9/b6/cdec52ab131d1f06f748ad1c84b58d77fde73e8b074ed193237c8c2395d0/django-admin-toolbox-1.0.0.dev29.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-24 14:02:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gbdlin",
"github_project": "django-admin-toolbox",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-admin-toolbox"
}
JSON
