CMS后端【免费下载链接】django-cmsThe easy-to-use and developer-friendly enterprise CMS powered by Django项目地址https://gitcode.com/gh_mirrors/dj/django-cms点击查看免费下载django CMS 在cms.admin.utils、cms.utils.page、cms.utils.placeholder与cms.utils.plugins四个模块中沉淀了一套供核心代码与第三方扩展包复用的工具函数集合。本文以官方参考文档 docs/reference/utility-functions.rst 为骨架逐一对这些工具函数进行源码级剖析并结合测试用例说明其行为与适用场景。读完本文你将掌握如何在自定义 Admin 中接入操作按钮Action Buttons、搭建 Grouper 模型管理后台以及如何通过 Placeholder 与 Plugin 工具函数在模板渲染、插件复制、权限限制等场景中写出与 django CMS 核心一致的高质量扩展代码。工具函数在 django CMS 中的角色django CMS 的工具函数并不是一个独立的模块而是分散在若干按职责划分的子包中。它们的特点是被 django CMS 核心自身高频调用同时以公开 API 的形式开放给第三方包。参考文档 docs/reference/utility-functions.rst 将其归纳为四组子包模块主要职责Model admincms.admin.utilsAdmin 变更列表操作按钮、Grouper 管理后台Pagescms.utils.page从请求中解析当前页面对象Placeholderscms.utils.placeholderPlaceholder 声明与实例解析Pluginscms.utils.plugins插件查询、树形化、降类型转换、复制与数量限制理解这些工具函数的最佳方式是阅读它们的源码因为其中包含大量针对性能与边界情况的工程化处理如查询缓存、批量下转换、孤儿插件修复等这些都是官方文档中不会展开的细节。Model Admin 工具让后台管理更贴近 CMS 业务cms.admin.utils模块是 django CMS 对 Django 自带django.contrib.admin的增强层它解决了 CMS 后台的两个典型痛点单行级快捷操作与**grouper-content 结构的管理**。ChangeListActionsMixin为变更列表添加行级操作按钮类定义位于 cms/admin/utils.py。与 Django 内置的批量 action 不同ChangeListActionsMixin提供的按钮每次只作用于一行数据常用于预览、设置这类针对单个对象的操作。要启用该功能需要两步在 Admin 类的list_display中加入占位符字符串admin_list_actions让 Admin 类继承ChangeListActionsMixin可直接继承也可通过GrouperModelAdmin间接获得。源码中get_list_display()会将admin_list_actions占位符替换为get_admin_list_actions()生成的列方法def get_list_display(self, request): list_display super().get_list_display(request) return tuple( self.get_admin_list_actions(request) if item admin_list_actions else item for item in list_display )注意占位符的失效保护如果list_display中写了admin_list_actions却没有混入该 Mixinadmin_list_actions()会抛出ValueError提示开发者ChangeListActionsMixin未加载——这是避免静默出错的贴心设计见 cms/admin/utils.py。注册自定义按钮需要实现两个方法get_actions_list()返回当前 Admin 实例的方法列表每个方法接收(obj, request)并返回按钮 HTML 字符串。重写时必须调用super()以保留 Mixin 自身的动作class MyModelAdmin(ChangeListActionsMixin, admin.ModelAdmin): def get_actions_list(self): return super().get_actions_list() [ self.my_first_action, self.my_second_action, ]admin_action_button()这是一个staticmethod用于生成符合 django CMS 前端样式的按钮其参数完整说明如下见 cms/admin/utils.py参数类型说明urlstr动作目标 URL通常由cms.utils.urlutils.admin_reverse生成iconstr按钮图标名如info、view、settingstitlestr人类可读的动作描述burger_menubool为True时该项进入所有按钮右侧的汉堡菜单actionstrget或post定义 URL 使用的 HTTP 方法部分 URL 需要 POSTdisabledbool为True时按钮置灰不可点击keepsideframebool为False时若侧边栏打开执行动作前会先关闭它namestr追加到按钮 class 中形成cms-action-{{ name }}便于样式定位一个典型用法源码 docstring 中的模式def my_custom_button(self, obj, request, disabledFalse): # 准备工作检查权限、计算 URL 等 url admin_reverse(..., args[obj.pk]) if permissions_ok: return self.admin_action_button( url, info, _(View usage), disableddisabled ) return # 无按钮按钮的 HTML 由模板 cms/templates/admin/cms/icons/base.html 渲染前端逻辑与样式分别位于cms/js/admin/actions.js与cms/css/cms.admin.css在Media类中声明见 cms/admin/utils.py。GrouperModelAdmin一站式管理 Grouper 与 Content 模型GrouperModelAdmin是 django CMS 4.x 引入的核心管理后台模式参见 docs/how_to/16-grouper-admin.rst。它建立在grouper-content 结构之上grouper 模型保存与语言无关的字段如页面在树中的位置、权限content 模型保存语言相关的内容。django CMS 自身的Page-PageContent就是这一模式的范例。类定义于 cms/admin/utils.py继承自ChangeListActionsMixin与ModelAdmin。使用它只需要注册 grouper 模型的管理类content 模型无需单独注册 Adminfrom cms.admin.utils import GrouperModelAdmin class MyGrouperAdmin(GrouperModelAdmin): # 声明 content 模型 content_model MyContent # 为新增/编辑视图添加语言选项卡 extra_grouping_fields (language,) # 变更列表同时展示 grouper 与 content 字段并追加操作列 list_display ( field_in_grouper_model, content__field_in_content_model, admin_list_actions, )关键类属性与自动推断规则GrouperModelAdmin通过少量类属性即可工作其余全部自动推断见 cms/admin/utils.py类属性默认推断逻辑grouper_field_namecontent 模型中指向 grouper 的外键名未指定时取 grouper 模型的蛇形命名如BlogPost→blog_postextra_grouping_fields空元组。content 模型按这些字段分组如(language,)会生成变更列表下拉与表单选项卡content_model未指定时按grouper 类名 Content在同一 app 中查找如BlogPost→BlogPostContentcontent_related_field未指定时取第一个指向 content 模型的反向关系字段名若存在多个反向关系如多对多相关文章必须显式指定注意所有作为extra_grouping_fields的字段必须出现在 Admin 的fieldsets中否则GrouperModelAdmin无法正常工作在变更表单中这些字段会以隐藏域形式呈现。__init__中还做了几件自动化工作为 content 模型挂载admin_manager若缺失、为每个 content 模型字段自动生成content__{field_name}的 getter 方法用于list_display、以及在未提供自定义表单时自动生成GrouperAdminFormMixin包装的表单类见 cms/admin/utils.py。变更列表视图的增强content 字段展示list_display中可混用 grouper 字段与content__xxx形式的内容字段。后者通过子查询Subquery标注annotate到 grouper 查询集上支持排序字符字段还会生成小写副本__lc以实现不区分大小写的排序日期字段在 MySQL 上会显式Cast以保证类型正确见 cms/admin/utils.py。语言选择器当extra_grouping_fields含language时变更列表模板 cms/templates/admin/cms/grouper/change_list.html 会渲染语言下拉框由cms/js/admin/language-selector.js驱动切换。内置操作按钮只要list_display包含admin_list_actions每一行会自动获得两个按钮——前端编辑器预览按钮_get_view_action与设置按钮_get_settings_action无内容时显示为添加内容。这两个动作在get_actions_list()中注册见 cms/admin/utils.py。变更表单的合并保存GrouperModelAdmin的变更表单同时承载 grouper 与 content 字段表单 mixin_GrouperAdminFormMixin负责初始化、语言标签后缀如Title (en)与分组字段校验见 cms/admin/utils.py。保存逻辑save_model()会先保存 grouper再根据情况创建或更新 content 实例若 content 模型管理器支持with_user还会记录操作者见 cms/admin/utils.py。内容只读控制与版本化兼容get_readonly_fields()委托给can_change_content()当用户缺少权限或 content 对象的is_editable返回假值时所有 content 字段变为只读见 cms/admin/utils.py。is_editable可返回携带失败原因的 rich bool如 djangocms-versioning这些原因会通过get_content_readonly_message()呈现给用户。这保证了 Grouper 后台可以与 djangocms-versioning 之类的版本化扩展无缝协作。页面工具从请求解析当前页面cms.utils.page模块中最核心的函数是get_page_from_request()定义于 cms/utils/page.py其作用是根据HttpRequest解析出当前请求对应的Page对象。URL 结构约定如下源码 docstringhttp://server.whatever.com/some_path/pages-root/some/page/slugsome_pathCMS 未安装在站点根目录时的前缀解析时会剥离pages-rootCMS 的 Django URL 根空 slug末尾的 slug 最终解析为Page模型实例。工作流程结合源码若request上已有_current_page_cache由CurrentPageMiddleware设置直接返回避免重复查询clean_path参数控制是否剥离pages-root前缀与末尾斜杠默认在未提供use_path时开启解析pages-root失败NoReverseMatch时静默跳过通过PageUrl.objects.get_for_site(site).filter(pathpath)查询select_related(page, page__site)预取关联并用list()强制求值以减少一次数据库往返命中后若首条记录语言与请求语言一致还会构建page.urls_cache供后续多语言 URL 解析复用未命中返回None。测试覆盖了无页面、404 页面等场景参见 cms/tests/test_page.py。同模块的get_page_template_from_request()cms/utils/page.py则负责从CMS_TEMPLATES与请求参数中解析当前模板含单模板短路与无模板headless分支。Placeholder 工具声明与实例的双向解析cms.utils.placeholder模块围绕{% placeholder %}模板标签对应的DeclaredPlaceholder与数据库中的Placeholder实例展开。get_declared_placeholders_for_obj读取对象声明的占位符函数定义于 cms/utils/placeholder.py。它接收一个模型对象并返回其声明的占位符列表解析顺序为若对象有get_template()方法则编译模板并通过get_placeholders()扫描其中的{% placeholder %}标签否则若对象有get_placeholder_slots()方法将返回的 slot 列表包装成DeclaredPlaceholder两者皆无则抛出NotImplementedError。模板扫描由_scan_placeholders()递归完成cms/utils/placeholder.py它需要处理{% include %}、{% extends %}、{{ block.super }}、嵌套BlockNode等复杂情况。get_placeholders()在生产环境DEBUGFalse下会缓存扫描结果模板改动在开发环境即时生效见 cms/utils/placeholder.py。get_placeholder_from_slot获取或创建占位符实例函数定义于 cms/utils/placeholder.py签名如下get_placeholder_from_slot(placeholder_relation, slot, template_objNone, default_widthNone)它按template_obj是否具备get_template()分支处理具备模板的对象先尝试placeholder_relation.get(slotslot)若Placeholder.DoesNotExist则调用rescan_placeholders_for_obj()重扫模板并为缺失 slot 批量创建Placeholder记录bulk_createMySQL 旧版本走逐条save()回退见 cms/utils/placeholder.py无模板的对象直接get_or_create(slotslot, default_widthdefault_width)适用于通过{% render_placeholder %}渲染的场景。get_placeholder_conf()cms/utils/placeholder.py是另一重要工具用于读取CMS_PLACEHOLDER_CONF中按作用域全局None→ 模板 → slot → 模板slot逐级覆盖的配置并支持inherit继承链解析与循环继承检测。Plugin 工具查询、树形化、下转换与复制cms.utils.plugins是插件渲染与管理的发动机参考文档列出的 9 个函数几乎覆盖了插件生命周期的每个环节。类型解析get_plugin_class 与 get_plugin_model这两个函数cms/utils/plugins.py是对plugin_pool的薄封装def get_plugin_class(plugin_type): return plugin_pool.get_plugin(plugin_type) def get_plugin_model(plugin_type): return get_plugin_class(plugin_type).model前者按字符串插件类型返回CMSPluginBase子类后者返回其绑定的模型类。它们在downcast_plugins中被反复使用是插件体系的基础设施。查询与分配get_plugins 与 assign_pluginsget_plugins(request, placeholder, template, langNone)cms/utils/plugins.py获取指定占位符在指定语言下的插件列表尊重占位符的渲染缓存若placeholder已有_plugins_cache直接返回否则调用assign_plugins()填充后返回。assign_plugins()cms/utils/plugins.py是核心性能函数其策略是一次性查询所有给定占位符、指定语言的CMSPlugin记录若为空检查CMS_PLACEHOLDER_CONF的default_plugins配置并按权限创建默认插件create_default_plugins()支持嵌套 children 递归与notify_on_autoadd钩子否则调用downcast_plugins()将基类实例批量下转换为具体插件类型按占位符分组后用get_plugins_as_layered_tree()组织成树根插件存入_plugins_cache全部插件存入_all_plugins_cache。树形化get_plugins_as_layered_tree该函数cms/utils/plugins.py接收按位置排序的插件可迭代对象返回根插件deque并将子插件挂到父插件的child_plugin_instances属性上。实现上借助defaultdict(deque)延迟聚合子节点逆向遍历以保证兄弟顺序稳定。下转换downcast_plugins 与 get_bound_pluginsDjango CMS 的插件在数据库中以CMSPlugin基类 具体模型如TextPlugin的模型存储渲染时需将基类实例下转换downcast为具体类型。downcast_plugins()cms/utils/plugins.py的实现要点按具体模型_meta.concrete_model分组主键每种类型一条查询批量加载iterator(chunk_sizePLUGIN_ITERATOR_CHUNK_SIZE)流式迭代常量定义于cms/constants.py通过直接改写实例的__class__完成类型转换含代理模型跳过未安装的插件类型并记录错误日志填充parent字段缓存与placeholder属性若插件类声明cacheFalse且无过期策略则关闭占位符缓存placeholder.cache_placeholder False。get_bound_plugins()cms/utils/plugins.py是下转换的无缓存变体返回生成器且仅产出父插件有效的实例剔除父节点缺失的幽灵插件。两者都通过plugin._inst填充绑定插件缓存保证后续渲染能拿到具体实例。复制copy_plugins_to_placeholder该函数cms/utils/plugins.py在transaction.atomic事务内将插件含嵌套子插件复制到目标占位符是复制页面/占位符功能与相关测试见 cms/tests/test_plugins.py的底层支撑。签名如下copy_plugins_to_placeholder(plugins, placeholder, languageNone, root_pluginNone, start_positionsNone, plugins_are_downcastFalse)核心步骤源码 docstring 总结为每个源插件获取绑定实例必要时先get_bound_plugins找到父插件或root_plugin深拷贝源实例将pk/id置None以便新建计算新占位符中的位置按语言维护positions_by_language游标首遇某语言时基于get_next_plugin_position计算并右移已有插件位置_shift_plugin_positions保存具体插件并触发copy_relations()复制关联数据处理子先于父的孤儿插件_reunite_orphaned_placeholder_plugin_children用源父 ID 回填新父对高级插件如嵌套插件的 Text 类插件调用post_copy()完成内容修正重算各语言位置并返回新插件 ID 列表。数量限制has_reached_plugin_limit该函数cms/utils/plugins.py校验占位符的CMS_PLACEHOLDER_CONF[limits]配置签名与行为has_reached_plugin_limit(placeholder, plugin_type, language, templateNone)无limits配置时直接返回False通过一次聚合查询同时统计总数total_count与指定类型数量type_count超过limits[global]抛出PluginLimitReached该占位符已到达插件数量上限超过limits[plugin_type]抛出带插件名称与上限信息的PluginLimitReached。实战建议与调用路径速查自定义 Admin 增强优先继承GrouperModelAdmingrouper 结构或混入ChangeListActionsMixin仅需操作按钮并通过get_actions_list()admin_action_button()扩展行级操作。模板渲染扩展在自定义渲染逻辑中优先调用get_plugins/assign_plugins带缓存而非直接查询CMSPlugin.objects以复用批量下转换与默认插件创建逻辑。插件复制页面/占位符复制功能应复用copy_plugins_to_placeholder它已处理位置、孤儿插件、关联复制与post_copy钩子等全部细节。权限限制添加插件前调用has_reached_plugin_limit可保持与后台行为一致。如需进一步深入可继续阅读 docs/how_to/16-grouper-admin.rstGrouper Admin 的完整教程、docs/explanation/content_objects.rstgrouper-content 设计模式以及 grouper 模板 cms/templates/admin/cms/grouper/change_form.html 与 cms/templates/admin/cms/grouper/content_inline.html。赞分享CMS后端【免费下载链接】django-cmsThe easy-to-use and developer-friendly enterprise CMS powered by Django项目地址https://gitcode.com/gh_mirrors/dj/django-cms点击查看免费下载相关推荐django-cms 3.4.4 升级指南Page 方法与 Placeholder 工具函数的破坏性变更全解析django cms 3.4.4 升级指南Page 方法与 Placeholder 工具函数的破坏性变更全解析 本文以 django cms 官方升级文档 dCMS后端django CMS 模板标签完全指南从 placeholder 到前端编辑cms_tags 全解析django CMS 模板标签完全指南从 placeholder 到前端编辑cms_tags 全解析 django CMS 通过 cms_tags 模板标CMS后端django CMS Placeholder 完整指南模型、前端编辑与插件管理源码深度解析django CMS Placeholder 完整指南模型、前端编辑与插件管理源码深度解析 Placeholder占位符是 django CMS 内容架构CMS后端上一篇ToolJet 连接 MongoDB 数据源从连接配置到 18 种查询操作的完整指南下一篇OpenClaw 接入 Mistral 模型与 Voxtral 语音转写从 API 密钥到流式 STT 的完整配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
`：手动刷新微任务队列的原理与实战)
