跳到主要内容

🎨 模板开发指南

emlog可以方便的更换模板,模板文件位于 content\templates 目录下,每个模板都是一个单独的文件夹,文件夹以模板的英文别名命名。通过应用商店以及后台上传安装的模板都保存在这个目录下。

模板文件及目录说明​

文件名说明
css存放模板所需的所有CSS样式文件
js存放模板所需的所有JS文件
images存放模板所需 LOGO 等图片资源
preview.jpg在后台模板选择界面显示的模板预览图,推荐:500x300 jpg格式
header.php站点头部信息,一般包含页面head信息和顶部标题、导航栏
echo_log.php文章详情页,展示单篇文章内容
log_list.php首页,展示文章列表
footer.php站点底部信息,展示版权信息等
page.php页面,展示自定义的页面
side.php侧边栏,如制作单栏模板则该文件不是必须的
module.php功能模块:最新文章、评论、分类、标签等
404.php自定义404页面未找到时的报错页面
pw.php自定义加密文章输入密码页面,没该文件使用系统默认样式 【非必须】
user.php路由 /user 加载的模板,可用于用户中心等页面【非必须】
plugins.php模板的系统调用文件,模板启用后,该文件会被系统自动加载。可用于实现类似插件的功能。【非必须】
options.php模板设置的配置文件,可以构建更丰富的设置项。【非必须】
callback.php模板的事件回调函数定义,详见事件回调部分文档【非必须】
custom_fields.php预设模板自己需要的文章自定义字段【非必须】

模板引擎​

emlog未采用任何其他第三方的模板引擎,直接使用PHP原生的语法标记来内嵌HTML生成动态页面。这样不但降低了开发者的学习负担,也大大提高了页面加载和渲染效率。

// 嵌入变量
<div><?= $value ?></div>

// 循环
<?php foreach ($abc as $v) :?>
<div><?= $v ?></div>
<?php endforeach;?>

// 判断
<?php if($a == 'abc') :?>
<div>hello</div>
<?php endif;?>

公共代码​

禁止直接访问​

下面这行代码存在于模板目录下的每个php文件开头,其作用是防止代码所在的php脚本被直接访问执行,务必保留。

if(!defined('EMLOG_ROOT')) {exit('error!');}

或者

defined('EMLOG_ROOT') || exit('access denied!');

引用模板文件​

下面这两行代码作用是调用模板文件夹下的 side.php 和 footer.php 的代码到当前文件的当前位置。

require_once View::getView('side');
require_once View::getView('footer');

// View是模板视图控制器,View::getView('文件名','文件后缀')将返回当前模板安装路径下对应的文件。
// getView 函数的第二个参数为缺省参数,在不传入值的情况下,将默认作为.php文件后缀返回文件路径。

文件说明​

header.php​

站点头部信息,一般包页面head信息和顶部标题、导航栏。

页头信息​

开头注释内容是模板的必要信息,该信息会显示在后台模板管理界面,务必完整填写。

/*
Template Name:默认模板
Version:1.0
Template Url:https://www.emlog.net/template/
Description:emlog的默认模板
Author:emlog
Author Url:https://www.emlog.net/author/index/577
*/
提示

其中 Template URL 和 Author URL 请使用官网 emlog.net 的应用链接和作者页,其他非官网链接不会在后台展示超链接。

加载模板文件​

require_once View::getView('module'); // 加载模板通用模块.

变量&常量​

变量&常量类型说明
$site_title变量站点标题(受后台seo优化设置影响)
$site_key变量站点关键字
$site_description变量输出站点浏览器描述 (受后台seo优化设置影响)
$blogname变量站点标题
$bloginfo变量站点副标题
BLOG_URL常量站点首页的URL,输出形如https://emlog.net/
TEMPLATE_URL常量模板文件夹的URL,用于加载模板内的css、js及其他内容,输出形如http://emlog.net/blog/content/templates/default/

上面的变量、常量都可以通过下面的方式在模板中输出

<?= $page_url ?>
<?= BLOG_URL ?>

footer.php​

站点底部信息,展示版权、备案等信息等。

变量&常量​

变量、常量类型说明
$icp变量后台设置的ICP备案号
$footer_info变量后台设置的页面底部信息
Option::EMLOG_VERSION常量当前emlog版本号

log_list.php​

首页模板,展示文章列表。

变量&方法​

变量、常量、方法类型说明
$value['log_cover']变量文章封面图URL
$value['logid']变量当前文章的id
$value['log_url']变量文章地址URL
$value['log_title']变量文章标题
date('Y-n-j', $value['date'])变量文章发布时间,参数'Y-n-j G:i l'用于定义日期格式
$value['log_description']变量文章摘要 (没有摘要则输出全文)
$value['comnum']变量当前文章的评论数
$value['views']变量当前文章的浏览量
$value['fields']变量自定义字段,数组类型,读取方式见下方示例
editflg($value['logid'],$value['author'])变量当管理员或作者登陆时显示“编辑”链接
topflg($value['top'])变量显示置顶标记,该函数位于模板module.php内
$page_url变量显示当前列表页的翻页功能
blog_sort($value['logid'])方法展示文章所属的分类
blog_author($value['author'])方法展示文章的作者
blog_tag($value['logid'])方法展示文章的标签

上面的变量、方法都可以通过下面的方式在模板中输出

<?= $value['logid'] ?>
<?= blog_author($value['author']) ?>

// 读取自定义字段,其中索引 abcd 即为自定义字段名称
if (isset($value['fields']['abcd'])) {
echo $value['fields']['abcd']; // 输出自定义字段名为 abcd 的值
}

echo_log.php​

文章详情页模板,展示单篇文章内容。

变量&方法​

