主题

主题会改变你网站的外观。最简单的形式是主题生成你扩展内容输出的周围HTML标记。

注释

本教程中的示例取自Hello主题，该主题可在市场中获得。安装后，Hello 主题位于。/packages/pagekit/theme-hello

封装定义

主题是一个常规的 Pagekit 包，类型为。每个包裹都需要描述，才能被 Pagekit 识别。这份描述位于文件中，内容如下。详细信息请参阅“套餐”章节。pagekit-themecomposer.json

{
    "name": "pagekit/theme-hello",
    "type": "pagekit-theme",
    "version": "0.9.0",
    "title": "Hello"
}

模定义

主题本身就是一个模块。所以你可能想先了解模块。这为主题能发挥的潜力打开了许多可能性。

定义主题的位置和菜单，加载更多脚本，以及更多功能。这里有一个简短的示例，帮助你入门。以下是对主题特定属性的说明。index.php


return [

    'name' => 'theme-hello',

    /**
     * Define menu positions.
     */
    'menus' => [

        'main' => 'Main',

    ],

    /**
     * Define widget positions.
     */
    'positions' => [

        'sidebar' => 'Sidebar',

    ]

];

你的主题定义了渲染菜单和控件的位置。实际渲染发生在中，如下所示。不过，你的主题需要先识别这些位置。这种情况发生在和财产上。这些文件包含职位名称的数组和一个标签，标签会显示在管理面板中。template.phpmenuspositions

菜单

在你的主题中，你可以根据Pagekit系统渲染菜单，按你想要的多个位置。要让这些职位让Pagekit知道，你需要用该网站注册。menus

每个菜单位置由标识符（例如）和一个需要显示给用户的标签（例如：主）定义。main

'menus' => [

    'main' => 'Main',
    'offcanvas' => 'Offcanvas'

],

职位

小部件位置允许用户在主题标记的多个位置发布小部件。它们出现在 Pagekit 管理面板的 Widgets 区域，用户可以在设置 Widget 时选择。

每个小部件位置由标识符（即）和一个标签（即侧边栏）定义，供用户使用。sidebar

'positions' => [

    'sidebar' => 'Sidebar',

],

布局文件

除了必备的模块文件外，主题还会带来自己的文件。它是主题标记的主文件，包含以下可供渲染的对象。views/template.php

目标	描述
`$view`	查看渲染器实例
`$params`	主题参数
`$app`	应用容器实例

注释

在PHP模板中，简短符号打印变量的值。<?= $var ?>$var

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <!-- Always render head section from the system -->
        <?= $view->render('head') ?>

        <!-- Include theme css -->
        <?php $view->style('theme', 'theme:css/theme.css') ?>

        <!-- Include theme JS, require jQuery which will also be included -->
        <?php $view->script('theme', 'theme:js/theme.js', 'jquery') ?>
    </head>
    <body>

        <!-- Render logo with site URL -->
        <?php if ($logo = $params['logo']) : ?>
        <a href="<?= $view->url()->get() ?>">
            <img src="<?= $this->escape($logo) ?>" alt="">
        </a>
        <?php endif ?>

        <!-- Render menu position -->
        <?php if ($view->menu()->exists('main')) : ?>
            <?= $view->menu('main') ?>
        <?php endif ?>

        <!-- Render widget position -->
        <?php if ($view->position()->exists('sidebar')) : ?>
            <?= $view->position('sidebar') ?>
        <?php endif; ?>

        <!-- Render system messages -->
        <?= $view->render('messages') ?>

        <!-- Render content -->
        <?= $view->render('content') ?>

        <!-- Insert code before the closing body tag  -->
        <?= $view->render('footer') ?>

    </body>
</html>

你可能想用自定义菜单或位置渲染器。下面你会看到两个使用这些设备的示例。

<?= $view->menu('main', 'menu-navbar.php') ?>

在这种情况下，菜单会被渲染成带有布局文件的样式。mainmenu-navbar.php

<ul class="uk-navbar-nav">

    <?php foreach ($root->getChildren() as $node) : ?>
    <li>

    <!-- ... more markup ... -->

    </li>
    <?php endforeach ?>

</ul>

小部件位置也是一样的。

<?= $view->position('hero', 'position-grid.php') ?>

这里，控件位置将与布局文件一起渲染。heroposition-grid.php

