模板开发

开发说明：

主题结构

templates/themes/
└── 主题目录名/
    ├── int.py          # DjacoreCMS 应用包必用
    ├── theme.jpg           # 主题预览图
    ├── static              # 静态文件
    ├── templates           # 模板文件
    ├── templatetags        # 主题预览图
    ├── themeconfig.json    # 主题元信息文件
    └── themesettings.json  # 个性设置文件

themeconfig.json

自0.2.5版本后我们移除了对themeconfig.ini的使用，改为使用themeconfig.json使用

现在themeconfig.json文件如下：

 {
    "name": "默认主题",
    "author": "djacore CMS官方",
    "version": "1.0.0",
    "description": "系统默认主题样式,推荐非标签数据单表在30万左右以下使用。本主题具备容灾作用，此主题会不定时更新，修改请尽量不要在这个主题修改，可复制后修改使用。",
    "main": "这里为具体说明，支持html"
}

main这里是支持html的，但是JSON格式有要求，我们需要将“"”替换为“\"”,并且压缩到一行当中。

themesettings.json

我们还在0.2.5版本后加入了themesettings.json的使用，这样在主题管理中我们可以使用主题相关的个性设置

themesettings.json

{
  "settings": [
    {
      "name": "primarycolor",
      "label": "主色调",
      "type": "color",
      "default": "#007bff",
      "description": "网站的主要颜色，用于按钮、链接等",
      "required": true,
      "maxlength": 7
    },
    {
      "name": "backgroundimage",
      "label": "背景图片",
      "type": "image",
      "default": "",
      "description": "上传或输入图片URL",
      "required": false
    },
    {
      "name": "fontfamily",
      "label": "字体家族",
      "type": "select",
      "options": [
        {"value": "Arial, sans-serif", "label": "Arial"},
        {"value": "'Microsoft YaHei', sans-serif", "label": "微软雅黑"},
        {"value": "'SimSun', serif", "label": "宋体"}
      ],
      "default": "Arial, sans-serif",
      "description": "网站默认字体",
      "required": true
    },
    {
      "name": "showbreadcrumb",
      "label": "显示面包屑导航",
      "type": "checkbox",
      "default": true,
      "description": "是否显示页面面包屑导航"
    },
    {
      "name": "maxposts",
      "label": "每页文章数",
      "type": "number",
      "default": 20,
      "min": 1,
      "max": 50,
      "step": 1,
      "description": "列表页每页显示的文章数量",
      "required": true
    },
    {
      "name": "sitedescription",
      "label": "网站描述",
      "type": "text",
      "default": "",
      "description": "网站的简短描述，用于SEO",
      "required": false,
      "maxlength": 255
    },
    {
      "name": "siteemail",
      "label": "管理员邮箱",
      "type": "email",
      "default": "admin@example.com",
      "description": "网站管理员的联系邮箱",
      "required": true
    },
    {
      "name": "siteurl",
      "label": "网站URL",
      "type": "url",
      "default": "https://example.com",
      "description": "网站的完整URL",
      "required": true
    },
    {
      "name": "publishdate",
      "label": "发布日期",
      "type": "date",
      "default": "2023-01-01",
      "description": "内容发布日期",
      "required": false
    },
    {
      "name": "enablecomments",
      "label": "启用评论",
      "type": "boolean",
      "default": true,
      "description": "是否启用评论功能"
    },
    {
      "name": "contenttype",
      "label": "内容类型",
      "type": "radio",
      "options": [
        {"value": "blog", "label": "博客文章"},
        {"value": "news", "label": "新闻资讯"},
        {"value": "tutorial", "label": "教程指南"}
      ],
      "default": "blog",
      "description": "选择内容类型"
    },
    {
      "name": "tags",
      "label": "内容标签",
      "type": "multiple",
      "options": [
        {"value": "tech", "label": "技术"},
        {"value": "design", "label": "设计"},
        {"value": "business", "label": "商业"}
      ],
      "default": ["tech"],
      "description": "选择相关内容标签（可多选）"
    },
    {
      "name": "priority",
      "label": "优先级",
      "type": "range",
      "default": 5,
      "min": 1,
      "max": 10,
      "step": 1,
      "description": "设置内容优先级（1-10）"
    }
  ]
}

表单字段与 JSON 类型对应关系