变量、常量、方法类型说明
$logid变量当前文章的id
$log_title变量文章标题
$log_cover变量封面图URL
date('Y-n-j', $date)变量发布时间,参数'Y-n-j G:i l'用于定义日期格式
$log_content变量文章正文
$excerpt变量文章摘要
$comnum变量当前文章的评论数
$views变量当前文章的浏览量
$fields变量自定义字段,数组类型,读取方式见下方示例
$page_url变量显示当前列表页的翻页功能
topflg($top)方法显示置顶标记
blog_tag($logid)方法标签
blog_author($author)方法作者
blog_sort($logid)方法所属的分类
editflg($logid,$author)方法当管理员或作者登录时显示“编辑”链接。
neighbor_log($neighborLog)方法邻近文章,就是上一篇、下一篇。
blog_comments($comments)方法评论列表
blog_comments_post($logid,$ckname,$ckmail,$ckurl,$verifyCode,$allow_remark)方法发表评论框
// 在模板中输出标题
<?= $log_title ?>

// 读取自定义字段,其中索引 abcd 即为自定义字段名称
if (isset($fields['abcd'])) {
echo $fields['abcd']; // 输出自定义字段名为 abcd 的值
}

page.php​

页面,展示自定义的页面。变量定义等和echo_log.php相同。

side.php​

侧边栏,主要负责根据后台widgets设置信息输出侧边栏内容。建议该文件内代码保持不变。

module.php​

模板公共代码,包含侧边widgets、评论、引用、编辑等。

该文件由若干函数组成,被模板文件调用,可在内自定义函数实现更多功能。

如在自定义函数内调用emlog缓存时,假设读取user缓存信息,则形如: global $CACHE; $user_cache = $CACHE→readCache('user');

如需要操作数据库,则形如: $DB = MySql::getInstance(); $res = $DB→query($sql);

404.php​

用于自定义404页面的模板。

pw.php​

用于自定义加密文章输入密码页面,如果没有该模板文件,将使用系统默认样式,不影响输入密码功能正常使用,模板内容请参考默认模板。

user.php​

用户中心模板,可用于主题构建自己的用户中心。用户中心URL路由规则如下,其中 xxx 为自定义的路由名称,比如:/user/profile 或 /?uc=profile 等,如果该模板文件不存在,访问会提示404

  • 路由规则1(需要开启伪静态): /user/xxx
  • 路由规则2: /?uc=xxx

示例如下:

<?php
/**
* 前台用户中心
*/
defined('EMLOG_ROOT') || exit('access denied!');


// 判断是否登录
if (ISLOGIN) {
//do something
}

// 获取当前登录用户信息
$avatar = $userData['photo']
$name = $userData['nickname']
$bio = $userData['description']
$email = $userData['email']

// 获取当前路由路径
// 变量 $routerPath 存储了当前请求的路由路径,如:/user/profile,$routerPath 值为 profile
// 引入头部模板文件(可根据路由判断是否引入)
if (in_array($routerPath, ['', 'order', 'account', 'profile', 'weiyu'])) {
include View::getView('header');
}

// 实现路由对应功能
if ($routerPath === 'profile') {
include View::getView('user_xxxx') //可加载其他模板文件
} elseif ($routerPath === 'weiyu') {
// 展示微语页
} elseif ($routerPath === 'order_calback') {
// 处理支付回调逻辑
} else {
show_404_page();
}

// 引入底部模板文件
include View::getView('footer')

custom_fields.php​

预设模板自己需要的文章自定义字段,在后台文章编辑页面添加自定义字段支持下拉选择这些预设字段。配置内容参考如下:

<?php
/**
* 模板预设的文章自定义字段
*/

defined('EMLOG_ROOT') || exit('access denied!');

$custom_fields = [
'price' => [
'type' => 'text',
'name' => '价格',
'description' => '如:9.99',
'default' => ''
],
'need_vip' => [
'type' => 'radio',
'name' => '是否需要会员',
'values' => [
'0' => '否',
'1' => '是'
],
'description' => '1是,0否',
'default' => '0'
],
];

plugins.php​

模板的系统调用文件,模板启用后,该文件会被系统自动加载。可用于实现类似插件的功能。

有时候模板也会希望在系统中自定义一些功能,包括在插件的挂载点挂载函数进行功能扩展,该文件就赋予模板这个能力,这样模板就不需要安装额外的配套插件,就可以实现更丰富的功能。

<?php
/**
* 模板的系统调用文件
* 模板启用后,该文件会被系统自动加载。可用于实现类似插件的功能。
*/

if (!defined('EMLOG_ROOT')) {
exit('error!');
}

/* eg:

function sameFunc() {
echo "xxxx";
}

addAction('adm_head', 'sameFunc');

*/

options.php​

模板设置的配置文件,见下文 开启模板设置 部分。

自定义模板​

文章、分类、页面:支持自定义模板,用户在创建分类、页面以及文章的时候可以选择模板主题支持的自定义模板,从而实现更丰富的页面展示。

自定义模板文件的命名规则​

  • 分类:文件名以 log_list_ 开头,如:log_list_abc.php
  • 文章:文件名以 echo_log_ 开头,如:echo_log_abc.php
  • 页面:文件名以 page_ 开头,如:page_abc.php

自定义模板文件的注释规则​

<?php
/*@name 自定义模板的名称*/

该注释内容会作为自定义模板名称出现在下拉选择框中 ,符合上述规范的自定义模板会以下拉选择框的方式出现在添加分类和创建页面场景中,方便用户选择。

模板挂载点​

如下代码格式是模板里的插件挂载点,参考默认模板,注意保留,不要删除

<?php doAction('xxx') ?>
危险

注意:务必在开发模板时参考默认模板保留下面这些挂载点,方便兼容其他插件。

挂载点所属文件改在点描述实例
doAction('index_head')header.php站点head标签内挂载点,用于挂载js或css样式文件
doAction('index_footer')footer.php页脚底部挂载点,用于挂载底部信息展示类插件
doAction('index_loglist_top')log_list.php首页文章列表顶部挂载点, 建议添加在首页导航栏下方
doAction('log_related', $logData)echo_log.php相关文章挂载点, 添加在文章内容和评论之间的位置

事件回调​

在emlog后台的外观-模板管理页面,用户可以开启、删除、更新模板。这些操作会触发对应的回调函数。 开发者可以给模板添加文件: callback.php 并定义特定事件的回调函数,来实现模板初始化、数据清理、数据结构更新等操作。

事件触发函数
开启模板callback_init()
删除模板callback_rm()
更新模板callback_up()

