Home

Welcome to the main wiki page for wordpress-base-plugin.

• Getting Started
  • Requirements
  • Carbon Fields
  • Setting Initial Variables
  • Node Packages & Renaming Strings/Files
  • Bower
  • Other Changes
  • Installing Composer Dependencies
• Files & Paths
• Other Articles
  • Configuration & Constants
  • Features & Customization
  • Translation
  • Packaging Your Plugin (ZIP)

Getting Started

Once you have cloned the repository, you can follow these steps to make it your own.

Requirements

Before we begin, make sure your system has the following requirements:

• WordPress 4.0 or higher
• PHP 5.6 or higher
• Carbon Fields 2.0 or higher (see the Carbon Fields section
• Composer (required)
• Node.js & Gulp (highly recommended)
• Bower (required for the demo, but optional for your own plugin)

Note: If you need tips on installing Node.js, Composer, Gulp and/or Bower, see the Installing Dependencies article.

Carbon Fields

This plugin uses Carbon Fields to handle custom fields and plugin settings. In order for it to work as-is, you will need to decide if you want to include it as a Composer dependency or install the Carbon Fields plugin.

NB! In order to use the included Network/Multisite functions/examples, Carbon Fields 2.2 or higher must be installed/loaded.

Load as a Plugin

To avoid conflicts caused by multiple versions of Carbon Fields being loaded, it is recommended that you install the Carbon Fields plugin.

Simply clone/download it to your plugins folder an activate as you would any other plugin.

Composer Dependency

Alternatively, you may also load Carbon Fields as a Composer dependency:

$ composer require htmlburger/carbon-fields

By default, this plugin uses TGMPA to display a notice when the Carbon Fields plugin is not detected. If you are loading Carbon Fields as a Composer Dependency and have no other need for TGMPA, you can delete/comment out the TGMPA lines in app/Plugin.php, remove the app/TGMPA.php, and remove the line referencing TGMPA from composer.json.

Setting Initial Variables

Now, open package.json and modify the following variables to values that are relevantely named for your plugin.

• name - The slug for your plugin. I usually set this to match the base directory name.
• config
  • username - While not imparative, this will change the GitHub username paths. If you don't have a GitHub account, you can change it to whatever you like (such as your WordPress.com username).
  • php_namespace - A unique PHP namespace for your plugin. This value will replace the default VendorName\PluginName namespace used in the examples.
  • WPBP_NS - To avoid conflicts, the JavaScript examples use a unique object that contains function logic. Rename this to something that makes sense for your plugin.

Node Packages & Renaming Strings/Files

To install Node & Gulp dependencies:

$ npm install

To rename the strings that you set in the previous step, run:

$ gulp rename

This will replace the namespaces, slugs and filenames to your new strings.

Bower

This step is only necessary to install some script dependencies used by the examples. Whether or not you choose to use Bower is up to you. Alternatively, you may put JavaScript dependencies in src/vendor and enqueue assets/js/wordpress-base-plugin-vendor.js as desired.

$ bower install

Installing Composer Dependencies

Finally, run the following comppand to install PHP dependencies used by the plugin into the vendor directory:

$ composer install

Tip: In the future, if you wish to update the versions of these dependencies, run composer update.

Gulp

The main Gulp task is used to process, minify and combine SASS (CSS) and JavaScript files. In order to try this example plugin, you will want to run it at least once:

$ gulp

Tips: To exit, hit Control-C. As you are developing your plugin and modifying SASS/JavaScript files, leave gulp running to that these files are processed in real time.

Files & Paths

The majority of work is done in the app (PHP) and src (SASS & JavaScript, which Gulp processes and copies the results to assets).

app

The plugin-specific PHP files and classes are located here.

• Core - The main plugin class. You may rename it, break it into multiple classes, or do whatever else you want.
• EnqueueScripts - This file is used to enqueue/inject CSS and JavaScripts into WordPress.
• Helpers - This class holds some static functions used throughout the plugin.

The other files are fairly self-explanatory. Rename, divide and refactor as desired. This is just an example.

src

This folder holds SASS and JavaScript files that will eventually be process by Gulp and copied to the assets folder.

• js - This holds the JavaScripts that will be combined and minified for the frontend and WP Admin, as well as a common folder (in this example) that contains code shared between both. There is also a vendor folder where you can optionally copy JavaScript snippets that will be compiled into a single file. You may use all or none of these - they are examples.
• scss - Contains some example SASS files, which Gulp compiles into CSS.

assets

• components - The pre-configured directory where Bower components are installed.
• css - The destination of CSS files created by Gulp from files in ./src/scss.
• images - This file is empty in the example, but you can use this directory to store plugin-specific images.
• js - The destination of JavaScripts processed by Gulp from files in ./src/js.

languages

If you create a Translation file for your plugin, the resulting .pot will be created here.

See Internationalize Your Plugin for more information.

Other Files

• .gitignore - If you are publishing your plugin to GitHub and want it to be usable without special commands (or updatable via GitHub Updater), you'll probably want to remove/comment out the "Development" section at the bottom. You may also wish to add .gitignore to the list.
• plugin.json - Contains several global settings for the plugin. At minimum, you'll want to change the prefix value to something unique to your project (this is used to prefix all options added to the wp_options table). See Configuration & Constants for more information.
• readme.txt - If you're going to publish your plugin to the wordpress.org repo, you'll want to modify this file appropriately.
• wordpress-base-plugin.php - This is the main plugin loader file. You will want to change any settings in the header meta relavent to your plugin. If you're not interested in supporting automatic updates via GitHub Updater, you'll want to remove the "GitHub Plugin URI" line.