Django CMS 项目中的占位符(Placeholder)使用指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00006/article/details/148415716

Django CMS 项目中的占位符(Placeholder)使用指南

django-cms django-cms/django-cms: 是一个基于 Django 的内容管理系统，可以用于构建多语言的 Web 应用程序和网站，提供了丰富的内容管理功能和多种插件扩展。项目地址: https://gitcode.com/gh_mirrors/dj/django-cms

什么是占位符

在Django CMS中，占位符(Placeholder)是一种特殊的模型字段，用于在模板中渲染用户可编辑的内容(插件)。简单来说，它就像一个容器，用户可以通过前端编辑器向网页添加文本、视频等各种插件内容。

占位符的核心概念

占位符本质上是一个用于存放CMSPlugin实例的容器，它不仅可以用于CMS页面，还可以在自定义应用中使用。通过PlaceholderRelationField，开发者可以在自定义模型上利用CMS插件的全部功能。

新旧版本差异

在Django CMS 4.0版本中，占位符系统有了重要改进：

工具栏现在为包含占位符的Django模型提供了预览和编辑端点
即使模型没有面向用户的视图(如django CMS Alias)，也可以包含占位符
需要将前端可编辑模型注册到django CMS
视图需要告知工具栏它们是否包含前端可编辑模型

注意：Django CMS 3.x使用不同的方式集成占位符，旧版的PlaceholderField("slot_name")需要改为4.x版本中的PlaceholderRelationField。

基础使用教程

1. 定义模型

首先需要在模型中定义PlaceholderRelationField：

from django.db import models
from django.utils.functional import cached_property
from cms.models.fields import PlaceholderRelationField
from cms.utils.placeholder import get_placeholder_from_slot

class MyModel(models.Model):
    placeholders = PlaceholderRelationField()

    @cached_property
    def my_placeholder(self):
        return get_placeholder_from_slot(self.placeholders, "slot_name")

2. 模板渲染

在模板中使用render_placeholder标签渲染占位符：

{% load cms_tags %}

{% render_placeholder mymodel_instance.my_placeholder "640" %}

render_placeholder标签参数说明：

PlaceholderField实例
可选width参数，用于上下文相关插件
可选language参数，指定渲染语言

3. 视图配置

视图需要返回request对象，并为工具栏设置对象：

from django.shortcuts import get_object_or_404, render

def render_my_model(request, obj):
    return render(
        request,
        "my_model_detail.html",
        {"object": obj},
    )

def my_model_detail(request, id):
    obj = get_object_or_404(MyModel, id=id)
    request.toolbar.set_object(obj)
    return render_my_model(request, obj)

高级功能

多语言支持

占位符和其中的插件原生支持多语言。如果还需要翻译其他字段，可以使用django-hvad：

class MultilingualExample1(TranslatableModel):
    translations = TranslatedFields(
        title=models.CharField('title', max_length=255),
        description=models.CharField('description', max_length=255),
    )
    placeholders = PlaceholderRelationField()

    @cached_property
    def my_placeholder(self):
        return get_placeholder_from_slot(self.placeholders, "slot_name")

结构模板

为了让前端编辑器知道模型包含哪些占位符，需要创建一个结构模板：

{% load cms_tags %}
{% placeholder "slot_name" %}

然后在模型中指定这个模板：

class MyModel(models.Model):
    def get_template(self):
        return "my_app/my_model_structure.html"

注册前端编辑

在应用的cms_config.py中注册模型：

from cms.app_base import CMSAppConfig
from . import models, views

class MyAppConfig(CMSAppConfig):
    cms_enabled = True
    cms_toolbar_enabled_models = [(models.MyModel, views.render_my_model)]