4.2. 主题模块开发

未匹配的标注

系统主题

主题模块是特殊的功能模块,所有功能基础请参考 普通模块开发

主题模块开发教程

模板主题是一个模块,以 CmsTheme 或者 BlogTheme 开头,如 CmsThemeBlueCmsThemeGreenBlogThemeXxx 等。

主题模块结构

CmsThemeMyTest
├── Admin
│     ├── Controller
│     │     └── ConfigController.php             → 后台配置文件
│     └── routes.php
├── Asset                                        → 主题资源文件
│     ├── css
│     │     └── theme.css
│     └── js
│         └── theme.js
├── Core
│     └── ModuleServiceProvider.php              → 模块核心注册器
├── Docs                                         → 模块文档
│     ├── doc
│     │     └── Manual.md
│     ├── module
│     │     ├── content.md
│     │     ├── demo.md
│     │     ├── mobilePreview.md
│     │     └── preview.md
│     └── release
│         └── 1.0.0.md
├── Provider
│     └── ThemeSiteTemplateProvider.php         → 主题注册器
├── View                                        → 模块视图主目录
│     └── pc                                    → 自适应默认为PC
│         ├── cms
│         │     ├── list                        → 列表视图
│         │     │     ├── cases.blade.php
│         │     │     ├── default.blade.php
│         │     │     ├── job.blade.php
│         │     │     ├── news.blade.php
│         │     │     └── product.blade.php
│         │     ├── detail                      → 详情视图
│         │     │     ├── cases.blade.php
│         │     │     ├── default.blade.php
│         │     │     ├── job.blade.php
│         │     │     ├── news.blade.php
│         │     │     └── product.blade.php
│         │     ├── form                        → 表单视图
│         │     │     └── default.blade.php
│         │     ├── page                        → 单页视图
│         │     │     └── default.blade.php
│         │     ├── index.blade.php
│         ├── footer.blade.php
│         ├── frame.blade.php                   → 模板框架视图
│         └── header.blade.php
├── config.json                                 → 模块配置文件
└── demo_data.php                               → 演示数据初始化

系统默认主题为 default 可以通过 modstart_config('siteTemplate') 获取系统当前主题。

  • 系统视图根目录:resources/views/theme/
  • 主题模块的视图根目录通常位于:module/Xxx/View/

如何开发主题模块

第一步,实现一个主题模块提供者

<?php
namespace Module\MyTestTheme\Core;

use Module\Vendor\Provider\SiteTemplate\AbstractSiteTemplateProvider;

class ThemeSiteTemplateProvider extends AbstractSiteTemplateProvider
{
    const NAME = 'myTestTheme';

    public function name()
    {
        return self::NAME;
    }

    public function title()
    {
        return '我的测试主题';
    }

    public function root()
    {
        return 'module::MyTestTheme.View';
    }

}

第二步,注册主题模块到系统中

<?php
namespace Module\MyTestTheme\Core;

use Illuminate\Events\Dispatcher;
use Illuminate\Support\ServiceProvider;
use Module\Vendor\Provider\SiteTemplate\SiteTemplateProvider;

class ModuleServiceProvider extends ServiceProvider
{
    public function boot(Dispatcher $events)
    {
        SiteTemplateProvider::register(ThemeSiteTemplateProvider::class);
    }
}

第三步,按照需要提供的视图结构完成视图开发

如,Xxx 模块中调用了 $this->view('news.list') 来渲染视图,如果需要重新覆盖这个页面,复制当前页面视图文件(通常位于 module/Xxx/View/pc/news/list.blade.php)放到 module/MyTestTheme/View/pc/news/list.blade.php 重新开发样式,如果用户启用的 MyTestTheme 模块主题,系统将会使用已开发的新样式,未覆盖的页面将会使用老的样式。

视图渲染查找顺序

