系统主题

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

主题模块开发教程

模板主题是一个模块，以 CmsTheme 或者 BlogTheme 开头，如 CmsThemeBlue、CmsThemeGreen、BlogThemeXxx 等。

主题模块结构

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开发测试主题），用户点击初始化演示数据，勾选需要初始化的数据，即可完成数据填充。

演示数据参考配置

数据参考配置位于模块根目录下的，如 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>',
            ]
        ],
    ],
];