示例:(请参考默认主题目录下的 callback.php)

模板设置​

模板支持自定义设置功能,为模板提供更丰富的设置功能。

在模板目录里放入 options.php 文件,内容格式如下即可,可以任意增加设置项,开头注释不可以删除或更改,参考如下:

默认主题 options.php 完整示例​

以下为系统默认主题真实的配置文件完整示例,开发者可直接参考或复制:

<?php
/*@support tpl_options*/

/**
* 模板设置的配置文件
* 详见官网文档-模板开发:https://www.emlog.net/docs/dev/template
*/

defined('EMLOG_ROOT') || exit('access denied!');

$options = [
'TplOptionsNavi' => [
'name' => '定义设置项标签页名称',
'values' => [
'tpl-head' => '头部设置',
'tpl-home' => '首页设置',
'tpl-article' => '文章设置',
'tpl-demo' => '设置演示',
],
'description' => '' // 设置说明(可选)
],
'logotype' => [
'labels' => 'tpl-head',
'type' => 'radio',
'name' => 'LOGO显示模式',
'values' => [
'1' => '文字',
'0' => '图片',
'2' => '图文',
],
'default' => '1',
],
'logoimg' => [
'labels' => 'tpl-head',
'type' => 'image',
'name' => 'LOGO上传',
'values' => [
TEMPLATE_URL . 'images/logo.png',
],
'description' => '上传LOGO图片,推荐尺寸 180x60像素,高度不超60像素'
],
'favicon' => [
'labels' => 'tpl-head',
'type' => 'image',
'name' => '浏览器图标(favicon)',
'description' => '上传浏览器图标,推荐尺寸48×48的PNG或JPG图片'
],
'slideShow' => [
'labels' => 'tpl-home',
'type' => 'text',
'name' => '首页轮播图',
'multi' => true,
'description' => '每行一个,图片高度推荐260像素,格式:图片地址 | 图片标题 | 跳转地址',
],
'isShowCover' => [
'labels' => 'tpl-article',
'type' => 'checkon',
'name' => '在文章页展示封面图',
'values' => ['1' => '开启'],
'default' => '0',
'description' => ''
],
'isSideBar' => [
'labels' => 'tpl-article',
'type' => 'checkon',
'name' => '在文章页展示侧边栏',
'values' => ['1' => '开启'],
'default' => '0',
'description' => ''
],
'isAllowCommentUrl' => [
'labels' => 'tpl-article',
'type' => 'checkon',
'name' => '评论时可填写主页',
'values' => ['1' => '开启'],
'default' => '1',
'description' => ''
],

// 1. notice - 提醒
'demo_notice' => [
'labels' => 'tpl-demo',
'type' => 'notice',
'style' => 'info',
'name' => '组件演示说明',
'content' => '本页面演示了模板设置插件新增支持的 10 种选项类型:background(背景)、border(边框)、date(日期)、link(链接)、link_color(超链接颜色)、notice(提醒)、number(数字框)、slider(滑块)、spacing(间距)、submessage(小提醒)。',
],

// 2. submessage - 小提醒
'demo_submessage' => [
'labels' => 'tpl-demo',
'type' => 'submessage',
'style' => 'success',
'content' => '小提醒(submessage):以左侧色条的紧凑形式展示内联提示、注意事项或配置引导。',
],

// 3. number - 数字文本框
'demo_number' => [
'labels' => 'tpl-demo',
'type' => 'number',
'name' => '分页显示文章数',
'description' => '数字文本框(number):支持设置数值上下限(min/max)、步长与后缀单位',
'min' => 1,
'max' => 100,
'step' => 1,
'unit' => '篇',
'default' => '10',
],

// 4. slider - 滑块
'demo_slider' => [
'labels' => 'tpl-demo',
'type' => 'slider',
'name' => '列表卡片圆角弧度',
'description' => '滑块(slider):拖动滑块或在右侧数字框输入,实时双向联动更新',
'min' => 0,
'max' => 50,
'step' => 1,
'unit' => 'px',
'default' => '8',
],

// 5. date - 日期(单日期与区间)
'demo_date' => [
'labels' => 'tpl-demo',
'type' => 'date',
'name' => '单个活动截止日期',
'description' => '日期组件(date):单日期选择器,采用写文章页面的日历交互控件',
'default' => '2026-12-31',
],
'demo_date_range' => [
'labels' => 'tpl-demo',
'type' => 'date',
'name' => '活动起止时间范围',
'description' => '日期组件(date):支持起止范围区间选择(from_to)',
'from_to' => true,
'text_from' => '开始',
'text_to' => '结束',
'default' => [
'from' => '2026-10-01',
'to' => '2026-10-31',
],
],

// 6. link - 链接
'demo_link' => [
'labels' => 'tpl-demo',
'type' => 'link',
'name' => '自定义推荐链接',
'description' => '链接组件(link):包含链接文字、链接网址以及在新标签页中打开',
'default' => [
'text' => 'Emlog 官网',
'url' => 'https://www.emlog.net',
'target' => '_blank',
],
],

// 7. link_color - 超链接颜色
'demo_link_color' => [
'labels' => 'tpl-demo',
'type' => 'link_color',
'name' => '超链接多状态颜色',
'description' => '超链接颜色(link_color):支持常规、悬浮、激活等多状态色彩配置',
'color' => true,
'hover' => true,
'active' => true,
'default' => [
'color' => '#1a73e8',
'hover' => '#1557b0',
'active' => '#0d47a1',
],
],

// 8. spacing - 间距
'demo_spacing' => [
'labels' => 'tpl-demo',
'type' => 'spacing',
'name' => '页面容器内边距(Padding)',
'description' => '间距组件(spacing):支持独立配置上、右、下、左间距及单位选择',
'units' => ['px', '%', 'rem'],
'default' => [
'top' => '16',
'right' => '20',
'bottom' => '16',
'left' => '20',
'unit' => 'px',
],
],

// 9. border - 边框
'demo_border' => [
'labels' => 'tpl-demo',
'type' => 'border',
'name' => '卡片边框样式',
'description' => '边框组件(border):支持边框粗细、线型样式(实线/虚线/点线等)以及边框颜色',
'all' => true,
'unit' => 'px',
'default' => [
'all' => '1',
'style' => 'solid',
'color' => '#e2e8f0',
],
],

// 10. background - 背景
'demo_background' => [
'labels' => 'tpl-demo',
'type' => 'background',
'name' => '全局背景配置',
'description' => '背景组件(background):支持背景色、背景图上传、平铺模式、对齐位置与附着方式',
'default' => [
'background-color' => '#f8fafc',
'background-image' => '',
'background-repeat' => 'no-repeat',
'background-position' => 'center center',
'background-size' => 'cover',
'background-attachment' => 'scroll',
],
],
];

