bnomei / kirby3-plopfile
Plopfile to generate and append to various files for Kirby3 CMS using Plop.js
Installs: 247
Dependents: 0
Suggesters: 0
Security: 0
Stars: 7
Watchers: 3
Forks: 0
Open Issues: 0
Language:JavaScript
Type:kirby-plugin
Requires
- php: >=8.0
- getkirby/composer-installer: ^1.2
Requires (Dev)
- phpunit/phpunit: ^9.5
Suggests
- bnomei/autoloader-for-kirby: Helper Class to automatically load various Kirby extensions in a plugin
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
or
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
orcomposer 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 onfolder
prompts to default to kirbys root. The plugin willglob
to find the locations of your Kirby roots automatically, but the folders must exist.none
/defaults
/all
can be used onoptions
andextensions
to select checkboxes when bypassing.y
/n
can be used on confirmation prompts.file
andfolder
will be globbed and support wildcards. So you could write*mydo*
instead of writingconfig.www.mydomain.net.php
.
⚠️ If you use plop to generate files but set generator
extensions
tonone
or cherry pick them manually you might be missing some markers. I'd recommend to stick todefault
orall
as values for these when bypassing or just pressenter
(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. Thesetup
generator will then automatically exclude thenode_modules
folder via the created.gitignore
file based on the existence of thepackage.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
No node_module dependencies are included. To use this plugin run npm i
or yarn
in the plugin folder.
Disclaimer
This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.
License
It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.