JSON 类型	Django 表单字段	说明	常用参数
`color`	`forms.CharField`	颜色选择	`maxlength=7`, `widget=forms.TextInput(attrs={'type': 'color'})`
`text`	`forms.CharField`	文本输入	`maxlength`, `required`, `widget=forms.TextInput`
`email`	`forms.EmailField`	邮箱输入	`maxlength`, `required`, `widget=forms.EmailInput`
`url`	`forms.URLField`	URL输入	`maxlength`, `required`, `widget=forms.URLInput`
`number`	`forms.IntegerField`或 `forms.DecimalField`	数字输入	`minvalue`, `maxvalue`, `required`, `widget=forms.NumberInput`
`range`	`forms.IntegerField`	范围滑块	`minvalue`, `maxvalue`, `widget=forms.NumberInput(attrs={'type': 'range'})`
`select`	`forms.ChoiceField`	下拉选择	`choices`, `required`, `widget=forms.Select`
`radio`	`forms.ChoiceField`	单选按钮	`choices`, `required`, `widget=forms.RadioSelect`
`checkbox`	`forms.BooleanField`	单个复选框	`required=False`, `widget=forms.CheckboxInput`
`boolean`	`forms.BooleanField`	开关按钮	`required=False`, `widget=forms.CheckboxInput(attrs={'class': 'form-check-input'})`
`multiple`	`forms.MultipleChoiceField`	多选框	`choices`, `required`, `widget=forms.CheckboxSelectMultiple`
`date`	`forms.DateField`	日期选择	`required`, `widget=forms.DateInput(attrs={'type': 'date'})`
`image`	`forms.ImageField`	图片上传	`required`, `widget=forms.ClearableFileInput`

在模板开发时themesettings.json是可以为空或者是无的，并不是必要项。

我们更建议如果不需要主题个性设置则不放入themesettings.json

themesettings.json中个性变量的使用方法

以theme<json.keyname>为键在模板中直接引用
如上面的安全中的themesettings.json中的"name": "primarycolor"，我们在使用的时候可以直接在模板中使用{{themeprimarycolor}}来引入个性设置。

为了快速的开发模板，我们还准备了一个快速开发工具

主题模板创建工具说明

📋 工具简介

createtemplate 是一个 Django 管理命令，用于快速创建符合 DjacoreCMS 规范的主题模板目录结构。通过此工具，开发者可以一键生成完整的主题模板基础结构，提高开发效率。

🚀 使用方法

在命令行中执行以下命令创建新主题：

# 创建名为 "mytheme" 的主题 python manage.py createtemplate my_theme 创建名为 "dark_mode" 的主题 python manage.py createtemplate darkmode 创建带下划线的主题

python manage.py createtemplate moderntheme

💡 注意：主题名称建议使用英文、小写字母、数字和下划线，避免使用空格和特殊字符。

📁 生成的文件结构

执行命令后，会在 templates/themes/ 目录下生成完整的主题结构：

templates/themes/yourthemename/
├── init.py              # 主题模块定义，从themeconfig.json读取元信息
├── theme.jpg               # 主题预览图（占位符）
├── themeconfig.json        # 主题元信息配置文件
├── themesettings.json      # 主题个性化设置配置文件
├── README.md              # 主题开发说明文档
├── static/                # 静态资源目录
│   ├── css/              # 样式表目录
│   │   └── style.css     # 主样式文件
│   ├── js/               # JavaScript目录
│   │   └── main.js       # 主JavaScript文件
│   └── images/           # 图片资源目录
│       └── README.txt    # 图片目录说明
├── templates/             # 模板文件目录
│   ├── base.html         # 基础模板文件
│   ├── index.html        # 首页模板文件
│   └── single.html       # 单页模板文件
└── templatetags/         # 自定义模板标签目录
    └── init.py

⚙️ 配置文件说明

1. themeconfig.json - 主题元信息配置

包含主题的基本信息和元数据：

{
    "name": "主题名称",
    "author": "作者名称",
    "version": "1.0.0",
    "description": "主题描述",
    "main": "<p>HTML格式的详细说明</p>"
}

在 init.py 中会自动读取这些信息并导出为模块变量：

version - 主题版本
author - 主题作者
description - 主题描述
name - 主题名称
main - HTML详细说明

2. themesettings.json - 主题个性化设置

定义主题的可配置选项，支持多种表单字段类型：

