README

Plopfile to generate and append to various files for Kirby3 CMS using Plop.js

What others (might have) said about this plugin

🤩
- K-nerd

Using generators is faster than grabbing and adjusting code from the official docs? Really? Awesome!
- Lasi Toiper

Finally a Kirby CLI on ploperoids with a gazzilion of appending generators.
- p10pa

I don't care how it works but it does! Unittests FTW.
- NewToThis

Installation

Plop.js (version 2)

Install Plop.js globally. Plop.js is simplified just glue code between inquirer prompts and handlebar templates.

npm install -g plop@2

yarn global add plop@2

NOTE: plop.js version 3 is not supported yet since all js files would need to be converted to ESM syntax.

Kirby Plugin

unzip master.zip as folder site/plugins/kirby3-plopfile or
git submodule add https://github.com/bnomei/kirby3-plopfile.git site/plugins/kirby3-plopfile or
composer require bnomei/kirby3-plopfile --dev

Plopfile for your project

Copy example.plopfile.js from the plugin directory to your project root.

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

Node dependencies

No node_module dependencies are included. To use this plugin run npm i or yarn in the plugin folder.

Usage

Use Plop to generate or append to files

Plop provides an interactive terminal UI. It let's you choose a generator and fill each prompt step by step.

plop

But you can also trigger a generator and bypass some prompts. You can provide all prompts or choose to be prompted for some using _ as an value. Generators that create files need a target folder. The plugin tries its best to guess your setup using glob. When bypassing the folder-prompt you can use $ to default to your kirby root for that specific generator (like site/templates for plop template $).

# $ = 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

Kirby Plugins index.php and Config files created using plop config/plop plugin can be appended with lots of Kirbys extensions. These generators have the prefix conf-/ext-. Some of them might require you to add a file to the plugin folder first before appending a reference to that file.

# 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

Usage of `config-` and `ext-` with existing files or when missing markers

When creating files with plop config or plop plugin the generator will add markers to identify the location to append extensions. To make config- and ext- generators work with files not created by plop you have to manually add these strings to the respective files. Do not be afraid. It's very simple. The markers adhere to the following pattern:

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

example for PHP files

// @PLOP_EXT_HOOK
// @PLOP_EXT_FILES_METHOD

example site/config/config.php

<?php

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

Autoloading of extensions

Some extensions can be autoloaded using the autoloader-for-kirby composer package. Once required with composer you add the autoloader for each extension type you want once and it will register all files in subfolders correctly. This might save you calling the most frequently used ext- plop generators again and again.

/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
]);

Extending the plopfile

You can add custom code to your ./plopfile.js as inline code or using files with plop.load(). This allows you to add your own generators.

plopfile.js

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

Generators (60)

blueprint (folder, type, template, extension, import)
config-option (file, key, value)
config-hook (file, key, todo)
config-route (file, pattern, method, todo, [language, ])
config (filename, extensions, import)
content (title, parent, template, import, [language, slug,])
command (folder, file, options)
controller (folder, template, extension, options)
dockercompose (folder, type, [...])
ext-auth-challenge (folder, key, value)
ext-api-data (folder, key, params, todo)
ext-api-route (folder, params, pattern, method, todo)
ext-block-method (folder, key, params, todo)
ext-block-model (folder, key, value)
ext-blocks-method (folder, key, params, todo)
ext-blueprint (folder, file)
ext-cache-type (folder, key, value)
ext-class-alias (folder, key, value)
ext-class-loader (folder, key, value)
ext-collection-filter (folder, key, todo)
ext-collection-method (folder, key, params, todo)
ext-collection (folder, key, params, todo)
ext-command (folder, key, params, todo)
ext-controller (folder, file)
ext-field-method (folder, key, params, todo)
ext-field (folder, key, todo)
ext-file-method (folder, key, params, todo)
ext-files-method (folder, key, params, todo)
ext-hook (folder, hook, todo)
ext-layoutcolumn-method (folder, key, params, todo)
ext-layout-method (folder, key, params, todo)
ext-layouts-method (folder, key, params, todo)
ext-kirbytag (folder, key, attr, params, todo)
ext-option (folder, key, value)
ext-page-method (folder, key, params, todo)
ext-page-model (folder, key, value)
ext-pages-method (folder, key, params, todo)
ext-pages (folder, title, template, import)
ext-permission (folder, key, value)
ext-route (folder, pattern, method, params, todo, [language, ])
ext-section (folder, key, todo)
ext-site-method (folder, key, params, todo)
ext-snippet (folder, file)
ext-template (folder, file)
ext-user-method (folder, key, params, todo)
ext-user-model (folder, key, value)
ext-users-method (folder, key, params, todo)
ext-validator (folder, key, todo)
file (file, parent, template, import, [language,])
htaccess (folder, type)
indexphp (folder, type)
language (code, default, direction, locale, name, url, import)
model (folder, template, options)
plugin (user, repository, prefix, options)
robotstxt (folder)
setup (setup)
snippet (folder, file, options, import)
tdd (folder, options, ide)
template (folder, template, extension, options)
user (email, name, password, role, language)