options.php里,每个元素都该写什么?​

如上所示,$options 数组里,key为设置项的id,而value是一个数组,数组里包含若干个元素。其中type属性和name属性必选,name是设置项名字,而type用来指定设置项的类型。

设置项支持的类型:​

  • radio: 单选按钮
  • checkbox: 复选按钮
  • checkon: 开关
  • text: 单行/多行文本
  • image: 图片上传与媒体库选择
  • color: 颜色选择
  • sort: 分类选择
  • page: 页面选择
  • tag: 标签选择
  • select: 搜索选择(文章/分类/页面)
  • block: 多内容块(支持图文自由排序)
  • number: 数字文本框
  • slider: 滑块控件
  • date: 日期选择器
  • link: 链接组件
  • link_color: 超链接颜色
  • spacing: 间距组件
  • border: 边框组件
  • background: 背景组件
  • notice: 提醒条
  • submessage: 小提醒

设置项说明​

  • 对于所有类型,default属性用于指定默认值,当没有指定default时,使用values里第一个值,若都没有指定,则会使用奇怪的默认值。
  • 对于radio和chexkbox类型,values属性用来设置各个按钮的值和显示名称。
  • 除sort外,均可以指定depend为sort,表示该选项可以根据不同的分类设置不同的值,当指定depend为sort时,可选unsorted属性,为true时,表示包括未分类,为false不包括,默认为true。
  • 除tag外,均可以指定depend为tag,表示该选项可以根据不同的标签设置不同的值,例如给标签添加图标
  • sort和page可设置multi属性为true,表示多选。
  • description属性用于描述该选项 (可选)
  • 若type为text,可设置multi属性为true,表示多行文本,
  • 可选属性rich用以支持富文本,若设置该值,将加载编辑器(已废弃,pro系列版本不支持)。
  • 如果要使用数字文本框,type仍为text,可设置pattern属性为num。可指定max、min、unit,即限制最大值、限制最小值和数量单位。可单独设置最小值或最大值。例如仅设置最小值,最大值不会限制输入。计量单位会显示在文本框最右侧。
  • 如果使用日期文本框,type仍为text,可设置date属性为true即可。
  • 若type为sort、page或者tag,且设置了多选,默认值将为空,否则将为第一个该类型的值。
  • 对于类型select,pattern属性是必填项,可以填入:(1). post (2).cate (3).page。分别依次对应文章、分类、页面。此功能模块在数据非常庞大时可能查询缓慢。使用内置函数获取的数组内容为设置类型的ID,例如获取到一组文章gid。
  • (可选) 上述所有类型均支持 new 属性,即会在设置项名称后显示提醒徽标,效果可见默认模板。该属性值随意填写,如:NEW、新等。若为空或不填写将不显示。
  • 类型block,可选设置pattern属性,若不设置pattern属性默认内容为文本,可设置multi属性为true,表示多行文本。pattern属性设置为image可以使用多图片内容块。
  • 类型block,支持通过 placeholder 配置输入框占位文字。

字段类型详解与示例​

单选按钮(radio)​

单项选择按钮组,用户在多个互斥选项中挑选其中一项。

  • 支持属性:
    • name: 选项标题
    • values: 关联数组,键为选项保存的值,值为后台显示的文案
    • default: 默认选中的值(若未设置则默认取 values 的第一个选项)
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
'post_layout' => [
'labels' => 'tpl-head',
'type' => 'radio',
'name' => '文章列表排版模式',
'values' => [
'card' => '卡片网格',
'list' => '单列图文',
'text' => '极简纯文本',
],
'default' => 'card',
'description' => '选择首页及列表页的文章展示风格',
],
  • 模板中调用:
<?php
$layout = _g('post_layout'); // 返回选中的值字符串,例如 "card"
if ($layout === 'card') {
// 渲染卡片布局
}
?>

复选按钮(checkbox)​

多项勾选框,用户可同时勾选零个、一个或多个选项。保存并返回勾选项的值数组。

  • 支持属性:
    • name: 选项标题
    • values: 关联数组,键为各个选项保存的值,值为后台显示的文案
    • default: 默认勾选的项数组(如 ['author', 'date'])
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
'meta_elements' => [
'labels' => 'tpl-head',
'type' => 'checkbox',
'name' => '文章列表展示元素',
'values' => [
'author' => '作者信息',
'date' => '发布时间',
'views' => '阅读量',
'comnum' => '评论数',
],
'default' => ['author', 'date', 'views'],
'description' => '勾选需要在文章列表卡片中展示的元数据',
],
  • 模板中调用:
<?php
$meta = _g('meta_elements') ?: []; // 返回数组,例如 ['author', 'date', 'views']
if (in_array('views', $meta)) {
echo '<span>浏览量:' . $value['views'] . '</span>';
}
?>

开关(checkon)​

滑动开关按钮(Toggle Switch),适合二元开关控制(开启 / 关闭)。开启时值为 '1',关闭未勾选时为空或 '0'。

  • 支持属性:
    • name: 选项标题
    • values: 开启时的值,通常设为 ['1' => '开启']
    • default: 默认值,'1' 表示开启,'0' 表示关闭
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
'enable_dark_mode' => [
'labels' => 'tpl-appearance',
'type' => 'checkon',
'name' => '是否开启夜间模式切换',
'values' => ['1' => '开启'],
'default' => '1',
'description' => '开启后前台顶部导航将显示明暗主题切换开关',
],
  • 模板中调用:
<?php
$dark_mode = _g('enable_dark_mode'); // 开启返回 "1",关闭返回空或 "0"
if ($dark_mode == '1') {
// 渲染明暗主题切换按钮
}
?>

文本输入框(text)​

单行文本输入框或多行文本域(Textarea)。设置 multi => true 即可渲染为多行文本域。

  • 支持属性:
    • name: 选项标题
    • multi: 是否为多行文本(布尔值或 'true',默认单行)
    • default: 默认文本
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
// 单行文本输入
'contact_email' => [
'labels' => 'tpl-head',
'type' => 'text',
'name' => '站长联系邮箱',
'default' => 'admin@example.com',
'description' => '展示在页面底部的联系邮箱',
],

// 多行文本域
'footer_custom_code' => [
'labels' => 'tpl-head',
'type' => 'text',
'multi' => true,
'name' => '页脚自定义统计/脚本代码',
'default' => '',
'description' => '可填入第三方网站统计代码或自定义 JavaScript 脚本',
],
  • 模板中调用:
// 输出单行文本
<a href="mailto:<?= _g('contact_email') ?>"><?= _g('contact_email') ?></a>

// 输出多行代码/统计脚本
<?= _g('footer_custom_code') ?>

颜色选择器(color)​

原生调色板选择器,用户可点击弹窗选取色彩或输入 Hex 颜色值。

  • 支持属性:
    • name: 选项标题
    • default 或 values: 默认色值(如 '#006fff')
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
'primary_color' => [
'labels' => 'tpl-appearance',
'type' => 'color',
'name' => '网站主题主色调',
'default' => '#006fff',
'description' => '用于全站主要按钮、高亮链接及选中状态的强调色',
],
  • 模板中调用:
<?php $primary = _g('primary_color') ?: '#006fff'; ?>
<style>
:root {
--theme-primary: <?= $primary ?>;
}
</style>

图片上传与选择(image)​

全功能图片选择组件,同时支持“系统媒体库模态框选择”、“直接从本地上传”以及“手动输入外链图片 URL”。

  • 支持属性:
    • name: 选项标题
    • default 或 values: 默认图片 URL
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
'site_logo' => [
'labels' => 'tpl-head',
'type' => 'image',
'name' => '站点LOGO',
'default' => TEMPLATE_URL . 'images/logo.png',
'description' => '推荐上传尺寸 200x50 像素透明背景 PNG 或 SVG 图片',
],
  • 模板中调用:
<?php $logo = _g('site_logo'); ?>
<img src="<?= $logo ?>" alt="<?= $blogname ?>">

分类选择(sort)​

自动读取站点所有分类列表供用户选择。支持单选以及多选(设置 multi => true)。

  • 支持属性:
    • name: 选项标题
    • multi: 是否支持多选(布尔值或 'true')
    • default: 默认选中的分类 ID(多选时为数组,单选时为字符串)
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
// 单选分类
'featured_sort' => [
'labels' => 'tpl-head',
'type' => 'sort',
'name' => '首页头条聚焦分类',
'description' => '选择一个分类作为首页重点推荐栏目展示',
],

// 多选分类
'slider_exclude_sorts' => [
'labels' => 'tpl-head',
'type' => 'sort',
'multi' => true,
'name' => '首页幻灯片排除分类',
'description' => '勾选不需要出现在首页顶部幻灯片中的分类',
],
  • 模板中调用:
// 单选:返回分类 ID 字符串,例如 "2"
$featured_sid = _g('featured_sort');

// 多选:返回分类 ID 数组,例如 ["1", "3"]
$exclude_sids = _g('slider_exclude_sorts') ?: [];

页面选择(page)​

自动读取站点已发布的独立自定义页面供用户选择,支持单选与多选(multi => true)。

  • 支持属性:
    • name: 选项标题
    • multi: 是否支持多选(布尔值或 'true')
    • default: 默认选中的页面 ID
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
'about_page' => [
'labels' => 'tpl-head',
'type' => 'page',
'name' => '关于我们关联页面',
'description' => '选择作为页头或页脚“关于我们”跳转的目标独立页面',
],
  • 模板中调用:
<?php
$about_page_id = _g('about_page'); // 返回页面 ID 字符串,例如 "5"
?>

标签选择(tag)​

自动读取站点的所有文章标签并展示使用频率计数,以复选框形式供用户挑选。

  • 支持属性:
    • name: 选项标题
    • default: 默认勾选的标签名数组
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
'hot_tags' => [
'labels' => 'tpl-head',
'type' => 'tag',
'name' => '首页推荐标签',
'description' => '挑选显示在搜索框下方或首页侧边栏的热门标签',
],
  • 模板中调用:
<?php
$tags = _g('hot_tags') ?: []; // 返回标签名数组,例如 ["PHP", "Emlog", "教程"]
foreach ($tags as $tag_name) {
echo '<a href="' . BLOG_URL . '?tag=' . urlencode($tag_name) . '">' . htmlspecialchars($tag_name) . '</a>';
}
?>

关联搜索选择(select)​

带实时动态模糊搜索的关联选择器,支持从海量数据中精确搜索并关联特定的文章(post)、分类(cate)或页面(page)。

  • 支持属性:
    • name: 选项标题
    • pattern: 必填项,可选:
      • 'post': 搜索文章(输入文章标题实时联想)
      • 'cate': 搜索分类
      • 'page': 搜索页面
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
'home_top_post' => [
'labels' => 'tpl-head',
'type' => 'select',
'pattern' => 'post',
'name' => '首页头条特荐文章',
'description' => '输入文章标题关键字搜索并选择推荐文章',
],
  • 模板中调用:
<?php
// 返回选中的文章 ID 数组,例如 ["12", "34"]
$top_post_ids = _g('home_top_post') ?: [];
if (!empty($top_post_ids)) {
// 遍历文章 ID 获取文章数据并展示
}
?>

多内容块(block)​

