Privex的Django自定义管理器

这是一个为Django Web框架设计的自定义管理视图扩展，作为一种Django AdminPlus的替代品。

尽管名称如此，本项目及我们与原始的Django AdminPlus没有任何关联，本项目也不是Django AdminPlus的1:1精确重实现 - 在某些情况下可能作为直接替换使用，但不保证一定如此。

+===================================================+
|                 © 2020 Privex Inc.                |
|               https://www.privex.io               |
+===================================================+
|                                                   |
|        Privex Django Admin Plus                   |
|        License: X11/MIT                           |
|                                                   |
|        Core Developer(s):                         |
|                                                   |
|          (+)  Chris (@someguy123) [Privex]        |
|                                                   |
+===================================================+

Privex Django Admin Plus - An extension for Django so you can add custom views to the admin panel
Copyright (c) 2020    Privex Inc. ( https://www.privex.io )

使用pip安装

我们建议至少使用Python 3.6 - 我们无法保证与旧版本的兼容性。

pip3 install privex-adminplus

快速入门

使用pip3 / pipenv从PyPi安装privex-adminplus包

# Using the standard 'pip3' package manager
pip3 install -U privex-adminplus

# Using 'pipenv' - third party package manager + virtualenv manager + interpreter version manager
pipenv install privex-adminplus

将以下内容添加到YourProject/yourapp/settings.py中的INSTALLED_APPS

在您的Django项目中打开settings.py。

从INSTALLED_APPS中移除默认的django.contrib.admin。然后添加privex.adminplus和privex.adminplus.apps.PVXAdmin到INSTALLED_APPS的START / TOP。

INSTALLED_APPS = [
    # You must delete / comment out the line for the default admin (django.contrib.admin)   
    # 'django.contrib.admin',

    # NOTE: If you are running a version of Django older than 3.1 (3.0.9, 2.2.15 etc.), then you should 
    #       add 'privex.adminplus.backports' BEFORE the 'privex.adminplus' and PVXAdmin apps.
    #       The backports app is auto-loaded if it's not in INSTALLED_APPS and adminplus detects you need it, but the
    #       auto-loading will slow down your app's startup, and may cause issues with apps that should only be loaded ONCE.

    # 'privex.adminplus.backports',

    'privex.adminplus',
    'privex.adminplus.apps.PVXAdmin',
    # ...
    'django.contrib.auth',
    'django.contrib.contenttypes',
    # ...
]   

在您的主urls.py文件中注册自定义管理

在您的项目主Django应用中（通常是包含settings.py和wsgi.py的文件夹），您需要注释掉任何之前的admin.site语句，并在定义任何URL之前添加setup_admin(admin)。

from django.contrib import admin
from django.urls import path
from privex.adminplus.admin import setup_admin

# Register Privex AdminPlus to replace the default Django admin system
# This will automatically run admin.autodiscover(), so you don't need to call both setup_admin() and admin.autodiscover() 
setup_admin(admin)

# If admin.autodiscover() shouldn't be ran yet, pass discover=False to disable running autodiscover
# setup_admin(admin, discover=False)

##### Ensure any previous admin.xxx statements are deleted / commented out to avoid conflict.
# admin.site = something
# admin.sites.site = admin.site
# admin.autodiscover()

urlpatterns = [   # Mount admin.site.urls as normal, no changes needed here
    path('admin/', admin.site.urls),
    # your app URLs...
]

关于AdminPlus Django向后兼容性的注意！

为什么您要包括包含从官方Django项目复制代码的backports模块？

虽然Django因其确保向后兼容性的努力而闻名，但Django管理面板相当复杂，并且经常有潜在的破坏性更新，例如新的模板文件、布局更改，以及使用新的Django功能，如新的模板标签。

这类更改可能导致Django Admin插件/包装/替代品（如Privex AdminPlus）停止工作，或者简单地导致如自定义页面管理面板列表无法正确渲染、自定义视图无法加载等错误。

通常，为了处理由新Django版本引起的问题回归，我们必须更新Privex AdminPlus以与新版本的Django兼容。然而，通过更新代码以支持新的Django版本，可能会破坏旧版本Django上的AdminPlus。

为了允许Privex AdminPlus支持Django的新版本，同时保留对旧版本的支持，我们包括了一个额外的Django应用：privex.adminplus.backports

backports模块是什么？

backports应用是一个Django应用，它包含从Django的新版本（如3.1、3.2或最新的开发代码）复制的回滚视图、管理面板模板、模板标签和其他部分代码，这些代码来自官方Django管理面板代码。

通过使用包含的exampleapp项目进行轻度测试，通过运行开发服务器上的项目，然后浏览管理面板，手动测试Privex AdminPlus自定义视图以及标准的ModelAdmin视图（例如创建、编辑、查看和删除数据库对象）来测试回滚代码。

请注意，backports应用仅在“较旧”的Django版本上进行了测试，这些版本缺少最新稳定版Django至少一个必须回滚的关键功能。

我应该将backports应用添加到INSTALLED_APPS中吗？/ 如何禁用backports？

自动加载backports应用

截至Privex AdminPlus 1.0.0 - 不需要回滚即可使用AdminPlus的最旧Django框架版本是Django 3.1.0

为了使安装过程简单，并确保与从privex-adminplus < 1.0.0升级的用户兼容，privex.adminplus.apps.PVXAdmin类在其ready()方法中包含了一个Django版本检查。

如果检测到您正在运行需要回滚功能的Django版本，并且privex.adminplus.backports不在您的INSTALLED_APPS中，那么它将动态地将privex.adminplus.backports注入到INSTALLED_APPS中，并尝试触发所有INSTALLED_APPS的重新初始化，以确保加载backports。

如果您的Django应用配置为记录WARNING或更高等级的消息，您在首次启动应用时可能会在日志中看到自动加载backports应用的记录。

PrivexAdminPlusConfig.ready :: Django version is < 3.1 :: Ver is: 2.2.15
'privex.adminplus.backports' not in INSTALLED_APPS... adding to apps and re-initialising!
Re-initialising all Django Apps...
Finished re-initialising.

不要依赖backports自动加载器

尽管如果backports应用不在INSTALLED_APPS中并且adminplus检测到您需要它时，将会自动加载，但**自动加载会减慢应用的启动速度，并且可能会与应该只加载一次的应用产生问题**。

为防止与backports自动加载器相关的奇怪问题风险，如果您正在运行低于3.1.0版本（3.0.9、2.2.15等）的Django版本，那么您应该在INSTALLED_APPS中在'privex.adminplus'和PVXAdmin应用之前添加'privex.adminplus.backports'。

INSTALLED_APPS = [
    'privex.adminplus.backports',
    'privex.adminplus',
    'privex.adminplus.apps.PVXAdmin',
    # ...
]

强制禁用backports自动加载器

如果您正在运行需要我们privex.adminplus.backports Django应用的旧版Django，但您不想使用/无法使用我们的backports应用，则可以禁用backports自动加载器。

原因示例

• 由于另一个Django应用/Python包与我们的backports冲突
• 由于您已对视图/模板/类等进行自己的backports/修改，与我们的backports应用冲突。

注意：backports自动加载器仅在它尚未加载（列在INSTALLED_APPS中），并且您正在运行需要我们的backports应用才能使pvx-adminplus正常工作的旧版Django时才会加载backports。

要将AUTO_BACKPORT设置为False以强制禁用自动加载privex.adminplus.backports，请在您的项目settings.py文件中设置。

# Disable privex.adminplus's automatic loading of privex.adminplus.backports
AUTO_BACKPORT = False

INSTALLED_APPS = [
    'privex.adminplus',
    'privex.adminplus.apps.PVXAdmin',
    # ...
]

用Privex AdminPlus替换默认管理界面

首先，您需要在INSTALLED_APPS的开始处注释掉django.contrib.admin。

在注释掉的django.contrib.admin下面，您需要添加privex.adminplus以注册基本Django应用本身，然后添加privex.adminplus.apps.PVXAdmin以注册管理面板。

INSTALLED_APPS = [
    # 'django.contrib.admin',

    # NOTE: If you are running a version of Django older than 3.1 (3.0.9, 2.2.15 etc.), then you should 
    #       add 'privex.adminplus.backports' BEFORE the 'privex.adminplus' and PVXAdmin apps.
    #       The backports app is auto-loaded if it's not in INSTALLED_APPS and adminplus detects you need it, but the
    #       auto-loading will slow down your app's startup, and may cause issues with apps that should only be loaded ONCE.

    # 'privex.adminplus.backports',

    'privex.adminplus',
    'privex.adminplus.apps.PVXAdmin',
    # ...
    'django.contrib.auth',
    'django.contrib.contenttypes',
    # ...
]   

从您的urls.py文件中删除任何旧的admin.site语句

在您的项目主要Django应用（通常包含settings.py和wsgi.py的文件夹）中，您需要注释掉任何之前的admin.site语句，或者如果存在，注释掉admin.autodiscovery()。

您不需要删除admin URL挂载path('admin/', admin.site.urls)

from django.contrib import admin
from django.urls import path

#####
# Ensure any previous admin.xxx statements are comment out to avoid conflict.
#####
# admin.site = something
# admin.sites.site = admin.site
# admin.autodiscover()

urlpatterns = [
    # Mount admin.site.urls as normal, no changes needed here
    path('admin/', admin.site.urls),
    # your app URLs...
]

用法

注册标准ModelView

在您的admin.py中正常注册ModelView

from django.contrib import admin
from myapp.models import SomeModel

@admin.register(SomeModel)
class SomeModelAdmin(admin.ModelAdmin):
    pass

注册自定义管理视图

您可以使用privex.adminplus.admin.register_url注册自定义视图，包括函数式视图和类视图。您甚至不需要指定名称或URL，它可以从类/函数名称自动推断。

from privex.adminplus.admin import register_url
from django.http import HttpResponse
from django.views import View

# This would result in the url '{admin_prefix}/hello/' and the human name 'Testing Admin'
@register_url(url='hello/')
def testing_admin(request):
    return HttpResponse(b"hello world")

# This would result in the url '{admin_prefix}/another_test' and the human name 'Another Test'
@register_url()
def another_test(request):
    return HttpResponse(b"another test view")

# This would result in the url '{admin_prefix}/class_view_test' and the human name 'Class View Test'
@register_url()
class ClassViewTest(View):
    def get(self, *args, **kwargs):
        return HttpResponse(b"this is a class view")

# You can also hide views from the auto-generated custom admin views list, and you can override their "human friendly name" 
# which is shown on the custom admin views list on the admin index page::

# This would result in the url '{admin_prefix}/lorem' and the human name 'Lorem Ipsum Dolor Generator'
@register_url(human="Lorem Ipsum Dolor Generator")
def lorem(request):
    return HttpResponse(b"lorem ipsum dolor")
# This would result in the url '{admin_prefix}/some_internal_view' - and the human name doesn't matter, 
# as it's hidden - thus does not show up in the custom admin views list

@register_url(hidden=True)
def some_internal_view(request):
    return HttpResponse(b"this is an internal view, not for just browsing!")

具有多个URL和路由参数的管理视图

以下是两个示例：通过指定为列表为单个视图指定多个URL，以及通过指定为字典（字典允许您为每个URL设置静态admin:前缀名称）为多个URL指定多个URL。

from django.contrib.auth.models import User
from django.http import HttpResponse, JsonResponse, HttpRequest
from privex.adminplus.admin import register_url

# You can specify multiple URLs as a list.
# By default, all URLs other than the first one specified will be set as hidden=False - to avoid duplicate
# custom view entries in the admin panel
@register_url(['user_info/', 'user_info/<str:username>'])
def user_info(request, username=None):
    if username:
        u = User.objects.filter(username=username).first()
        return JsonResponse(dict(id=u.id, username=u.username, first_name=u.first_name, last_name=u.last_name))
    return JsonResponse(dict(error=True, message="no username in URL"))

# If you want the URLs to have stable URL names, you can pass the URLs as a dictionary of `url: name` instead,
# which will register the URLs under the given names.
# NOTE: Just like when passing a list, only the first item in the dictionary will have hidden=False
@register_url({
    'user_info/': 'user_info_index',
    'user_info/<str:username>': 'user_info_by_username'
})
def user_info(request, username=None):
    if username:
        u = User.objects.filter(username=username).first()
        return JsonResponse(dict(id=u.id, username=u.username, first_name=u.first_name, last_name=u.last_name))
    return JsonResponse(dict(error=True, message="no username in URL"))

当使用列表/字典在url中指定多个URL时，如果hide_extra为True，则只有列表/字典中的第一个URL将使用用户指定的hidden参数。其余的URL将具有hidden=True

要禁用自动隐藏“额外”URL，请像这样传递hide_extra=False

@register_url(hide_extra=False)

如果hide_params为True，则默认隐藏包含路由参数的URL（例如<str:username>），以防止在管理面板自定义视图列表中尝试反转它们的URL时产生错误。

要禁用自动隐藏包含路由参数的URL，请像这样传递hide_params=False

@register_url(hide_params=False)

包含示例应用

为了开发和测试目的，exampleapp文件夹包含一个基本的Django项目，该项目尝试使用privex-adminplus的大部分功能，以便可以在实际的Django应用程序中手动测试它们。

要使用exampleapp

git clone https://github.com/Privex/adminplus
cd adminplus
# install requirements
pip3 install -r requirements.txt

# For exampleapp to be able to resolve the 'privex/adminplus' module, you must set the PYTHONPATH
# to the base folder of the privex-adminplus project.
export PYTHONPATH="$PWD"

# Enter exampleapp and migrate the Django DB (auto-creates an sqlite3 database at exampleapp/db.sqlite3)
cd exampleapp
./manage.py migrate

# Create an admin user
./manage.py createsuperuser

# Start the dev server and then navigate to http://127.0.0.1:8000/admin
./manage.py runserver