Download the PHP package bnomei/kirby3-plopfile without Composer

Kirby Plopfile

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.

or

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.

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.

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 $).

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.

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:

example for PHP files

example site/config/config.php

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

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

Generators (60)

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

start blueprint generator directly

blueprint with bypassed prompts (values forwarded from command line)

content with known parent and template but prompt for title

blueprint cloning

config with options from escaped json string

content with fields from json/yml file

file with template and sorting number

language with translations from json/yml file

plugin to add project specific extensions

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

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

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

template for laravel blade rendering

hook in plugin with todo comment

.env File

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

clipboard

Kirby Roots

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

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.

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.

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.

Major dependencies

• plop.js
• inquirer.js
• handlebars.js
• fast-glob
• js-yaml
• clipboardy

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

MIT

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.