README

使用 Plop.js 生成和附加到 Kirby3 CMS 的各种文件的 Plopfile

其他人（可能）对这款插件的评价

🤩
- K-nerd

使用生成器比从官方文档中抓取和调整代码更快？真的吗？太棒了！
- Lasi Toiper

终于有了 ploperoids 上的 Kirby CLI，有无数个附加生成器。
- p10pa

我不关心它是如何工作的，但它确实做到了！单元测试万岁。
- NewToThis

商业使用

支持开源！

此插件免费，但如果您将其用于商业项目，请考虑赞助我或捐款。
如果我的工作帮助您赚了钱，似乎公平的话，我应该也能得到一点回报，对吧？

友善。分享一点。谢谢。

－ Bruno

安装

Plop.js（版本 2）

全局安装 Plop.js。Plop.js 是一个简化了 inquirer 提示和 handlebar 模板之间的粘合代码的库。

npm install -g plop@2

或者

yarn global add plop@2

注意：由于所有 JS 文件都需要转换为 ESM 语法，因此尚不支持 plop.js 版本 3。

Kirby 插件

将 master.zip 解压为文件夹 site/plugins/kirby3-plopfile 或
git submodule add https://github.com/bnomei/kirby3-plopfile.git site/plugins/kirby3-plopfile 或
composer require bnomei/kirby3-plopfile --dev

您项目的 Plopfile

将插件目录中的 example.plopfile.js 复制到您的项目根目录。

cp site/plugins/kirby3-plopfile/example.plopfile.js plopfile.js

Node 依赖项

不包含任何 node_module 依赖项。要使用此插件，请在插件文件夹中运行 npm i 或 yarn。

用法

使用 Plop 生成或附加到文件

Plop 提供了一个交互式终端 UI。它允许您选择一个生成器，并逐步填写每个提示。

plop

但是，您也可以触发一个生成器并跳过一些提示。您可以选择提供所有提示，或者选择使用 _ 作为值来提示一些。需要创建文件的生成器需要一个目标文件夹。插件会尽力使用 glob 来猜测您的设置。当跳过 folder 提示时，您可以使用 $ 默认为特定生成器（如 site/templates 对于 plop template $）使用您的 Kirby 根目录。

# $ = kirbys default root for that generator
plop blueprint $ pages blogpost
plop template $ blogpost
plop content "Consistency made simple!" blog blogpost
plop content _ blog blogpost
plop snippet $ slideshow

使用 plop config/plop plugin 创建的 Kirby 插件 index.php 和配置文件可以通过许多 Kirby 扩展进行附加。这些生成器具有 conf-/ext- 前缀。其中一些可能要求您首先将文件添加到插件文件夹中，然后再附加对该文件的引用。

# adding inline code to plugins
plop plugin myname myplugin
plop ext-collection myplugin allBlogpages

# some files need to be referenced in the plugin index.php to work
plop blueprint myplugin pages contactform
plop ext-blueprint myplugin contactform
plop template myplugin contactform
plop ext-template myplugin contactform

# some extensions do not have a file on their own but are inlined to index.php
plop ext-route myplugin form/submit '' POST

`config-` 和 `ext-` 的用法以及现有文件或缺少标记时

使用 plop config 或 plop plugin 创建文件时，生成器会添加标记以识别添加扩展的位置。为了使 config- 和 ext- 生成器与 plop 未创建的文件一起工作，您必须手动将这些字符串添加到相应的文件中。不要害怕，这非常简单。标记遵循以下模式

[language specific comment] @PLOP_EXT_[extension name in uppercase, singular and low-dashes]

PHP 文件示例

// @PLOP_EXT_HOOK
// @PLOP_EXT_FILES_METHOD

示例网站/config/config.php

<?php

return [
    'hooks' => [
        // Do not forget adding a `,` after existing array items
        'page.update:after' => function () { },
        // @PLOP_EXT_HOOK
    ],
];

扩展自动加载

某些扩展可以使用 autoloader-for-kirby composer 包进行自动加载。一旦使用 composer 需求，您只需为要自动加载的每种扩展类型添加一次自动加载器，它将正确注册子文件夹中的所有文件。这可能会让您避免反复调用最常用的 ext- plop 生成器。

/site/plugins/example/index.php

