Skip to content

Latest commit

 

History

History
303 lines (244 loc) · 11.4 KB

README.md

File metadata and controls

303 lines (244 loc) · 11.4 KB
Raw

Django-AdminLTE2-PDQ

Documentation Status PyPI Python Versions Django Versions GitHub PyPI Downloads per Month

Django-AdminLTE2-PDQ is a Django app that takes all of the work out of making a beautiful and functional web application pretty darn quickly (PDQ) using the AdminLTE2 theme.

Additionally, the app provides decorators, mixins, template filters, and template tags to aid in the rapid development of a site.

Features include:

  • Styled with AdminLTE2.
  • Easy sidebar menu creation.
  • Automatic Django Admin styling that matches AdminLTE2.
  • Automatic inclusion of Admin links in the sidebar.
  • Automatic menu link hiding based on user permissions to views.
  • Template filters to aid in manual styling.
  • Template tags for form rendering that matches AdminLTE2.
  • Automatic form error and message styling.
  • Font Awesome 4 & Font Awesome 5 integration.
  • Highly configurable functionality, via project Django settings variables.

The full documentation can be found on Read The Docs.

django-adminlte2-pdq-static-menu

Quickstart

  1. Install the Django App via GitHub for now. Working on getting on Pypi soon.

    python -m pip install django-adminlte2-pdq

  2. Add "adminlte2_pdq" to your INSTALLED_APPS setting like this:

    INSTALLED_APPS = [
    'adminlte2_pdq',
    ...
]

    ℹ️ NOTE The adminlte2_pdq app should be listed before any Django apps so that template overriding works correctly. Additionally, if you plan to override any Django-AdminLTE2-PDQ templates, the apps containing those templates should be listed above the adminlte2_pdq app.

  3. Django-AdminLTE2-PDQ provides a middleware that is required for some of the available authentication and authorization scenarios from this package to function.

    Add this middleware to your middleware list in settings.py.

    Once installed the available scenarios are controlled by changing settings in your settings.py file. For more information about the various scenarios and associated settings refer to the full documentation on Read The Docs.

       MIDDLEWARE = [
       ...
       'adminlte2_pdq.middleware.AuthMiddleware',
   ]

    ℹ️ NOTE Django-AdminLTE2-PDQ has been configured out of the box to get you set up and running as fast as possible. As a result, the settings surrounding authentication and authorization are not as strict as they could be. We strongly encourage you to read the Authentication and Authorization section on Read The Docs once you get the basics of this package working.

  4. Django-AdminLTE2-PDQ provides routes and templates for a home page, some sample pages, and Django's account pages. You can add these default routes to your URLconf if you would like to use them.

    ℹ️ NOTE Using the included routes and templates requires that your urlpatterns has both the routes from the package added as well as the accounts routes provided by Django. See sample code below.

    ⚠️ WARNING Opting not to use these default routes requires that you configure the ADMINLTE2_HOME_ROUTE setting, as some parts of the default template expect that your site has at minimum, a home page, defined in that setting.

    from django.contrib import admin
from django.urls import include

urlpatterns = [
    # Adminlte2 default routes for demo purposes
    path('', include('adminlte2_pdq.urls')),
    # Django Account Routes - Styled in AdminLTE2
    path('accounts/', include('django.contrib.auth.urls')),
    # Admin - Styled in Django but hosted in AdminLTE2 layout
    path('admin/', admin.site.urls),
]

  5. Ensure that the login redirect will work.

    LOGIN_REDIRECT_URL = 'adminlte2_pdq:home'

    ℹ️ NOTE Django-AdminLTE2-PDQ does not include a route or templates for /accounts/profile which is the default Django Login redirect. Adding the above entry to your settings.py file will allow successful logins to redirect to the default provided home page included in step 4. At least until a proper profile route can be set up.

    ⚠️ WARNING If you are not using the default urls from step 4, we assume that you already know where you would like to have users redirected to on successful login and thus have already done this step with a different value.

  6. Update settings.py to customize the look and feel of Django-AdminLTE2-PDQ. Common configuration options are listed below in the configuration section.

    For the full list of configuration options refer to the documentation on Read The Docs.

  7. Override templates to further customize the look and feel of Django-AdminLTE2-PDQ.

    See the Templates section on Read The Docs for more information.

