开发文档 ›全部章节 ›入门 ›模板包

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.pngDTRCMS 后台只按这行找图,不写就不显示;官网代打包缺省才找 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。