generator-wppb

WordPress Plugin Boilerplate Generator

Yeoman generator for the WordPress Plugin Boilerplate - lets you quickly set up a new plugin project using the WordPress Plugin Boilerplate

"Wait, why should I use this?"

"I mean...find-and-replace in my IDE works, right?"

Indeed it does.

If you already have Yeoman and Grunt installed and in your workflow, this can make new plugin projects start faster and easier than before.

The generator prompts for information that is needed for trivial stuff (plugin name, author email, etc) and builds the template from there. It sets up the directory and file names, public and admin classes, and so on.

If you don't already use Yeoman or Grunt?

This could be fun if you want to explore Node.js and/or Grunt. Grunt is being used by the WordPress core team and can automate the build process. For plugins, this probably isn't a huge deal but for large web apps, this can be a nice tool to have in the belt. ...And while this generator doesn't install any Grunt tools yet, that's one of the next major enhancements to install.

Still reading? OK...let's get started.

Pre-Requisites

This generator relies upon Yeoman, which in turn relies upon Node.js.

Please see getting started with Yeoman for more information on this tool if you are new to it.

Installation

Install: npm install -g generator-wppb

Usage

Navigate to your development directory or to the wp-content/plugins directory where you will build the new boilerplate-based plugin. For example:

cd projects/new-plugins/wordpress/wp-content/plugins

Run yo wppb:

yo wppb

Finally, answer the prompts.

Answering the Prompts

It's a good idea to have your answers to the prompts prepared before running the generator. This would be true even if you are building a plugin manually or by using find-and-replace.

By doing this, not only will you be able to move more quickly, but you can also do some preliminary searches to be sure that there aren't already plugins using the name you want, you can ensure your name(s) meet the standards for file and class conventions, and so on.

The generator will prompt for these key plugin values:

• The Plugin Name - Keep it short; whitespace allowed; 'human friendly'
• Plugin Filename Prefix - filters human friendly to be file system friendly
• Plugin Class Prefix - filters human friendly to be PHP Class & WordPress style friendly (see docs below)
• Author Name - you!
• Author Email - [e-mail]
• Author URI - http://you.com
• Plugin URI (if different) - http://plugin.you.com
• (optional) Github project owner and name - http://github.com/you/yourplugin.git

What is intentionally missing from the generator:

• Description - descriptions can be lengthy and yeoman isn't the best tool for entering long text strings; this remains a TODO in the generated code so that you can edit the descriptive text via your IDE
• Plugin Functionality -- the generator won't write code for you, it will just set up the framework. :)

Prompt details

Sanity checks are done for each value so that easily avoided errors are...um...avoided.

The regular expressions used to accomplish this aren't bad, but they are likely to have holes. I'm not a regular expressions expert. As such, if you run into a situation where your data passes these validations but throws errors in the generated code...please open an issue! I'll improve these as I get feedback.

Plugin Name (mandatory field)

This is the 'human friendly' plugin name that shows up in places like the Plugin admin pages within Wordpress. The validator for this:

Accepts:

• letters [a-zA-Z]
• numbers [0-9]
• spaces

Rejects

• everything else
• i.e. no symbols, tabs, or other non-western alphanumeric characters
• (I'm happy to change this so that other character sets pass but for now, I'm working with what I know.)

Plugin File Name (mandatory field)

Using the Plugin Name (above) as a basis, a name that is file-system friendly (and slug-friendly) is generated by:

• all letters are converted to lowercase
• spaces are converted to hyphens

The generator allows for a new name to be entered, overriding the name derived from the Plugin Name. If a new name is entered, the validator will:

Accept:

• letters
• numbers
• hyphens

Everything else will be rejected. For the moment, this INCLUDES periods as this file name is actually a 'root' that gets used for public, admin, and other file names. Thus, adding a .php onto the end will be rejected because the generator already does that and other manipulations.

Plugin Class Name (mandatory field)

Plugin Author (optional field)

This is the name of the developer who created the plugin. No restritions or validations are applied.

Author Email (optional field)

This is the contact email for the plugin author. No restrictions or validations are applied.

Author and Plugin Website (optional fields)

Two prompts for websites are displayed.

The 'author website' allows for the author to specify their personal website for the plugin details. The 'plugin website' allows a second URL to be specified, differentiating the 'plugin homepage' from the 'author homepage'.

Github Project Details (optional fields)

Providing GitHub author and repo details is totally optional.

If these are selected, only the username and repo name should be provided in the corresponding prompts. Thus, if I were creating a new plugin, I would enter my 'GitHub username' as mbakaitis and the repo as whatever I called the plugin repo on GitHub...such as my-awesome-new-plugin or whatever.

Typical workflow

After installing the generator, the general workflow is:

1. Navigate to your development home or to wp-content/plugins
2. Run yo wppb
3. Answer the prompts
4. Start editing! Maybe update the description...then write your own new, awesome plugin code!

Contribute

I am happy to take suggestions for improvement, bug fixes, and anything else that will improve this generator overall. I'll add you to the contributors list as I accept pulls or suggestions that make significant improvements. :)

I probably won't take improvements to the boilerplate plugin as this generator will begin to shadow that project. As the original project updates, this one will follow.

License

GNU General Public License (as used by WordPress). See the content at the link or read the accompanying LICENSE.txt that mirrors the link.