Configuration

Home

Set the "Home" route for your project. This tells the package where to redirect users when they click a link that is designed to take the user home.

ADMINLTE2_HOME_ROUTE = 'adminlte2_pdq:home'

Set the Logo text for your site. This will be shown in the top left of the top bar when the sidebar is expanded.

ADMINLTE2_LOGO_TEXT = 'My Awesome Site'

Set the small Logo text for your site. This will be shown in the top left of the top bar when the sidebar is collapsed.

ADMINLTE2_LOGO_TEXT_SMALL = 'MAS'

Set the skin class to use for the site. Valid skin classes can be found on the AdminLTE documentation page.

ADMINLTE2_SKIN_CLASS = 'skin-green-light'

Menu

By default, the main navigation (non-admin) menu is not part of the sidebar when the user is viewing a Django Admin page If you would like users to be able to see all of the main nav links regardless of what page they are on, set this value to True.

ADMINLTE2_INCLUDE_MAIN_NAV_ON_ADMIN_PAGES = (True/False)

By default, the admin navigation menu is not part of the sidebar when the user is viewing a main navigation (non-Django-Admin) page. If you would like users to be able to see all of the admin nav links regardless of what page they are on, set this value to True.

ADMINLTE2_INCLUDE_ADMIN_NAV_ON_MAIN_PAGES = (True/False)

By default, there will be an implicit separator bar rendered between each menu group. These groups include: MENU_FIRST, MENU, MENU_LAST, and the Admin Menu. More information about these groups can be found on the Read The Docs Admin page. If you would like to disable this separator from being automatically rendered, set this value to False.

ADMINLTE2_USE_MENU_GROUP_SEPARATOR = (True/False)

This setting is the definition for the main navigation menu. There are a lot of options when creating this menu. See the Read The Docs Menu page for a detailed explanation of how to create this menu and all of the available options that can be used.

ADMINLTE2_MENU = []

Admin

By default, the admin menu sidebar will not have a link to the admin index page. If you would like to append a link to the admin index page in the sidebar, set this value to True.

ADMINLTE2_INCLUDE_ADMIN_HOME_LINK = (True/False)

By default, Django-AdminLTE2-PDQ will put the Apps on the Admin Index page into AdminLTE Info Boxes. Setting this to True will change that look to the traditional Django list view, but still within the main AdminLTE site styling.

ADMINLTE2_ADMIN_INDEX_USE_APP_LIST = (True/False)

Authorization

Whether all routes will require that users are logged in to access unless the route is added to a Whitelist.

If this setting is set to False, then all routes will be accessible and still visible on the sidebar menu.

If this setting is set to True, then all routes will not be accessible nor will there be links on the sidebar menu unless the user is logged in or the route is found in the ADMINLTE2_LOGIN_EXEMPT_WHITELIST setting.

ADMINLTE2_USE_LOGIN_REQUIRED = (True/False)

Assuming ADMINLTE2_USE_LOGIN_REQUIRED is set to True, this is the list of routes that will be shown on the sidebar menu and accessible, despite a user not being logged in.

ℹ️ NOTE Even though the default value for this list is an empty list, the underlying functionality that this setting is used in has some included routes. They can be seen in the full Documentation. The routes defined in this setting will be appended to that default list.

ADMINLTE2_LOGIN_EXEMPT_WHITELIST = []

Whether routes with no defined permission should be hidden unless added to a Whitelist.

If this setting is set to False, then all routes without defined permissions are still visible on the sidebar menu.

If this setting is set to True, then all routes without defined permissions are hidden on the sidebar menu unless the route is found in the ADMINLTE2_STRICT_POLICY_WHITELIST setting.

ADMINLTE2_USE_STRICT_POLICY = (True/False)

Assuming ADMINLTE2_USE_STRICT_POLICY is set to True, this is the list of routes that will be shown on the sidebar menu and accessible, despite said routes having no defined permission.

ADMINLTE2_STRICT_POLICY_WHITELIST = []