1. 模板包
一套模板就是主程序 templates/ 下的一个文件夹,页面用原生 PHP 写,没有模板标签、没有编译缓存。
后台「模板管理」扫描只看一件事:目录里有没有 Dtr.php。删掉整个文件夹就干净移除。
1.1 目录结构
后台「新建主题」按这套骨架生成,一共 10 个文件,一个不多:
templates/你的目录名/
├─ Dtr.php 模板信息。后台「模板管理」和商店只认这个文件
├─ Config.php 配置默认值。后台改过的值另存数据库,不动这个文件
├─ Form.html 后台「模板配置」的表单,纯 PHP,能直接写 tplcfg()
├─ views/
│ ├─ layout.php 公共外壳。有它,每个页面就不用重写头尾
│ ├─ header.php footer.php 被 layout 用 partial() 调的片段
│ ├─ index.php 首页,必需
│ └─ 404.php 找不到页面时的兜底页
└─ public/pc/
├─ css/style.css 这套模板自己的样式,改它不影响别的模板
└─ js/main.js 自己的脚本
生成器不会帮你做的事,得自己补:
├─ pic.png 预览图。它是 Dtr.php 里 pic 指过来的文件,图要自己截放进去,
│ pic 这一行也要自己写上;DTRCMS 后台只认 pic 填的路径,不填就是纯色块
├─ 其它页面视图 sort.php / site.php / search.php / apply.php / about.php 等
│ 想要自己写就放进 views/,不写就自动回落到 default 模板的同名视图
└─ public/pc/img/ 图片目录自己建,框架不生成空目录
最省事的起步方式:主程序后台「应用中心」右上角点「新建主题」或「新建插件」,填目录名和中文名,
框架按上面的结构生成一整套能直接改的骨架文件,改配色和文案就能看效果。生成的主题不会自动启用,
要回「模板管理」点启用。也可以把 templates/default 复制一份改名。
1.2 Dtr.php 每个字段
// templates/mytpl/Dtr.php 返回一个数组,键名固定,值随便改
return [
'title' => '我的模板',
'name' => 'mytpl', // 必须等于目录名,也等于标识 ID 里那段
'author' => '张三',
'version' => '1.0.0',
'pic' => 'pic.png', // 相对模板目录。DTRCMS 后台只按这行找图,不写就不显示;官网代打包时缺省才会去找 pic.png
'link' => 'https://wpa.qq.com/msgrd?v=3&uin=123456789&site=qq&menu=yes',
'set' => '1', // 不写等于 1,后台会出现「模板配置」;要藏起来必须显式写 0
'desc' => '一句话介绍这套模板。',
];
| 键 | 必填 | 干什么 | 注意 |
|---|---|---|---|
title | 是 | 后台列表和商店里显示的中文名 | 空的话列表里就没名字 |
name | 是 | 模板目录名,框架靠它定位目录 | 必须和目录名一致;也对不上官网标识 ID 就拒装 |
author | 是 | 作者名,商店详情页显示 | |
version | 是 | 版本号 x.y.z | 商店比对版本、提示有没有更新用它 |
pic | 否 | 预览图,相对模板目录,一般写 pic.png | DTRCMS 后台只按这行找图,不写就不显示;官网代打包缺省才找 pic.png |
link | 否 | 作者联系方式,通常贴 QQ 客服链接 | |
set | 否 | 框架读的是 set ?? 1:不写等于写 1 | 要藏掉后台「模板配置」入口必须显式写 0,删掉这行反而看得见 |
desc | 是 | 一句话介绍 | 商店列表的简介就是它 |
1.3 Config.php 的默认值,与后台改过的值存哪儿
// templates/mytpl/Config.php 键名自定义,视图里用 tplcfg('键名') 取
return [
'hero_title' => '我的导航站',
'hero_desc' => '一句话说清这站是干什么的',
'theme_main' => '#2f6fdb', // 配色,layout 里当 CSS 变量用
'theme_sub' => '#16346b',
'lead_num' => '128',
'foot_link' => "首页,/\n关于,/about.html", // 多行值必须双引号,单引号里的 \n 不成换行
// 勾选型字段的键名全列在这儿:没勾存 0,勾了存 1
'_switch' => 'hero_open,show_new,show_hot',
];
- 默认值写在你包的
Config.php里,返回一个数组。 - 改过的值存在数据库
dtr_tpl表的config列,一条模板一行 JSON。 读的时候用库里那份覆盖你的默认值,所以升级换包不会把站长的设置冲掉。 - 恢复默认后台点「恢复默认」就是删掉库里那一行,重新读你的文件。
- 键名不限想要多少个字段自己加,视图里
tplcfg('键名')取,取不到给你写的第二个参数。 - 保存的前提只有当前启用中的模板能在后台保存配置,没启用的模板点了会被退回。
勾选型字段要把键名列进 _switch:后台按「没勾存 0、勾了存 1」处理,
没列进去的字段当普通文本存,复选框就永远存不下。多行值必须用双引号写 "a\nb",
单引号里的 \n 是两个字符不是换行。
1.4 Form.html 怎么写
<!-- templates/mytpl/Form.html:字段名必须和 Config.php 的键一模一样 -->
<div class="fg">
<label>横幅标题</label>
<input class="input" name="hero_title" value="<?php echo e(tplcfg('hero_title')); ?>">
</div>
<div class="fg">
<label>横幅说明</label>
<textarea class="textarea" name="hero_desc" rows="3"><?php echo e(tplcfg('hero_desc')); ?></textarea>
</div>
<!-- 勾选型字段:先放一个 value=0 的 hidden,再放同名 checkbox -->
<div class="fg">
<label class="switch">
<input type="hidden" name="hero_open" value="0">
<input type="checkbox" name="hero_open" value="1" <?php echo tplcfg('hero_open') == '1' ? 'checked' : ''; ?>>
<span>显示首页横幅</span>
</label>
</div>
<div class="fg-full">
<p class="tip">改完点「保存」,值写进数据库,你的 Config.php 不会被动。</p>
</div>
Form.html 不是静态 HTML,它按 PHP 渲染,能直接用 tplcfg() 回显当前值、能用 e()。
字段名 name 必须和 Config.php 的键一模一样,名字对不上的字段存不进去。
可用的样式 class 照 default 或 lumen 那套:tpl-cfg 外层、form-grid cols-4 栅格、
fg 与 fg-full 单元格、section-title 分节、input
textarea 控件、switch 开关、tip 说明。
1.5 视图怎么拿数据
视图引擎是 DTR\Core\View,render('index', $data) 渲染 views/index.php,
数据数组直接 extract 成变量:控制器给什么,视图里就有什么,模板不查数据库。
<?php use DTR\Core\Config; use DTR\Core\Hooks; ?>
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title><?php echo e($seo_title ?? dtr('title')); ?></title>
<link rel="stylesheet" href="<?php echo tpl_url('css/style.css'); ?>">
<style>:root{--sk:<?php echo e(tplcfg('theme_main', '#2f6fdb')); ?>;}</style>
<?php echo Config::get('site_head', ''); ?> <!-- 后台「站点设置 → 头部代码」 -->
<?php Hooks::fire('front_head', ['page' => $page]); ?> <!-- 插件往这儿插 css/js -->
</head>
<body class="page-<?php echo e($page); ?>">
<?php Hooks::fire('front_body_start'); ?>
<?php echo $this->partial('header', ['page' => $page]); ?> <!-- 复用片段,不套布局 -->
<main>
<?php echo $__content; ?> <!-- 引擎把渲染好的页面塞进这个变量 -->
</main>
<?php Hooks::fire('front_footer_extra'); ?>
<?php echo $this->partial('footer', ['page' => $page]); ?>
<?php echo Config::get('site_foot', ''); ?>
<?php Hooks::fire('front_body_end', ['page' => $page]); ?>
</body>
</html>
- 套布局有
views/layout.php就自动套,页面渲染结果塞进$__content;没有就单独输出页面。 - 片段
$this->partial('header', [...])渲染片段,不套布局;$this->wrap($html)可以把一段现成 HTML 用当前模板的头尾包住。 - 回退当前模板缺某个视图,引擎自动回退去读
templates/default/views/的同名文件, 所以可以只做首页,其余页面先借默认模板。 - 标题控制器给的
$page是页面名,用来给 body 加 class;想自己定标题就给视图传$seo_title。
<?php /* 页面视图里:控制器传什么变量,这儿就有什么 */ ?>
<h1><?php echo e($sort['name']); ?></h1>
<?php foreach ($sites as $s): ?>
<article>
<a href="<?php echo url('site', ['id' => (int) $s['id']]); ?>"><?php echo e($s['name']); ?></a>
<p><?php echo e(cut($s['description'], 80)); ?></p>
<img src="<?php echo e($s['img']); ?>" alt="">
</article>
<?php endforeach; ?>
<?php if (tplcfg('hero_open') == '1'): ?> <!-- 模板配置 -->
<section><?php echo e(tplcfg('hero_desc')); ?></section>
<?php endif; ?>
<?php echo ad(1); ?> <!-- 广告位 1,后台填的代码 -->
<?php if (plugin_active('friendlink')): ?> <!-- 这功能被插件接管了 -->
<?php endif; ?>
<?php /* 分页:pager.php 里用 $cur / $pages / $total */ ?>
<a href="<?php echo url('sort', ['id' => (int) $sort['id'], 'page' => $cur + 1]); ?>">下一页</a>
| 视图 | 控制器传进来的变量 |
|---|---|
index | $page $sorts $recommend $latest $topView $recent $notice $links $articles $cntList $cntWz $cntSort $cntApply |
nav | $page $sorts $siteGroups $latest $mostView $recommend $hotWords $notice $cntList $cntSort $cntWz |
sort | $page $sort $sorts $sites $total $pages $cur $topView $latest。「最新收录」复用这个视图,多给一个 $list_route = newest |
site | $page $site $sort $domain $related $links |
search | $page $kw $sites $total $pages $cur $sorts |
ranking | 榜单首页:$page $seo_title $rankDay $rankMonth $rankTotal $rankArticles $rankStats $latest。分榜:$page $seo_title $rankType $rankTitle $rows $total $pages $cur $per $rankStats |
wz_all | $page $rows $total $pages $cur $sortwz $articleGroups $tui $hotWords $notice $cntWz |
wz_sort | $page $sortwz $rows $total $pages $cur $allwz |
wz_show | $page $article $sortwz $readable $readWhy $toc $contentHtml $words $readMin $related $prev $next $topics $hot $reader $likeOn $liked $likeCount $payReady $tipOn $priceYuan $payStats $payAmounts $walletFen $flash |
topics | $page $topics $counts $cur $pages $total $hot |
topic | $page $topic $arts $total $pages $cur $others $hot |
tougao | $page $err $sorts $old $token $tips $audit $hot |
apply | $page $sorts $msg $notice。前台投稿页,跟 tougao 不是一页 |
daishen | $page $rows $total $pages $cur。待审列表 |
tongji | $page $cntList $cntWz $cntSort $cntApply |
about | $page |
login | $page $err $back |
register | $page $err $old |
user | $page $me $tab $tabs $msg $submits $favs $myStats $tabHtml |
pager | 片段,partial 出来的:$cur $pages $total |
404 | $page |
想改首页数据不用改核心:在 index 之前挂 front_index 过滤器,
它拿到整个数据数组,改完原样 return。
1.6 后台与前台自适应要求
前台页面是给客户站的手机用户看的,验收只看两条:390px 宽不横向溢出、点得着能看得清。 后台那边的「模板配置」弹窗宽度会跟着变,Form.html 里别写死宽度。
/* 后台改配色,模板只要接住 CSS 变量 */
:root { --sk: #2f6fdb; }
.btn { background: var(--sk); }
/* 自适应:脚手架默认给 900 断点,lumen 用了 1180 / 900 / 520 三档 */
@media (max-width: 900px) {
.wrap { padding: 0 14px; }
.cols-4 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
}
@media (max-width: 520px) {
.cols-4 { grid-template-columns: 1fr; }
.side { display: none; }
}
/* 这三条是防止手机上横向溢出的底线 */
img, video, pre, table { max-width: 100%; }
html { -webkit-text-size-adjust: 100%; }
- viewport meta 一定要有,layout 的 head 标签里那行别删。
- 图片、pre、表格给
max-width:100%,长表格用overflow-x:auto的容器包着。 - 栅格用
grid-template-columns配minmax(0,1fr),小屏一档一档降列数。 - 配色从
tplcfg()读出来写进 CSS 变量,别把颜色硬编码在 style.css 里。 - 静态资源一律
tpl_url()输出,写死路径会串到别的目录去。
内容有问题去论坛发帖,或直接联系老李 QQ 260468289。