color - 颜色选择器
text - 文本输入框
select - 下拉选择框
checkbox - 复选框
boolean - 开关按钮
number - 数字输入框
range - 范围滑块
radio - 单选按钮
multiple - 多选框
date - 日期选择器
image - 图片上传

🎨 模板开发指南

1. 静态资源加载

在模板顶部加载静态文件标签，并使用静态资源：

{% load static %}

<link rel="stylesheet" href="{% static 'css/style.css' %}">

<script src="{% static 'js/main.js' %}" defer></script>

<img src="{% static 'images/logo.png' %}" alt="Logo">

2. 使用主题个性化设置

在模板中直接引用 themesettings.json 中的配置：


<div style="color: {{ themeprimarycolor }}">主题主色调</div>

<body style="font-family: {{ themefontfamily }}">
    {{ site_name }}
</body>

<p>每页显示 {{ thememaxposts }} 篇文章</p>

3. 使用主题元信息

在视图中传递主题元信息到模板：

# views.py
import json
from pathlib import Path

def yourview(request):
    themedir = Path("templates/themes/yourthemename")
    with open(themedir / "themeconfig.json", "r", encoding="utf-8") as f:
        themeconfig = json.load(f)

context = {
        "themename": themeconfig.get("name"),
        "themeversion": themeconfig.get("version"),
        "themeauthor": themeconfig.get("author"),
        "themedescription": themeconfig.get("description"),
    }
    return render(request, "template.html", context)

🔧 后续开发步骤

替换预览图：将 theme.jpg 替换为主题的实际预览图
添加图片资源：在 static/images/ 目录中添加主题所需图片
修改主题信息：编辑 themeconfig.json 中的主题元信息
配置主题设置：编辑 themesettings.json 中的个性化设置项
开发模板：在 templates/ 目录中完善HTML模板文件
完善样式：在 static/css/ 目录中完善样式表
添加脚本：在 static/js/ 目录中添加JavaScript功能
自定义标签：在 templatetags/ 目录中创建自定义模板标签（可选）

❓ 常见问题

Q1: 主题名称可以使用中文吗？

不建议使用中文作为主题目录名，建议使用英文、数字和下划线的组合。主题显示名称可以在 themeconfig.json 的 name 字段中设置中文。

Q2: themesettings.json 是必须的吗？

不是必须的。如果主题不需要个性化设置，可以删除 themesettings.json 文件或将内容置空。

Q3: 如何修改主题设置项的默认值？

直接编辑 themesettings.json 文件中每个设置项的 default 字段值即可。

Q4: 主题设置变量在模板中如何使用？

在模板中使用 {{ themesettingname }} 的格式，其中 settingname 是 themesettings.json 中定义设置的 name 字段值，前缀为 theme。

Q5: 主题模块元信息如何访问？

在Python中可以通过导入主题模块访问：

import sys
sys.path.append('templates/themes/yourthemename')
import yourthemename
print(yourthemename.version)  # 输出主题版本

🔍 故障排除

问题	可能原因	解决方案
命令执行失败	Django应用未正确配置	确保命令文件在正确的 `management/commands/` 目录中
主题目录已存在	同名主题已创建	使用不同的主题名称，或删除已存在的目录
静态资源无法加载	模板中未加载静态标签	在模板顶部添加 `{% load static %}`
主题设置变量不显示	设置名称错误或未定义	检查 `themesettings.json` 中的 `name` 字段

🏆 最佳实践

命名规范：使用有意义的主题名称，如 modernblog、corporatetheme 等
版本管理：在 themeconfig.json 中维护正确的版本号
响应式设计：确保主题支持移动设备，使用响应式CSS
浏览器兼容：测试主题在不同浏览器中的显示效果
性能优化：优化图片大小，合并CSS/JS文件，减少HTTP请求
SEO友好：确保HTML结构清晰，使用语义化标签
文档完善：在 README.md 中提供完整的使用说明

模板开发

快速找到您需要的专业解决方案

查看全部

如何为 DjacoreCMS 的不同页面（首页、列表页、详情页）设置不同的 `<title>`？

模板开发 10 次浏览 2026-04-11

