模块

Pagekit 使用模块来设置应用程序代码。模块定义用于提供引导、路由及其他配置选项。在这里你可以监听事件，添加自定义类和自己的控制器。

定义：index.php

为了加载和配置模块，Pagekit 配备了 ModuleManager。它会在模块目录根中寻找文件，并期望返回一个PHP数组。可以把这个数组看作模块代码的引导。index.php

通过在该数组中设置正确的属性，你就能告诉 Pagekit 关于你的模块所需的一切信息。

<?php

/*
 * Return a php array which is the module definition.
 */
return [

    // Required: Unique module name
    'name' => 'hello',

];

这个最小的例子是一个有效的模块定义，尽管它除了被 Pagekit 加载外没有其他功能。只有当模块随附的包在管理面板中被启用时，模块才会被加载。

注：如果你开始探索 Pagekit 的内部结构，你会发现许多地方都有相同的模块结构，这是 Pagekit 架构的核心概念。

可用房产

下表概述了模块定义数组中所有可用的密钥。以下章节将详细解释这些属性并包含代码示例。你可以点击“详情”链接，直接跳转到每个章节。

引导代码

要执行任何类型的PHP代码，你可以为该属性分配回调函数。该函数以 Pagekit Application 容器实例作为参数接收。main

use Pagekit\Application;

// ...

'main' => function (Application $app) {
    // bootstrap code
}

该函数在该模块加载时被调用，也就是在每个常规页面请求中调用。不过，模块需要位于有效的包中，并且该包需要在管理面板中启用。这意味着需要安装并启用扩展，才能加载引导代码。如果你在主题中使用它，只执行当前激活主题的引导代码。index.php

你也可以不指定回调函数，把所有代码直接放在 中，也可以在一个独立文件中创建一个专用的模块类。然后你指定模块类的全名（包括命名空间）作为属性的值。index.phpmain

'main' => 'MyNamespace\\MyModule',

引用的命名空间必须被自动加载才能实现。确保该类实现了 。MyModulePagekit\Module\ModuleInterface

寄存自定义命名空间

传递一份由 Pagekit 自动加载的命名空间和路径列表。路径相对于模的路径，因此在以下例子中 位于 ，假设模定义位于 。srcpackages/VENDOR/PACKAGE/srcpackages/VENDOR/PACKAGE/index.php

'autoload' => [

    'Pagekit\\Hello\\' => 'src'

]

链接目录中的类随后可以在 Pagekit 代码库的语句中被引用。use

<?php
use Pagekit\Hello\HelloExtension;

安装控制器

利用该属性将控制器挂载到路由上。了解更多关于路由与控制器的信息。routes

'routes' => [

    '/hello' => [
        'name' => '@hello/admin',
        'controller' => [
            'Pagekit\\Hello\\Controller\\HelloController'
        ]
    ]

]

定义权限

你的模块可以定义权限。这些文件随后可以在 Pagekit 用户与权限区域分配到角色中。

你定义的唯一权限名称（此处）作为代码库中的标识符。您可以使用该标识符保护路由免受未授权用户的侵害，并防止用户执行未经授权的作。hello: manage settings

'permissions' => [

    'hello: manage settings' => [
        'title' => 'Manage settings'
    ]

]

保护控制作的一个简单方法是使用如下注释。阅读关于注释的内容以了解更多信息。

<?php

class MyController {

    /**
      * @Access("hello: manage settings")
      */
    public function settingsAction() {
    }
}

寄存器资源简写

你可以注册前缀，作为路径工作时的简短版本。例如，使用 引用 。Pagekit 默认已经注册了一些扩展和主题的路径。views:admin/settings.phppackages/VENDOR/PACKAGE/views/admin/settings.php

只要使用 Pagekit 文件系统（即生成文件路径的 URL 或从控制器渲染视图）即可。

'resources' => [

    'views:' => 'views'

],

收听活动

事件会在Pagekit核心的多个节点触发，也可能由其他模块触发。事件总有一个唯一的名称来标识它。你可以对任何事件注册回调函数。

想了解更多关于事件系统的信息，请查看活动部分

'events' => [

    'view.scripts' => function ($event, $scripts) {
        $scripts->register('hello-settings', 'hello:app/bundle/settings.js', '~extensions');
    }

]

默认模块配置

在很多情况下，你希望允许用户更改模块的设置，比如通过设置界面。为了确保你的模块从一开始就有一些配置值，你可以提供一个默认的模块配置。

'config' => [
    'default' => 'World'
],

对该配置数组的任何更改都会被数据库存储。默认值总是与数据库中的值合并，合并结果将作为模块对象的配置属性提供，正如接下来两个节的示例所示。

读取配置