<?php

Kirby::plugin('bnomei/example', [
    'options' => [
        // options
    ],
    // autoloader for two extension typs
    'snippets' => autoloader(__DIR__)->snippets(),
    'templates' => autoloader(__DIR__)->templates(),
    // other extensions
]);

扩展 plopfile

您可以通过内联代码或使用带有 plop.load() 的文件将自定义代码添加到您的 ./plopfile.js 中。这允许您添加自己的生成器。

plopfile.js

module.exports = function (plop) {
    plop.load([
        "./site/plugins/kirby3-plopfile/plopfile.js",
        // add your custom files here...
    ]);
    // or any plop code here
};

生成器（60）

蓝图（文件夹，类型，模板，扩展，导入）
配置选项（文件，键，值）
配置钩子（文件，键，待办事项）
配置路由（文件，模式，方法，待办事项，[语言，]）
配置（文件名，扩展名，导入）
内容（标题，父级，模板，导入，[语言，slug，]）
命令（文件夹，文件，选项）
控制器（文件夹，模板，扩展，选项）
dockercompose（文件夹，类型，[...]）
ext-auth-challenge（文件夹，键，值）
ext-api-data（文件夹，键，参数，待办事项）
ext-api-route（文件夹，参数，模式，方法，待办事项）
ext-block-method（文件夹，键，参数，待办事项）
ext-block-model（文件夹，键，值）
ext-blocks-method（文件夹，键，参数，待办事项）
ext-blueprint（文件夹，文件）
ext-cache-type（文件夹，键，值）
ext-class-alias（文件夹，键，值）
ext-class-loader（文件夹，键，值）
ext-collection-filter（文件夹，键，待办事项）
ext-collection-method（文件夹，键，参数，待办事项）
ext-collection（文件夹，键，参数，待办事项）
ext-command（文件夹，键，参数，待办事项）
ext-controller（文件夹，文件）
ext-field-method（文件夹，键，参数，待办事项）
ext-field（文件夹，键，待办事项）
ext-file-method（文件夹，键，参数，待办事项）
ext-files-method（文件夹，键，参数，待办事项）
ext-hook（文件夹，钩子，待办事项）
ext-layoutcolumn-method（文件夹，键，参数，待办事项）
ext-layout-method（文件夹，键，待办事项）
ext-layouts-method（文件夹，键，参数，待办事项）
ext-kirbytag（文件夹，键，属性，参数，待办事项）
ext-option（文件夹，键，值）
ext-page-method（文件夹，键，参数，待办事项）
ext-page-model（文件夹，键，值）
ext-pages-method（文件夹，键，参数，待办事项）
ext-pages（文件夹，标题，模板，导入）
ext-permission（文件夹，键，值）
ext-route（文件夹，模式，方法，参数，待办事项，[语言，]）
ext-section（文件夹，键，待办事项）
ext-site-method（文件夹，键，参数，待办事项）
ext-snippet（文件夹，文件）
ext-template（文件夹，文件）
ext-user-method（文件夹，键，参数，待办事项）
ext-user-model（文件夹，键，值）
ext-users-method（文件夹，键，参数，待办事项）
ext-validator（文件夹，键，待办事项）
文件（文件，父级，模板，导入，[语言，]）
htaccess（文件夹，类型）
indexphp（文件夹，类型）
语言（代码，默认，方向，区域设置，名称，URL，导入）
模型（文件夹，模板，选项）
插件（用户，存储库，前缀，选项）
robotstxt（文件夹）
setup（设置）
片段（文件夹，文件，选项，导入）
tdd（文件夹，选项，IDE）
模板（文件夹，模板，扩展，选项）
用户（电子邮件，姓名，密码，角色，语言）

路线图（1）

ext-translation

如果您想提出建议或讨论现有的生成器，请创建一个新的问题。

跳过提示

包含空白的字符串需要用单引号或双引号括起来。
import可以是一个JSON字符串，或者是一个相对路径或绝对路径的JSON或yml文件。跳过的JSON字符串需要用单引号括起来。
_可以让您跳过跳过提示。
$可以用在folder提示中，默认为Kirby的根目录。插件会自动glob查找您的Kirby根目录的位置，但文件夹必须存在。
none/defaults/all可以用在options和extensions上，在跳过时选择复选框。
y/n可以用在确认提示中。
file和folder将支持glob和通配符。所以您可以写*mydo*而不是写config.www.mydomain.net.php。

