Skip to content

Home

Jump to bottom
Daniel M. Hendricks edited this page Aug 27, 2017 · 21 revisions

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

Carbon Fields

This plugin uses Carbon Fields to handle custom fields and plugin settings. In order for it to work, you will either need to add it as a Composer dependency or install a compatible Carbon Fields Loader plugin.

Loader Plugin

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

Simply clone/download it to your plugins folder an activate.

Composer Dependency

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

  1. Add "htmlburger/carbon-fields": "^2.0.0", to the require section of composer.json.
  2. Run composer update.
  3. This plugin also uses TGMPA to show a notice when the Carbon Fields Loader is not detected. You can remove this check by commenting out the TGMPA line in app/Plugin.php or by modifying app/TGMPA.php to exclude it as a requirement.

Getting Started

Once you have cloned/downloaded the base plugin, follow these steps to make it your own.

Install Node Modules

Change to the directory where the plugin is located and run the following to install NPM dependencies:

npm install

Rename Files and Strings

  1. Edit the package.json file. In the config section, change the slug from "wordpress-base-plugin" to your own (if you're not sure, set it to what you intend to name the plugin directory).
  2. Change the namespace from "VendorName\\PluginName" to your own namespace.
  3. Change the javascript_object from WPBP_NS to something unique to your plugin.
  4. Save the file.

At the command prompt, run:

npm run rename

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

Finally, open composer.json and change the autoload psr-4 namespace from "VendorName\\PluginName\\" to your own namespace, paying attention to the double backslashes. Save changes.

Install Composer Dependencies

Important: See Dependencies for important information about Carbon Fields. If you are not going to usae the Carbon Fields Loader, you must add Carbon Fields as a dependency to your composer.json file first.

To install Composer dependencies, run:

composer install

Other Changes

Edit the following files and change the names, descriptions, versions, etc as necessary:

  • composer.json
  • package.json
  • plugin.json
  • readme.txt
  • The main plugin PHP file in the plugin root directory (initially wordpress-base-plugin.php before running the npm run rename command.

Gulp

Gulp is used to automatic SASS & JavaScript processing. If you do not already have Gulp installed, see here.

Assuming that you have already run npm install, the gulpfile.js will monitor changes in your SASS/JavaScript files in ./src and compiled them into the ./assets directory. To have Gulp watch your file changes, run the following from your plugin directory:

gulp

Note: It is required that you run Gulp in order to have the "Clear Cache" link from the admin bar dropdown example work. If you do not, you will receive 404 console errors that the enqueued scripts are not found.

Files & Paths

This section describes the layout of the base plugin.

Root Files

There are several key files that you may want to customize:

  • .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.
  • package.json - Before running npm rename, you'll want to change the config settings to your own.
  • composer.json - This is where you'll want to add/remove Composer dependencies (for example, if you wish to embed Carbon Fields in your plugin rather than depending on an external plugin loader.
  • gulpfile.js - This file tells Gulp how to handle tasks. You can modify paths, change CSS output style, and define the folders you wish to process in ./src/js.
  • 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).
  • 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.

Directories

  • app - This directory holds the core PHP logic for your plugin.
    • TODO: Explain app file structure
  • assets - Hold the compiled CSS & JS from the ./src directory, as well as a screenshot image and an images directory for putting images related to your plugin. You can add other linked files/folders here as you wish.
  • languages - The location of the .pot file generated with npm run translate, as well as any translations you may create.
  • src - The source directory for custom and vendor JavaScripts and SASS. These files are processed by Gulp and copied to the ./assets folder.
  • vendor - This directory contains the Composer autoload files as well as dependencies that you define in composer.json. The contents are automatically generated with composer install or composer update and should not be modified unless you know what you're doing.

Translation

Translation language files can be created automatically using wp-pot-cli.

Assuming the you have already run npm install, you can run the following command to create a translation file in the languages directory:

npm run translate

Installing Dependencies

This section is intended to provide some tips if you need help installing Node.js, Composer, Gulp, and Bower.

Windows

I am not a Windows user, but this is how I would probably do it:

  1. Install Chocolatey:
    • Right-click and run PowerShell as Administrator: Start > Run > All Programs > Accessories > Windows PowerShell > Windows PowerShell
    • Set the PowerShell ExecutionPolicy to RemoteSigned with this command: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
    • iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
  2. Close PowerShell and reopen it as Administrator.
  3. Install packages:
    • choco install openssh git nodejs.install
    • choco install composer gulp-cli bower

Please feel free to send corrections.

Mac OS X

  1. Install Homebrew, then brew update
  2. Install Node.js: brew install node
  3. Install Composer: brew install composer
  4. Install Grunt & Bower:
    • sudo npm install -g grunt-cli
    • sudo npm install -g bower
Clone this wiki locally