一、主题文件结构
可进入「后台管理」界面,在 应用中心 插件中,通过点击 新建主题 或 新建插件 按钮创建应用;会自动创建相应的文件夹及「自述文件」,并根据应用类型放入「初始文件」。
以下基于通过创建应用生成的初始文件:
/path/zb_users/theme/demoTheme │ screenshot.png [必需]缩略图 300*240像素, 横向; │ theme.xml [必需]自述文件; │ main.php [可选]应用内置管理页,在创建主题时填写才会生成; │ include.php [可选]应用嵌入页,在创建主题时填写才会生成; │ ├─compile [废弃]旧版 z-blog 用于放置模板编译文件,可直接删除; ├─include [可选]主题自带「文件模块」,使用{module:abc}「嵌入调用」该目录下的abc.php文件; ├─script [可选]JS目录; ├─style [必需]样式目录, 内存样式表及所需图片; │ style.css [必需]不限于这个文件名,一套主题也可以拥有多个样式(各自独立使用); │ ├─css [可选]并不会自动创建,用于不应该放在style文件夹中的样式内容; └─template 用于存放模板文件;建议优先确立以下 6 个模板文件及内容; index.php 首页及列表页 single.php 文章页(单页) search.php 搜索结果页,不存在时使用index.php header.php 公共头部文件 footer.php 公共尾部文件 404.php 建议设置
二、主入口模板
默认情况下,系统只会尝试直接调用index.php、single.php、search.php、404.php四个模板文件(如果存在的话);其他模板则通过「嵌入调用」组合其自身内容到「主模板」之中;
三、示例
1、理论上可以直接使用如下示例作为四个「主模板」文件的基础结构;(Your Code部分除外);
2、{template:header} {template:footer} {template:sidebar} 为「Z-BlogPHP 体系内」常用模板,{template:hero}则可自由命名,用于拆分相应位置的代码;
{* Template Name: 首页及列表页 * Template Type: index|list *} <!-- ↑ 「模板描述信息」,包括适配的「页面类型」,放在模板文件第一行 --> <!DOCTYPE html> <html lang="{$language}"><!-- {$language} 为「变量输出标签」 --> <head> {template:header}<!-- 公共头部文件 --> </head> <body class="{$type}"><!-- 同为「变量输出标签」,对应上方 Template Type --> {template:hero} <!-- ↓Your Code↓ --> <!-- ↓Your Code↓ --> <div id="divNavBar"> <!-- 导航「模块」调用 --> <ul>{module:navbar}</ul> </div> <div id="divMiddle"> <div id="divMain">列表索引或正文内容</div> <!-- 「侧栏」调用 --> <div id="divSidebar">{template:sidebar}</div> </div> <!-- ↑Your Code↑ --> <!-- ↑Your Code↑ --> {template:footer}<!-- 公共尾部文件 --> </body> </html>
三、模板文件及缺省机制
因为「保留模板」机制,当主题未提供某一模板文件时,系统会从zb_system/defend/default中读取使用;因此可以缺省部分不需要自定义内容结构的模板文件,尤其是侧栏模块部分;
四、页面公共模板文件
五、首页与列表页模板
六、日志/独立页模板
七、侧栏模块相关
1、模块展现外框架模板
2、模块内容细节模板(1.5 版本及以上)
八、模板书写
描述信息(可选)
1、模板内注释语法(推荐)
放在模板文件第一行:{* Template Name:「模板用途描述」 *}
可以同时声明模板类型(针对「主入口模板」):{* Template Name: 首页及列表页 * Template Type: index|list *}
注意:
「描述信息」和「类型声明」的必要性仅体现在同一「页面类型」有多个「入口模板」可供用户选择时的选项输出,或者针对不同「页面类型」细化建立了不同的模板文件。对于后者需要自行实现判断调用,或引导用户选择设置。在{}内部,*与其他内容之间要有空格;
- index 首页 - list 列表页 - author - category - date - tag - single 单页面(含文章与页面) - article - page - search 搜索 - 404 404 - none 显示设置隐藏
2、1.7.0 以后支持 template.json 配置
template.json示例:
{ "id": "主题ID", "templates": [ { "filename": "index", "type": "list", "name": "列表自动模板" }, { "filename": "single", "type": "single", "name": "文章/单页自动模板" } ] }
九、嵌入调用
1、嵌入模板文件
{template:hearder} – 嵌入模板文件 hearder.php 的文件内容。
2、嵌入模块内容
{module:navbar} – 嵌入「导航栏模块」,「模块」或者说「侧栏模块」,一般是指 「后台管理」→模块管理 中列出的项目;navbar为「导航栏模块」的「filename(文件名)」,其他「模块」同理;
注意:除include文件夹内的「文件模块」外其他模块其实是存在数据库的,另外不建议使用「文件模块」,主题更新时用户修改的内容会被覆盖。
十、模板标签
在「模板文件示例」示例中使用了{$language}和{$type}两个语法标签,称为「变量输出标签」或「模板标签」,实际会编译为<?php echo $language;?>和<?php echo $type;?>来输出对应变量的值;在 Z-BlogPHP 模板中,可通过{$var}、{$obj.a}来输出「文本或数字类型」的「变量或对象属性」,其中后者会编译为<?php echo $obj->a;?>。
注意:
1、部分标签只能在特定的页面类型($type取值)或上下文中才能使用;
2、{module:navbar}可视为{$modules[“navbar”].Content}的简写语法;
3、除系统标签外,可通过「接口机制」或「原生 PHP 语法」自定义或修改作为标签输出的变量。
十一、模板内使用PHP
在相应内容输出前,可以使用如下语法额外对数据进行处理;
{php} // 这里可以写原生 PHP; $myVar = "变量值"; {/php} <p>输出一个自定义变量:{$myVar}</p> <p>当前 Z-BlogPHP 版本是:{$version}</p> //还可以用<?php ?>符号在{php}{/php}里以实现代码高亮 {php}<?php //原生php代码 ?>{/php}