主题的视图文件( .blade.php 结尾)可能出现在多个位置,系统在渲染视图的时候会按照以下优先级查找直到匹配成功:

  1. 启用主题自定义视图目录:如 resources/views/theme/<主题>
  2. 当前主题主题模块视图目录:如 module/<主题模块>/View(这里假设主题模块的主题根目录为 module/<主题模块>/View
  3. 系统默认视图目录:如 resources/views/theme/default
  4. 当前模块视图目录:如 module/Xxx/View

举例说明:
当前系统启用 myTest 主题模块,主题根目录位于 module/MyTest/View,在 Xxx 模块中调用 $this->view('test.list.news')
系统会按照如下顺序进行视图文件的查找,优先使用第一个匹配到的文件:

  1. resources/views/theme/myTest/pc/test/list/news.blade.php
  2. module/MyTest/View/test/list/news.blade.php
  3. resources/views/theme/default/pc/test/list/news.blade.php
  4. module/Xxx/View/pc/test/list/news.blade.php

自适应的设备视图

ModStart的View根据访问设备的不同,会启用不同的视图文件,具体逻辑可参照 \ModStart\Core\View\ResponsiveViewTrait 中的逻辑。

  • PC端使用 pc/ 中的视图
  • 手机端使用 m/ 中的视图
  • 当手机端视图不存在时,会自动降级使用 pc/ 中的视图

定义一个视图例子

@extends($_viewFrame)
@section('pageTitleMain')我的视图标题@endsection
@section('bodyContent')
    <div class="ub-container">
        我的视图文件
    </div>
@endsection

其中:

  • $_viewFrame 变量表示当前系统使用的框架视图
  • @section('pageTitleMain') 为系统标题
  • @section('bodyContent') 为系统正文内容部分

网站主色调

可以通过 CSS 的变量 var(--color-primary) 获取,该变量会根据用户后台设置的主色调来动态改变。

内置变量说明

_viewFrame 框架视图文件

通过会在 blade 模板文件中看到 @extends($_viewFrame) 来确定当前模板的框架视图,该文件通常包含公共的头部、尾部、侧边栏等内容。

$_viewFrame 会根据当前模板查找最先匹配到的文件,查找顺序参考视图渲染查找顺序

通常情况下,该变量会按照如下顺序查找:

  1. 当前主题视图根目录的框架视图文件,可能为以下路径中的一个
    • resources/views/theme/<主题>/pc/frame.blade.php
    • module/<主题模块>/View/pc/frame.blade.php
  2. 如果主题未定义框架视图文件,会使用系统默认视图目录
    • resources/views/theme/default/pc/frame.blade.php

常见 @section 说明

系统约定了一些模板 @section ,在开发时候请遵守约定,以便系统能够正确的渲染模板。

  • @section('pageTitleMain'):系统标题,该标题后会自动补全网站主名称
  • @section('pageKeywords'):网站关键字
  • @section('pageDescription'):网站描述
  • @section('bodyContent'):系统正文内容部分,不包含公共的头部、尾部、侧边栏等内容
  • @section('body'):系统 body 标签的内容,会自动移除 body 标签中已有的内容
  • @section('headAppend'):追加到 head 标签的内容
  • @section('bodyAppend'):追加到 body 标签的内容

以上的 section 定义用法示例如下

@section('pageTitleMain')我的视图标题@endsection
@section('pageKeywords')我的视图关键字@endsection
@section('pageDescription')我的视图描述@endsection
@section('bodyContent')
    <div class="ub-container">
        我的视图内容
    </div>
@endsection
@section('body')
    <div class="ub-container">
        我的视图内容
    </div>
@endsection
@section('headAppend')
    @parent
    <script src="xxx"></script>
@endsection
@section('bodyAppend')
    @parent
    <script src="xxx"></script>
@endsection

如何自定义头部和尾部

在主题根目录覆盖系统默认的 pc/frame.blade.php 框架视图文件,该文件会包含公共的头部、尾部、侧边栏等内容。

如果是主题模块,该文件将会是 module/<主题模块>/View/pc/frame.blade.php

如果是普通应用主题,该文件将会是 resources/views/theme/<主题>/pc/frame.blade.php

演示数据

一个优秀的主题需要携带完整的演示数据,这样可以方便快捷的让用户快速的看到主题最终效果。

演示数据开启

CMS集成了演示数据初始化填充功能,只需要简单的配置即可完成。

在对应的主题设置页面(如 功能设置 → 主题设置 → CMS开发测试主题),用户点击初始化演示数据,勾选需要初始化的数据,即可完成数据填充。

演示1

演示2

演示数据参考配置

数据参考配置位于模块根目录下的,如 module/CmsThemeMyTest/demo_data.php

<?php
return [
    'tables' => [
        'banner' => [
            'where' => [
                'position' => 'home',
            ],
            'records' => [
                [
                    'type' => \Module\Banner\Type\BannerType::IMAGE,
                    'image' => 'vendor/CmsThemeMyTest/image/banner-1.jpg',
                ],
                // ...
            ]
        ],
        'news' => [
            'records' => [
                [
                    'title' => '演示新闻标题',
                    'cover' => 'vendor/CmsThemeMyTest/image/news-1.jpg',
                    'summary' => '演示新闻描述',
                    '_data' => [
                        'content' => '<p>演示新闻内容</p>',
                    ]
                ],
                // ...
            ]
        ],
        'product' => [
            'records' => [
                [
                    'title' => '演示产品',
                    'cover' => 'vendor/CmsThemeMyTest/image/product-1.jpg',
                ],
                // ...
            ]
        ],
        'cases' => [
            'records' => [
                [
                    'title' => '演示案例',
                    'cover' => 'vendor/CmsThemeMyTest/image/cases-1.jpg',
                ],
                // ...
            ]
        ],
        'job' => [
            'records' => [
                [
                    'title' => '演示招聘',
                    '_data' => [
                        'content' => '<p>演示招聘说明</p>',
                    ]
                ]
            ]
        ],
        'nav' => [
            'where' => [
                'position' => 'head',
            ],
            'records' => [
                [
                    'name' => '产品',
                    'link' => modstart_web_url('product'),
                ],
                // ...
            ],
        ],
        'info' => [
            'records' => [
                'Cms_HomeInfoImage' => 'vendor/CmsThemeMyTest/image/about.jpg',
                'Cms_HomeInfoTitle' => '演示公司名称',
                'Cms_HomeInfoContent' => '<p>演示公司介绍。</p>',
            ]
        ],
    ],
];

本文章首发在 LearnKu.com 网站上。

上一篇 下一篇
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上,本课程教授 Web 开发中专业、实用的技能,如 Git 工作流、Laravel Mix 前端工作流等。
《L05 电商实战》
从零开发一个电商项目,功能包括电商后台、商品 & SKU 管理、购物车、订单管理、支付宝支付、微信支付、订单退款流程、优惠券等
讨论数量: 0
发起讨论 只看当前版本


暂无话题~