要读取模块的配置，可以访问模块实例的属性。这个对象既是存储在 内部的默认配置，也是数据库中存储的更改的结果。configindex.php

$config = $app->module('hello')->config;

写配置文件

要存储模块配置的更改，可以使用该服务。这些更改会自动传播到数据库。config()

// Complete config
$app->config()->set('hello', $config);

// Single Value
$app->config('hello')->set('message', 'Custom message');

.如果你直接读取模块里的配置，它仍然会保持旧值。下一次请求后，Pagekit 将合并这些更改并作为实例的属性提供。config$module

站点树的寄存器节点

节点类似于路由，主要区别在于可以在站点树视图中拖曳节点，从而动态生成计算好的路由。

当你添加了节点后，它会在站点树中显示。点击“添加页面”按钮，查看所有可用节点类型的下拉菜单。

想了解更多节点信息，请查看路由部分。

'nodes' => [

    'hello' => [

        // The name of the node route
        'name' => '@hello',

        // Label to display in the admin panel
        'label' => 'Hello',

        // The controller for this node. Each controller action will be mounted
        'controller' => 'Pagekit\\Hello\\Controller\\SiteController'
    ]

]

节点选项

如果你的模块想在站点树的内容编辑器中添加配置界面，你可以用该属性为节点对象添加默认选项（完整的配置界面解释见主题教程）。node

在下面的例子中，主题定义了一个属性，该属性会自动添加到每个被渲染的节点对象上。默认情况下，属性的值为 ，这是我们想为该位置渲染的 CSS 类，在这个示例中。top_styleuk-block-mutedtop

'node' => [

    'top_style' => 'uk-block-muted'

],

在主题中渲染页面时，你可以从数组中访问该属性。template.php$params

<?php echo $params['top_style'] ?>

通过该属性，你为每个节点设置默认值。为了允许用户更改这些值，你需要在管理区添加一个界面（通常在编辑页面内容时以添加主题标签的形式出现）。node

为了允许用户更改你在这里定义的默认控件选项的值，你可以在管理区添加一个接口。为此，你需要定义一个 JavaScript 组件来显示编辑界面（示例），在内容编辑器页面注册该 JavaScript 文件（示例），并选择性地更新你的 Webpack 配置（如果你使用 Webpack，示例）。关于这个问题的完整解释可以在主题教程中找到。

将菜单项添加到管理面板

你可以在管理面板的主导航中添加菜单项。这些路径可以链接到任何注册路由，并且受限于特定的访问权限。属性决定菜单项是否可见。access

'menu' => [

        // name, can be used for menu hierarchy
        'hello' => [

            // Label to display
            'label' => 'Hello',

            // Icon to display
            'icon' => 'hello:icon.svg',

            // URL this menu item links to
            'url' => '@hello/admin',

            // Optional: Expression to check if menu item is active on current url
            // 'active' => '@hello*'

            // Optional: Limit access to roles which have specific permission assigned
            // 'access' => 'hello: manage hellos'
        ],

        'hello: panel' => [

            // Parent menu item, makes this appear on 2nd level
            'parent' => 'hello',

            // See above
            'label' => 'Hello',
            'icon' => 'hello:icon.svg',
            'url' => '@hello/admin'
            // 'access' => 'hello: manage hellos'
        ]

    ],

设置界面链接

链接到一个能渲染你设置界面的路线。设置这个属性后，Pagekit会在管理面板列表中，在你的主题或扩展旁边渲染一个设置按钮。

'settings' => '@hello/admin/settings',

寄存器控件

小部件也是一个模块。通过该属性，你可以注册所有控件模块的定义文件。每个文件都应返回一个以有效模块定义形式出现的PHP数组。了解更多关于小部件的信息。widgets

'widgets' => [

    'widgets/form.php'

],

小工具选项

如果你的模块想在控件编辑器中添加配置界面（这在开发主题时很常见），你可以使用该属性为控件对象添加默认选项（完整的控件配置界面示例见主题教程）。widget

在下面的例子中，一个主题定义了一个属性，该属性会自动添加到每个被渲染的控件对象上。默认情况下，该属性的值将是空字符串。panel

'widget' => [

    'panel' => ''

],

渲染小部件时，你可以从数组中访问该属性。$widget->theme

<?php echo $widget->theme['panel'] ?>

为了让用户更改你在这里定义的默认控件选项的值，你可以在管理员区添加一个接口。为此，你需要定义一个 JavaScript 组件来显示编辑界面（示例），在控件编辑器页面注册该 JavaScript 文件（示例），并选择性地更新你的 Webpack 配置（如果你使用 Webpack，示例）。关于这个问题的完整解释可以在主题教程中找到。