在基础模板（如 `base.html`）中，将 `` 标签内容定义在一个 block 中：`{% block title %}默认标题{% endblock %}`。然后，在各个子模板（如 `home.html`, `article_detail.html`）中，使用 `{% block ti...

查看

模板中如何使用上下文变量？

模板开发 5 次浏览 2026-04-11

视图传递的上下文变量可直接在模板中使用 {{ variable }} 输出，使用点号访问属性 {{ object.attribute }}，使用过滤器修改变量 {{ variable|filter }}。

查看

DjacoreCMS 的模板继承机制是如何工作的？

模板开发 4 次浏览 2026-04-11

通过 {% extends "base.html" %} 指令，子模板继承父模板。父模板中使用 {% block content %} 等标签定义可被覆盖的“块”。子模板中使用同名的 {% block content %} 来填充这些块的内容。

查看

在 DjacoreCMS 模板中，如何优雅地处理可能为空的变量？

模板开发 4 次浏览 2026-04-11

使用 Django 模板过滤器的“链式”调用和默认值过滤器。例如：`{{ user.profile.bio|default:“暂无介绍”|truncatechars:100 }}`。如果 `user` 或 `profile` 不存在，`default` 过滤器会生效，避免模板渲染错误。另一个强...

查看

模板变量和标签有哪些？

模板开发 4 次浏览 2026-04-11

提供丰富的模板变量和自定义标签，支持动态内容渲染和逻辑控制，满足复杂的页面展示需求。

查看

DjacoreCMS 模板如何实现按日期归档的文章列表？

模板开发 4 次浏览 2026-04-11

首先在视图中查询数据并按年-月分组。可以使用 Django 的 `dates` 查询集方法：`date_list = Article.objects.dates(‘pub_date', ‘month', order=‘DESC')`。在模板中循环这个日期列表，并为每个日期项生成一个链接，指向类...

查看

查看更多问题

文档版本

Djacore CMS 使用文档

模板开发

开发说明：

主题结构

themeconfig.json

themesettings.json

表单字段与 JSON 类型对应关系

主题模板创建工具说明

📋 工具简介

🚀 使用方法

创建名为 "dark_mode" 的主题

创建带下划线的主题

📁 生成的文件结构

⚙️ 配置文件说明

1. themeconfig.json - 主题元信息配置

2. themesettings.json - 主题个性化设置

🎨 模板开发指南

1. 静态资源加载

2. 使用主题个性化设置

3. 使用主题元信息

🔧 后续开发步骤

❓ 常见问题

Q1: 主题名称可以使用中文吗？

Q2: themesettings.json 是必须的吗？

Q3: 如何修改主题设置项的默认值？

Q4: 主题设置变量在模板中如何使用？

Q5: 主题模块元信息如何访问？

🔍 故障排除

🏆 最佳实践

模板开发

如何为 DjacoreCMS 的不同页面（首页、列表页、详情页）设置不同的 `<title>`？

模板中如何使用上下文变量？

DjacoreCMS 的模板继承机制是如何工作的？

在 DjacoreCMS 模板中，如何优雅地处理可能为空的变量？

模板变量和标签有哪些？

DjacoreCMS 模板如何实现按日期归档的文章列表？

Djacore CMS 使用文档

文档版本

Djacore CMS 使用文档

模板开发

分享这篇文章

开发说明：

主题结构

themeconfig.json

themesettings.json

表单字段与 JSON 类型对应关系

主题模板创建工具说明

📋 工具简介

🚀 使用方法

创建名为 "dark_mode" 的主题

创建带下划线的主题

📁 生成的文件结构

⚙️ 配置文件说明

1. themeconfig.json - 主题元信息配置

2. themesettings.json - 主题个性化设置

🎨 模板开发指南

1. 静态资源加载

2. 使用主题个性化设置

3. 使用主题元信息

🔧 后续开发步骤

❓ 常见问题

Q1: 主题名称可以使用中文吗？

Q2: themesettings.json 是必须的吗？

Q3: 如何修改主题设置项的默认值？

Q4: 主题设置变量在模板中如何使用？

Q5: 主题模块元信息如何访问？

🔍 故障排除

🏆 最佳实践

模板开发

如何为 DjacoreCMS 的不同页面（首页、列表页、详情页）设置不同的 `<title>`？

模板中如何使用上下文变量？

DjacoreCMS 的模板继承机制是如何工作的？

在 DjacoreCMS 模板中，如何优雅地处理可能为空的变量？

模板变量和标签有哪些？

DjacoreCMS 模板如何实现按日期归档的文章列表？

Djacore CMS 使用文档