<?php foreach ($widgets as $widget) : ?>
<div class="uk-width-1-<?= count($widgets) ?>">

    <div>

        <h3><?= $widget->title ?></h3>

        <?= $widget->get('result') ?>

    </div>

</div>
<?php endforeach ?>

默认 Pagekit 标记

Pagekit 管理面板是使用 UIkit 前端框架构建的。这就是为什么 Pagekit 的核心扩展，比如静态页面和博客，会用 UIkit 的 CSS 类输出标记。不过，你完全没有义务用UIkit来创建自己的主题。

要为 Pagekit 系统输出做样式，你可以只添加几个类的 CSS，而不是包含整个 UIkit CSS。Hello扩展附带的文件已经包含了必要的类。theme.css

如果你想完全改变 Pagekit 本身生成的标记，你也可以覆盖系统视图文件。

覆盖系统视图

要覆盖系统视图文件，只需在主题内创建相应文件夹，模拟原始结构，并将模板文件放入，如下表所示。

档案	原始视图文件	描述
`views/system/site/page.php`	`/app/system/site/views/page.php`	默认静态页面视图
`views/blog/post.php`	`/packages/pagekit/blog/views/post.php`	博客文章单一视图
`views/blog/posts.php`	`/packages/pagekit/blog/views/posts.php`	博客文章列表视图

要了解这些视图中有哪些变量可用，可以查看原始视图文件中的标记。

在网站界面中添加主题选项

这可以通过JavaScript实现，最方便的是使用Vue组件。

当站点树界面当前激活时，加载你自己的 JS。在你的中，当你听到合适的事件时，你可以做到这一点。index.php

'events' => [

    'view.system/site/admin/settings' => function ($event, $view) use ($app) {
        $view->script('site-theme', 'theme:js/site-theme.js', 'site-settings');
        $view->data('$theme', $this);
    },

    // ...

],

它包含一个Vue组件，负责渲染界面并存储主题设置。js/site-theme.js

注释

虽然可以在一个 JS 文件中完成所有这些，并用字符串表示标记，但最佳做法是实际创建带有 Vue 组件的文件。示例可在默认 One 主题的文件夹中找到。*.vueapp/components

window.Site.components['site-theme'] = {

    section: {
        label: 'Theme',
        icon: 'pk-icon-large-brush',
        priority: 15
    },

    template: '<div>Your form markup here</div>',

    data: function () {
        return window.$theme;
    },

    events: {

        save: function() {

            var config = _.omit(this.config, ['positions', 'menus', 'widget']);

            this.$http.post('admin/system/settings/config', {name: this.name, config: config}).error(function (data) {
                this.$notify(data, 'danger');
            });

        }

    }

};

在站点树的节点配置中添加一个主题标签

通常你想把主题选项附加到站点树中的某个节点上。例如，你希望允许用户选择一张英雄图片，而每个页面的图片可以不同。为此，我们可以在网站界面中添加一个主题标签。

'events' => [

    // ...

    'view.system/site/admin/edit' => function ($event, $view) {
        $view->script('node-theme', 'theme:js/node-theme.js', 'site-edit');
    },

    // ...
];

示例：js/node-theme.js

window.Site.components['node-theme'] = {

    section: {
        label: 'Theme',
        priority: 90
    },

    props: ['node'],

    template: '<div>Your form markup here</div>'

};

注释

和默认One主题文件夹里的完整Vue组件做对比。app/components

在小部件编辑视图中注册脚本加载。

'view.system/widget/edit' => function ($event, $view) {
    $view->script('widget-theme', 'theme:app/bundle/widget-theme.js', 'widget-edit');
},

示例：widget-theme.js

window.Widgets.components['widget-theme'] = {

    section: {
        label: 'Theme',
        priority: 90
    },

    props: ['widget', 'config'],

    template: '<div>Your form markup here</div>'

};

注释

和默认One主题文件夹里的完整Vue组件做对比。app/components

手动添加设置界面

如果预备的设置界面添加方式无法满足你的需求，你也可以手动创建一个全新的界面。有了文件中的模块定义，你可以完全控制，可以做以下作：index.php

为设置界面创建一个视图文件。
创建一个新的控制器，并带有渲染视图文件的动作。
在你的index.php
可选：将属性设置为新的设置界面路径settings

主题