Roadmap (1)

ext-translation

Please create a new issue if you want to suggest an idea or discuss existing generators.

Bypassing prompts

Strings with whitespace need to wrapped in single quotes or double quotes.
import can be a json string, relative or absolute path to a json or yml file. Bypassed json strings need to be wrapped in single quotes.
_ let you skip bypassing a prompt.
$ can be used on folder prompts to default to kirbys root. The plugin will glob to find the locations of your Kirby roots automatically, but the folders must exist.
none/defaults/all can be used on options and extensions to select checkboxes when bypassing.
y/n can be used on confirmation prompts.
file and folder will be globbed and support wildcards. So you could write *mydo* instead of writing config.www.mydomain.net.php.

⚠️ If you use plop to generate files but set generator extensions to none or cherry pick them manually you might be missing some markers. I'd recommend to stick to default or all as values for these when bypassing or just press enter (aka default) when using the interactive dialog. You can always add the markers manually later.

Examples

start interactive generator

plop

start blueprint generator directly

plop blueprint

blueprint with bypassed prompts (values forwarded from command line)

plop blueprint $ pages article .yml {}

content with known parent and template but prompt for title

plop content _ blog default {}

blueprint cloning

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

config with options from escaped json string

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

content with fields from json/yml file

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

file with template and sorting number

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

language with translations from json/yml file

plop language de n ltr de_DE Deutsch de trans_de.yml

plugin to add project specific extensions

plop plugin myname myplugin '' defaults defaults

create blueprint in plugin and "extend" the plugin index.php

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

snippet at /site/snippets with isset check for each key with fallback

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

create snippet in plugin folder and then register it as an extension to that plugin

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

template for laravel blade rendering

plop template $ booking .blade.php defaults

hook in plugin with todo comment

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

.env File

You can add variables to your .env file to customize the plugins behaviour.

clipboard

# 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 Roots

If you renamed a root the generator will not find it unless you set it in your .env file.

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

Scaffolding: Generating new projects with composer and plop

Kirby offers various installation methods from basic zip download to gitsubmodule and composer. Here is a new one using composer and plop.

generator-based composer project for public-storage setup

Run the following commands in your project root. Create composer.json file, alter it with jq, install Kirby and this plugin plus copying the plopfile to your project root folder.

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

Since I will be using tailwind and laravel mix in most of my projects I am calling yarn init as well. The setup generator will then automatically exclude the node_modules folder via the created .gitignore file based on the existence of the package.json file. But you could always add stuff like this later manually.

Then create the basic folder structure and core website files using generators.

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

Optionally you could add php libraries with default config files for Test Driven Development (TDD) or use a customizable docker-compose.yml to serve your project locally.

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

plop dockercompose $ webdevops
docker-compose up

Major dependencies