⚠️如果您使用plop生成文件，但将生成器的extensions设置为none或手动选择它们，您可能会错过一些标记。我建议在跳过时使用default或all作为这些的值，或者在交互式对话框中使用时直接按enter（即默认）。您以后始终可以手动添加标记。

示例

启动交互式生成器

plop

直接启动蓝图生成器

plop blueprint

带有跳过提示的蓝图（从命令行传递的值）

plop blueprint $ pages article .yml {}

具有已知父级和模板但提示标题的内容

plop content _ blog default {}

蓝图克隆

plop blueprint $ fields cd .yml
plop blueprint $ fields dvd .yml cd.yml

使用转义JSON字符串的选项的配置

plop config config.staging defaults '{"debug": true, "home": "staging" }'

具有json/yml文件字段的content

plop content "Consistency, made easy!" blog default n123.json

具有模板和排序数字的file

plop file imgs/i456.jpg blog/consitency-made-easy hero '{"sort": 4}'

具有从json/yml文件翻译的语言

plop language de n ltr de_DE Deutsch de trans_de.yml

添加项目特定扩展的插件

plop plugin myname myplugin '' defaults defaults

在插件中创建蓝图并“扩展”插件index.php

plop blueprint myplugin pages merch .yml {}
plop ext-blueprint myplugin pages/merch

在/site/snippets中的片段，对每个键进行isset检查并提供回退

plop snippet $ topnav defaults '{ "title": "title fallback", "isOpen": null }'

在插件文件夹中创建片段，然后将其注册为该插件的扩展

plop snippet myplugin slideshow defaults {}
plop ext-snippet myplugin slideshow

用于laravel blade渲染的模板

plop template $ booking .blade.php defaults

带有todo注释的插件钩子

plop ext-hook myplugin page.changeStatus:after "if a blogpost is published make kirby send an email to client"

.env文件

您可以在.env文件中添加变量来自定义插件的行为。

剪贴板

# Code.exe' on Windows, 'code' on OSX
PLOP_CLIPBOARD="Code.exe {{filepath}}:{{line}}:{{char}}"

# Sublime Text on OSX
PLOP_CLIPBOARD="subl {{filepath}}:{{line}}:{{char}}"

# PHPStorm
PLOP_CLIPBOARD="phpstorm --line {{line}} --column {{char}} {{filepath}}"

# disable copying to clipboard at end of generator
PLOP_CLIPBOARD=false

kirby根目录

如果您重命名了一个根目录，除非您在.env文件中设置它，否则生成器将无法找到它。

# PLOP_ROOT_[uppercase version of original root name]
PLOP_ROOT_TEMPLATES="different"
# instead of "templates"

脚手架：使用composer和plop生成新项目

Kirby提供各种安装方法，从基本的zip下载到git子模块和composer。这里有一个使用composer和plop的新方法。

基于生成器的composer项目用于公共存储设置

在项目根目录中运行以下命令。创建composer.json文件，用jq修改它，安装Kirby和此插件，并将plopfile复制到您的项目根目录文件夹。

yarn init
composer init
jq -r '. + { config: { "optimize-autoloader": true } }' composer.json
composer require php:">=8.0 <8.2.0" getkirby/cms:^3.8 bnomei/kirby3-plopfile:^1.2
cp site/plugins/kirby3-plopfile/example.plopfile.js plopfile.js

由于我将在大多数项目中使用tailwind和laravel mix，所以我还将运行yarn init。然后，setup生成器将自动通过创建的.gitignore文件（基于package.json文件的存在）排除node_modules文件夹。但您始终可以手动添加类似的内容。

然后使用生成器创建基本的文件夹结构和核心网站文件。

plop setup public-storage
plop indexphp public public-storage
plop htaccess $
plop robotstxt $

可选地，您可以添加用于测试驱动开发（TDD）的默认配置文件的PHP库，或使用可定制的docker-compose.yml在本地提供服务。

plop tdd $ all sublime
# then use ctr-v + enter to install composer dev-requirements

plop dockercompose $ webdevops
docker-compose up

主要依赖