支持在后台自由新增、拖拽排序、删除条目的多内容容器。支持两种模式:

  1. 图文/图片模式(pattern => 'image'):每项包含标题输入框与图片上传/选择框。
  2. 文本模式(未设置 pattern 或为纯文本):每项包含标题输入框与单行内容输入框(或设置 multi => true 展开为多行文本域)。
  • 支持属性:
    • name: 选项标题
    • pattern: 可选 'image'(图片块模式)
    • multi: 是否为多行文本域(仅文本模式有效)
    • placeholder: 关联数组,自定义输入框占位提示,如 ['title' => '标题', 'content' => '内容/图片']
    • description: 描述说明(可选)
    • labels: 所属 Tab 分组名称
// 图片轮播图内容块
'home_slider' => [
'labels' => 'tpl-head',
'type' => 'block',
'pattern' => 'image',
'name' => '首页轮播幻灯片',
'placeholder' => [
'title' => '幻灯片标题/跳转URL',
'content' => '图片地址(点击选择或上传)',
],
'description' => '自由添加多张轮播图,支持上下拖拽排序',
],

// 常见问题(FAQ)多行文本块
'home_faq' => [
'labels' => 'tpl-head',
'type' => 'block',
'multi' => true,
'name' => '常见问题解答(FAQ)',
'placeholder' => [
'title' => '问题描述',
'content' => '问题解答正文',
],
],
  • 模板中调用: 使用专用辅助方法 _getBlock($key, $type):
    • $key: 设置项名称(例如 'home_slider')
    • $type: 可选 'title'(获取标题数组)或 'content'(获取内容/图片 URL 数组,缺省默认为 'content')
<?php
$titles = _getBlock('home_slider', 'title'); // 获取标题数组
$images = _getBlock('home_slider', 'content'); // 获取图片URL数组

if (!empty($images)) {
foreach ($images as $index => $img_url) {
$title = $titles[$index] ?? '';
echo '<div class="slide-item">';
echo '<img src="' . htmlspecialchars($img_url) . '" alt="' . htmlspecialchars($title) . '">';
echo '<h3>' . htmlspecialchars($title) . '</h3>';
echo '</div>';
}
}
?>

提醒条(notice)​

用于在模板设置页面展示大块引导、功能说明或重要警示卡片。此类型仅用于界面展示,不保存用户数据。

  • 支持属性:
    • style: 样式类型,可选 info(信息蓝,默认)、success(成功绿)、warning(警告黄)、danger(危险红)、normal(常规灰)
    • name: 提醒标题(可选)
    • content: 提醒正文内容(支持 HTML 格式)
    • description: 补充描述说明(可选)
'demo_notice' => [
'labels' => 'tpl-head',
'type' => 'notice',
'style' => 'info',
'name' => '配置说明',
'content' => '欢迎使用本主题,请按照各模块指引完成站点基础信息及色彩样式的个性化配置。',
],

小提醒(submessage)​

紧凑型的单行或内联提示,左侧带状态色条,适合放置在某些具体设置项上方作轻量注意事项或配置指导。此类型仅用于界面展示,不保存用户数据。

  • 支持属性:
    • style: 样式类型,可选 normal(常规灰,默认)、info(信息蓝)、success(成功绿)、warning(警告黄)、danger(危险红)
    • content: 提示内容(若未指定则取 name)
'demo_submessage' => [
'labels' => 'tpl-head',
'type' => 'submessage',
'style' => 'success',
'content' => '提示:开启图片异步懒加载后,可大幅降低首屏渲染资源消耗。',
],

数字输入框(number)​

专用的数字数值输入框(相较以往 type => text 搭配 pattern => num 更加规范标准),支持设置数值上下限(min/max)、递增步长(step)以及输入框右侧的后缀单位标识。

  • 支持属性:
    • min: 允许输入的最小值
    • max: 允许输入的最大值
    • step: 步长(例如 1 或小数 0.1,缺省为 any)
    • unit: 数值后缀单位(如 篇、px、秒、%)
    • placeholder: 输入框占位文本
    • default: 默认数值
'page_posts_num' => [
'labels' => 'tpl-head',
'type' => 'number',
'name' => '列表每页文章数',
'description' => '设置首页及分类列表每页展示的文章篇数(1-100篇)',
'min' => 1,
'max' => 100,
'step' => 1,
'unit' => '篇',
'default' => '10',
],
  • 模板中调用:
<?php
$posts_per_page = _g('page_posts_num'); // 返回数值字符串,例如 "10"
?>

滑块控件(slider)​

拖动滑块与右侧数字输入框双向实时联动,用户既可快速滑动调节,也能精确输入具体数值,非常适用于圆角弧度、透明度、比例等设置。

  • 支持属性:
    • min: 最小值(默认 0)
    • max: 最大值(默认 100)
    • step: 步长(默认 1)
    • unit: 后缀单位(如 px、%)
    • default: 默认值
'card_radius' => [
'labels' => 'tpl-appearance',
'type' => 'slider',
'name' => '列表卡片圆角弧度',
'description' => '拖动滑块或在右侧数字框输入,实时双向联动更新',
'min' => 0,
'max' => 50,
'step' => 1,
'unit' => 'px',
'default' => '8',
],
  • 模板中调用:
<?php
$card_radius = _g('card_radius'); // 返回数值字符串,例如 "8"
?>
<style>
.card {
border-radius: <?= $card_radius ?>px;
}
</style>

日期选择器(date)​

内嵌日历选择交互控件,不仅支持单个日期选择,还支持起止范围区间(from_to)选择。

  • 支持属性:
    • from_to: 是否启用日期区间(布尔值,true 启用区间,false 单日期,默认 false)
    • text_from: 区间起始前缀标签文案(默认 '从')
    • text_to: 区间截止前缀标签文案(默认 '到')
    • default: 默认日期。单日期填字符串(如 '2026-12-31');区间模式填关联数组(如 ['from' => '2026-10-01', 'to' => '2026-10-31'])
// 单日期模式
'event_deadline' => [
'labels' => 'tpl-head',
'type' => 'date',
'name' => '活动截止日期',
'description' => '选择活动截止时间',
'default' => '2026-12-31',
],

// 日期范围模式
'campaign_period' => [
'labels' => 'tpl-head',
'type' => 'date',
'name' => '活动起止时间范围',
'description' => '支持起止范围区间选择(from_to)',
'from_to' => true,
'text_from' => '开始',
'text_to' => '结束',
'default' => [
'from' => '2026-10-01',
'to' => '2026-10-31',
],
],
  • 模板中调用:
<?php
// 单日期调用
$deadline = _g('event_deadline'); // 输出 "2026-12-31"

// 日期区间调用
$period = _g('campaign_period');
$start_date = $period['from'] ?? '';
$end_date = $period['to'] ?? '';
?>

专用于自定义导航、横幅宣传、友情推荐等链接配置场景,将“链接文字”、“链接网址(URL)”以及“在新标签页中打开(target="_blank")”聚合为一个控件。

  • 支持属性:
    • default: 关联数组,包含 text、url、target(可选 '_blank' 或 '_self')
'banner_link' => [
'labels' => 'tpl-head',
'type' => 'link',
'name' => '首页横幅链接',
'description' => '包含链接文字、链接网址以及在新标签页中打开',
'default' => [
'text' => 'Emlog 官网',
'url' => 'https://www.emlog.net',
'target' => '_blank',
],
],
  • 模板中调用:
<?php $link = _g('banner_link'); ?>
<?php if (!empty($link['url'])): ?>
<a href="<?= $link['url'] ?>" target="<?= $link['target'] ?>"><?= $link['text'] ?></a>
<?php endif; ?>

专用于配置超链接不同伪类/交互状态的色彩集合,内置调色板拾取器与 Hex 色值输入。

  • 支持属性:
    • color: 是否启用常规状态颜色(布尔值,默认 true)
    • hover: 是否启用悬浮态颜色(布尔值,默认 true)
    • active: 是否启用激活/点击态颜色(布尔值,默认 false)
    • visited: 是否启用已访问态颜色(布尔值,默认 false)
    • focus: 是否启用聚焦态颜色(布尔值,默认 false)
    • default: 各激活状态对应默认色值的关联数组
'theme_link_colors' => [
'labels' => 'tpl-appearance',
'type' => 'link_color',
'name' => '超链接多状态颜色',
'description' => '支持常规、悬浮、激活等多状态色彩配置',
'color' => true,
'hover' => true,
'active' => true,
'default' => [
'color' => '#1a73e8',
'hover' => '#1557b0',
'active' => '#0d47a1',
],
],
  • 模板中调用:
<?php $lc = _g('theme_link_colors'); ?>
<style>
a { color: <?= $lc['color'] ?>; }
a:hover { color: <?= $lc['hover'] ?>; }
<?php if (!empty($lc['active'])): ?>
a:active { color: <?= $lc['active'] ?>; }
<?php endif; ?>
</style>

间距组件(spacing)​

用于配置内边距(Padding)或外边距(Margin)。支持四边统一设置,或上、右、下、左四个方向独立输入,并支持单位选择(px、%、rem、em 等)。

  • 支持属性:
    • all: 布尔值。设为 true 时为“四边统一”输入框;设为 false(默认)时提供上、右、下、左 4 个独立输入框
    • units: 允许切换的单位数组,例如 ['px', '%', 'rem', 'em']。若仅配置 1 个单位则固定该单位,不显示下拉框
    • default: 默认值关联数组:
      • 四边独立模式:['top' => '16', 'right' => '20', 'bottom' => '16', 'left' => '20', 'unit' => 'px']
      • 四边统一模式:['all' => '20', 'unit' => 'px']
'container_padding' => [
'labels' => 'tpl-appearance',
'type' => 'spacing',
'name' => '页面容器内边距(Padding)',
'description' => '支持独立配置上、右、下、左间距及单位选择',
'units' => ['px', '%', 'rem'],
'default' => [
'top' => '16',
'right' => '20',
'bottom' => '16',
'left' => '20',
'unit' => 'px',
],
],
  • 模板中调用:
<?php $sp = _g('container_padding'); ?>
<style>
.container {
padding: <?= "{$sp['top']}{$sp['unit']} {$sp['right']}{$sp['unit']} {$sp['bottom']}{$sp['unit']} {$sp['left']}{$sp['unit']}" ?>;
}
</style>

边框组件(border)​

综合边框配置器,集成边框粗细、线型样式(实线 solid、虚线 dashed、点线 dotted、双线 double、3D内嵌 inset、3D突出 outset、无 none)以及边框颜色取色器。

  • 支持属性:
    • all: 布尔值,设为 true(默认)为四边统一粗细;设为 false 则支持上、右、下、左分别独立设置粗细
    • unit: 粗细单位(默认 'px')
    • default: 关联数组,包含 all(或 top/right/bottom/left)、style、color
'card_border' => [
'labels' => 'tpl-appearance',
'type' => 'border',
'name' => '卡片边框样式',
'description' => '支持边框粗细、线型样式(实线/虚线/点线等)以及边框颜色',
'all' => true,
'unit' => 'px',
'default' => [
'all' => '1',
'style' => 'solid',
'color' => '#e2e8f0',
],
],
  • 模板中调用:
<?php $border = _g('card_border'); ?>
<style>
.card {
border: <?= $border['all'] ?>px <?= $border['style'] ?> <?= $border['color'] ?>;
}
</style>

背景组件(background)​

全功能背景样式配置器,包含:背景颜色、背景图片(支持系统媒体库弹窗选择与本地文件上传)、平铺模式(repeat)、对齐位置(position)、尺寸大小(size)以及附着方式(attachment)。在读取背景图片 URL 时系统会自动拼接为完整绝对路径。

  • 支持属性:
    • default: 关联数组,包含以下 6 个键:
      • background-color: 背景色 Hex 值(如 '#f8fafc')
      • background-image: 背景图片地址
      • background-repeat: 平铺方式(可选 no-repeat、repeat、repeat-x、repeat-y)
      • background-position: 对齐位置(如 center center、left top、center top 等)
      • background-size: 尺寸大小(可选 cover、contain、auto、100% 100%)
      • background-attachment: 附着方式(可选 scroll 随页面滚动、fixed 固定背景)
'site_background' => [
'labels' => 'tpl-appearance',
'type' => 'background',
'name' => '全局背景配置',
'description' => '支持背景色、背景图上传、平铺模式、对齐位置与附着方式',
'default' => [
'background-color' => '#f8fafc',
'background-image' => '',
'background-repeat' => 'no-repeat',
'background-position' => 'center center',
'background-size' => 'cover',
'background-attachment' => 'scroll',
],
],
  • 模板中调用:
<?php $bg = _g('site_background'); ?>
<style>
body {
background-color: <?= $bg['background-color'] ?>;
<?php if (!empty($bg['background-image'])): ?>
background-image: url('<?= $bg['background-image'] ?>');
background-repeat: <?= $bg['background-repeat'] ?>;
background-position: <?= $bg['background-position'] ?>;
background-size: <?= $bg['background-size'] ?>;
background-attachment: <?= $bg['background-attachment'] ?>;
<?php endif; ?>
}
</style>

为设置菜单增加图标​

TplOptionsNavi项内可加入图标icons数组,为你的主题设置侧边栏菜单父设置名称前增加图标。icons数组的键名和TplOptionsNavi项values数组一致。使用的是Remixicon ,去图标站点找到合适的图标,复制其class内的属性值即可,例如class="ri-home-line" ,只需复制ri-home-line即可。另外需在模板plugins.php内加入以下代码用于引入图标CSS。

function optionIconFont() {
echo sprintf('<link rel="stylesheet" href="%s">', 'https://cdn.bootcdn.net/ajax/libs/remixicon/3.5.0/remixicon.min.css?ver=' . Option::EMLOG_VERSION_TIMESTAMP);
}
addAction('adm_head', 'optionIconFont');

模板里如何调用设置项​

插件提供简单方法 _g($key) 或 _em($key),来获取设置,以_g($key)为例如:

  • 使用_g('sidebar')来获取侧边栏的设置,取到的值将为0或者1,
  • 使用_g('sortIcon')来获取分类icon的全部设置,以分类id为key的数组,
  • 使用_g('sortIcon.1')来获取分类id为1(如果存在)的sortIcon。需要注意的是,对于类型为page的,将取到页面id,类型为sort的,将取到分类id,类型为tag的,将取到标签名。

若不传递参数,即使用 _g() 方法将获取到所有设置项,对于老的模板迁移来的,可以用extract( _g() );来代替原来的加载option文件。

示例如下: 来自默认主题设置站点 logo 的配置


<?php if (_g('logotype') == 1): ?>
<a class="blog-header-title" href="<?= BLOG_URL ?>"><?= $blogname ?></a>
<div class="blog-header-subtitle subtitle-overflow" title="<?= $bloginfo ?>"><?= $bloginfo ?></div>
<?php else: ?>
<a href="<?php echo BLOG_URL; ?>" title="<?php echo $bloginfo; ?>"><img src="<?php echo _g('logoimg'); ?>" alt="<?php echo $blogname; ?>"/></a>
<?php endif; ?>

如需获取多内容块的数据,提供_getBlock($key, $type)方法获取:

  • $key同_g()方法提供的参数
  • $type是多内容块的数据类型,分为title和content,此参数可缺省,默认会获取content。title是多内容块填入的标题。content即内容,使用内置该函数可获取多内容块文本类型的文本或多内容块图片类型设置的图片URL
  • 返回值类型为array

使用案例:

_getBlock('image-block', 'content')

可以直接使用的常量​

变量、常量类型说明
Option::EMLOG_VERSION常量获得当前emlog版本号
ROLE常量当前用户角色(用户组):admin 管理员、writer 注册用户 、visitor 访客
ROLE_ADMIN常量admin 管理员
ROLE_WRITER常量writer 注册用户
ROLE_VISITOR常量visitor 访客
UID常量当前用户UID
BLOG_URL常量站点URL
ISLOGIN常量是否登录状态,true登录 false未登录
TEMPLATE_URL常量当前模板的URL eg: http://localhost:8080/content/templates/default/
TEMPLATE_PATH常量当前模板的绝对路径 eg:/www/emlog/content/templates/default/

上面的常量可以通过下面的方式在模板中使用

// 输出当前站点网址
<?= BLOG_URL ?>

常用配置信息获取​

配置项获取示例
站点标题Option::get('blogname')
站点副标题Option::get('bloginfo')
站点meta信息:titleOption::get('site_title')
站点meta信息:descriptionOption::get('site_description')
站点meta信息:keywordOption::get('site_key')
站点URLOption::get('blogurl')

使用示例:

// 输出当前站点名称
<?= Option::get('blogname')?>

常用方法&函数​

可以直接使用的方法和函数:通用方法和函数

异步请求​

pro版本支持ajax异步请求并返回json格式信息,方便用户构建评论、弹窗登录、注册、找回密码等更友好的前台交互体验。

发布评论​

用户登录​

用户注册​

找回密码​

文章搜索​

搜索路由:https://yoursite_domain/?keyword=emlog&sid=1

  • keyword:搜索关键词
  • sid:分类id,可选,填写后只搜索该分类下的文章,主题可以自行实现按分类搜索。

评论支持UBB​

emlog评论支持UBB标签短代码解析,用户可以在评论中使用UBB标签来格式化评论内容,如粗体、颜色、图片、链接。开发者可以开发支持插入UBB代码的评论输入框,来提供更丰富的评论体验。

目前支持的UBB标签短代码如下,粗体、颜色、链接、图片:

[b]text[/b]
[color=red]text[/color]
[url]http://example.com[/url]
[img]http://example.com/xxx.jpg[/img]

参考demo​

emlog系统自带的默认主题就是最好的演示demo,可以基于该主题进行修改来开发自己的主题,或者参考该主题的部分元素和文件。 默认模板所在目录: content/templates/default

开源发布​

如果你开发的模板在 Github 开源,那请为仓库添加topic: emlog-template

发布到应用商店​

制作好的主题,经过测试后就可以打包发布到官网的应用商店了。

  1. 打包:来到content\templates 目录下,找到模板的文件夹,直接使用zip压缩工具打包这个文件夹(注意不要进到文件夹内打包),并将打包后的压缩包命名为 :模板英文别名.zip,如 default.zip
  2. 发布:登录官网emlog.net - 我的 - 应用开发 - 发布模板,按照提示填写必要的信息即可发布,等待审核。