Merge branch 'master' into develop

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+* (4 September 2014). Updating the `README` with Windows symbolic link instructions.
+* (3 September 2014). Updating the `README` to describe how to install the Boilerplate.
+* (1 September 2014). Initial Release.

ChangeLog.md

@@ -1,3 +0,0 @@
-# ChangeLog
-
-* (1 September 2015). Initial Release

README.md

@@ -7,7 +7,7 @@ A standardized, organized, object-oriented foundation for building high-quality
 The WordPress Plugin Boilerplate includes the following files:
 
 * `.gitignore`. Used to exclude certain files from the repository.
-* `ChangeLog.md`. The list of changes to the core project.
+* `CHANGELOG.md`. The list of changes to the core project.
 * `README.md`. The file that you’re currently reading.
 * A `plugin-name` subdirectory that contains the source code - a fully executable WordPress plugin.
 
@@ -20,11 +20,35 @@ The WordPress Plugin Boilerplate includes the following files:
 
 ## Installation
 
-1. Copy the `plugin-name` directory into your `wp-content/plugins` directory.
+The Boilerplate can be installed in one of two ways both of which are documented below. Note that because of its directory structure, the Boilerplate cannot be installed “as-is.”
-2. In the WordPress dashboard, navigation to the *Plugins* page
+
+Instead, the options are:
+
+### Copying a Directory
+
+1. Copy the `trunk` directory into your `wp-content/plugins` directory. You may wish to rename this to something else.
+2. In the WordPress admin area, navigation to the *Plugins* page
 Locate the menu item that reads “The WordPress Plugin Boilerplate.”
 3. Click on *Activate.*
 
+### Creating a Symbolic Link
+
+#### On Linux or OS X
+
+1. Copy the `WordPress-Plugin-Boilerplate` directory into your `wp-content/plugins` directory.
+2. Create a symbolic link between the `trunk` directory and the plugin. For example: `ln -s plugin-name/trunk /path/to/wordpress/wp-content/plugins/plugin-name`
+3. In the WordPress admin area, navigation to the *Plugins* page
+Locate the menu item that reads “The WordPress Plugin Boilerplate.”
+4. Click on *Activate.*
+
+#### On Windows
+
+1. Copy the `WordPress-Plugin-Boilerplate` directory into your `wp-content/plugins` directory.
+2. Create a symbolic link between the `trunk` directory and the plugin. For example: `mklink /J path\to\wp-content\plugins \path\to\WordPress-Plugin-Boilerplate\trunk\plugin-name`
+3. In the WordPress admin area, navigation to the *Plugins* page
+Locate the menu item that reads “The WordPress Plugin Boilerplate.”
+4. Click on *Activate.*
+
 Note that this will activate the source code of the Boilerplate, but because the Boilerplate has no real functionality so no menu  items, meta boxes, or custom post types will be added.
 
 Examples are slated to be added to the [Boilerplate’s website](http://wppb.io) as the site continues to grow.
@@ -65,8 +89,8 @@ For reference, [here's a discussion](http://make.wordpress.org/themes/2013/03/04
 
 Note that if you include your own classes, or third-party libraries, there are three locations in which said files may go:
 
-* `plugin-name/includes` is where functionality shared between the dashboard and the public-facing parts of the side reside
+* `plugin-name/includes` is where functionality shared between the admin area and the public-facing parts of the site reside
-* `plugin-name/admin` is for all dashboard-specific functionality
+* `plugin-name/admin` is for all admin-specific functionality
 * `plugin-name/public` is for all public-facing functionality
 
 Note that previous versions of the Boilerplate did not include `Plugin_Name_Loader` but this class is used to register all filters and actions with WordPress.
@@ -93,20 +117,20 @@ When committing code to the WordPress Plugin Repository, all of the banner, icon
 
 ### What About Other Features?
 
-The previous version of the WordPress Plugin Boilerplate included support for a number of different projects such as the [GitHub Updater](https://github.com/afragen/github-updater). 
+The previous version of the WordPress Plugin Boilerplate included support for a number of different projects such as the [GitHub Updater](https://github.com/afragen/github-updater).
 
-These tools are not part of the core of this Boilerplate, as I see them as being additions, forks, or other contributions to the Boilerplate. 
+These tools are not part of the core of this Boilerplate, as I see them as being additions, forks, or other contributions to the Boilerplate.
 
 The same is true of using tools like Grunt, Composer, etc. These are all fantastic tools, but not everyone uses them. In order to  keep the core Boilerplate as light as possible, this feature have been removed and will be introduced in other editions, and will be listed and maintained on the project homepage
 
 # Credits
 
-The WordPress Plugin Boilerplate was started in 2011 by [Tom McFarlin](http://twitter.com/tommcfarlin/) and his since included a number of great contributions.
+The WordPress Plugin Boilerplate was started in 2011 by [Tom McFarlin](http://twitter.com/tommcfarlin/) and has since included a number of great contributions. In March of 2015 the project was handed over by Tom to Devin Vinson.
 
-The current version of the Boilerplate was developed in conjunction with [Josh Eaton](https://twitter.com/jjeaton), [Ulrich Pogson](https://twitter.com/grapplerulrich), and [Brad Vincent](https://twitter.com/themergency). 
+The current version of the Boilerplate was developed in conjunction with [Josh Eaton](https://twitter.com/jjeaton), [Ulrich Pogson](https://twitter.com/grapplerulrich), and [Brad Vincent](https://twitter.com/themergency).
 
 The homepage is based on a design as provided by [HTML5Up](http://html5up.net), the Boilerplate logo was designed by  Rob McCaskill of [BungaWeb](http://bungaweb.com), and the site `favicon` was created by [Mickey Kay](https://twitter.com/McGuive7).
 
 ## Documentation, FAQs, and More
 
-Because this version is a major rewrite of the core plugin, we’re working to create an entire site around the Boilerplate. If you’re interested, please [let me know](http://tommcfarlin.com/contact) and we’ll see what we can do. 
+Because this version is a major rewrite of the core plugin, we’re working to create an entire site around the Boilerplate. If you’re interested, please [let me know](http://devinvinson.com/contact/) and we’ll see what we can do.

plugin-name/trunk/admin/class-plugin-name-admin.php

@@ -1,20 +1,20 @@
 <?php
 
 /**
- * The dashboard-specific functionality of the plugin.
+ * The admin-specific functionality of the plugin.
  *
  * @link       http://example.com
  * @since      1.0.0
  *
  * @package    Plugin_Name
- * @subpackage Plugin_Name/includes
+ * @subpackage Plugin_Name/admin
  */
 
 /**
- * The dashboard-specific functionality of the plugin.
+ * The admin-specific functionality of the plugin.
  *
  * Defines the plugin name, version, and two examples hooks for how to
- * enqueue the dashboard-specific stylesheet and JavaScript.
+ * enqueue the admin-specific stylesheet and JavaScript.
  *
  * @package    Plugin_Name
  * @subpackage Plugin_Name/admin
@@ -27,9 +27,9 @@ class Plugin_Name_Admin {
 	 *
 	 * @since    1.0.0
 	 * @access   private
-	 * @var      string    $name    The ID of this plugin.
+	 * @var      string    $plugin_name    The ID of this plugin.
 	 */
-	private $name;
+	private $plugin_name;
 
 	/**
 	 * The version of this plugin.
@@ -44,18 +44,18 @@ class Plugin_Name_Admin {
 	 * Initialize the class and set its properties.
 	 *
 	 * @since    1.0.0
-	 * @var      string    $name       The name of this plugin.
+	 * @param      string    $plugin_name       The name of this plugin.
-	 * @var      string    $version    The version of this plugin.
+	 * @param      string    $version    The version of this plugin.
 	 */
-	public function __construct( $name, $version ) {
+	public function __construct( $plugin_name, $version ) {
 
-		$this->name = $name;
+		$this->plugin_name = $plugin_name;
 		$this->version = $version;
 
 	}
 
 	/**
-	 * Register the stylesheets for the Dashboard.
+	 * Register the stylesheets for the admin area.
 	 *
 	 * @since    1.0.0
 	 */
@@ -65,20 +65,20 @@ class Plugin_Name_Admin {
 		 * This function is provided for demonstration purposes only.
 		 *
 		 * An instance of this class should be passed to the run() function
-		 * defined in Plugin_Name_Admin_Loader as all of the hooks are defined
+		 * defined in Plugin_Name_Loader as all of the hooks are defined
 		 * in that particular class.
 		 *
-		 * The Plugin_Name_Admin_Loader will then create the relationship
+		 * The Plugin_Name_Loader will then create the relationship
 		 * between the defined hooks and the functions defined in this
 		 * class.
 		 */
 
-		wp_enqueue_style( $this->name, plugin_dir_url( __FILE__ ) . 'css/plugin-name-admin.css', array(), $this->version, 'all' );
+		wp_enqueue_style( $this->plugin_name, plugin_dir_url( __FILE__ ) . 'css/plugin-name-admin.css', array(), $this->version, 'all' );
 
 	}
 
 	/**
-	 * Register the JavaScript for the dashboard.
+	 * Register the JavaScript for the admin area.
 	 *
 	 * @since    1.0.0
 	 */
@@ -88,15 +88,15 @@ class Plugin_Name_Admin {
 		 * This function is provided for demonstration purposes only.
 		 *
 		 * An instance of this class should be passed to the run() function
-		 * defined in Plugin_Name_Admin_Loader as all of the hooks are defined
+		 * defined in Plugin_Name_Loader as all of the hooks are defined
 		 * in that particular class.
 		 *
-		 * The Plugin_Name_Admin_Loader will then create the relationship
+		 * The Plugin_Name_Loader will then create the relationship
 		 * between the defined hooks and the functions defined in this
 		 * class.
 		 */
 
-		wp_enqueue_script( $this->name, plugin_dir_url( __FILE__ ) . 'js/plugin-name-admin.js', array( 'jquery' ), $this->version, FALSE );
+		wp_enqueue_script( $this->plugin_name, plugin_dir_url( __FILE__ ) . 'js/plugin-name-admin.js', array( 'jquery' ), $this->version, false );
 
 	}
 

plugin-name/trunk/admin/css/plugin-name-admin.css

@@ -1,4 +1,4 @@
 /**
- * All of the CSS for your dashboard-specific functionality should be
+ * All of the CSS for your admin-specific functionality should be
  * included in this file.
  */

plugin-name/trunk/admin/js/plugin-name-admin.js

@@ -2,7 +2,7 @@
 	'use strict';
 
 	/**
-	 * All of the code for your Dashboard-specific JavaScript source
+	 * All of the code for your admin-specific JavaScript source
 	 * should reside in this file.
 	 *
 	 * Note that this assume you're going to use jQuery, so it prepares

plugin-name/trunk/admin/partials/plugin-name-admin-display.php

@@ -1,9 +1,9 @@
 <?php
 
 /**
- * Provide a dashboard view for the plugin
+ * Provide a admin area view for the plugin
  *
- * This file is used to markup the public-facing aspects of the plugin.
+ * This file is used to markup the admin-facing aspects of the plugin.
  *
  * @link       http://example.com
  * @since      1.0.0

plugin-name/trunk/includes/class-plugin-name-i18n.php

@@ -4,7 +4,7 @@
  * Define the internationalization functionality
  *
  * Loads and defines the internationalization files for this plugin
- * so that its ready for translation.
+ * so that it is ready for translation.
  *
  * @link       http://example.com
  * @since      1.0.0
@@ -17,7 +17,7 @@
  * Define the internationalization functionality.
  *
  * Loads and defines the internationalization files for this plugin
- * so that its ready for translation.
+ * so that it is ready for translation.
  *
  * @since      1.0.0
  * @package    Plugin_Name
@@ -44,7 +44,7 @@ class Plugin_Name_i18n {
 
 		load_plugin_textdomain(
 			$this->domain,
-			FALSE,
+			false,
 			dirname( dirname( plugin_basename( __FILE__ ) ) ) . '/languages/'
 		);
 

plugin-name/trunk/includes/class-plugin-name-loader.php

@@ -57,11 +57,11 @@ class Plugin_Name_Loader {
 	 * Add a new action to the collection to be registered with WordPress.
 	 *
 	 * @since    1.0.0
-	 * @var      string               $hook             The name of the WordPress action that is being registered.
+	 * @param      string               $hook             The name of the WordPress action that is being registered.
-	 * @var      object               $component        A reference to the instance of the object on which the action is defined.
+	 * @param      object               $component        A reference to the instance of the object on which the action is defined.
-	 * @var      string               $callback         The name of the function definition on the $component.
+	 * @param      string               $callback         The name of the function definition on the $component.
-	 * @var      int      Optional    $priority         The priority at which the function should be fired.
+	 * @param      int      Optional    $priority         The priority at which the function should be fired.
-	 * @var      int      Optional    $accepted_args    The number of arguments that should be passed to the $callback.
+	 * @param      int      Optional    $accepted_args    The number of arguments that should be passed to the $callback.
 	 */
 	public function add_action( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) {
 		$this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority, $accepted_args );
@@ -71,11 +71,11 @@ class Plugin_Name_Loader {
 	 * Add a new filter to the collection to be registered with WordPress.
 	 *
 	 * @since    1.0.0
-	 * @var      string               $hook             The name of the WordPress filter that is being registered.
+	 * @param      string               $hook             The name of the WordPress filter that is being registered.
-	 * @var      object               $component        A reference to the instance of the object on which the filter is defined.
+	 * @param      object               $component        A reference to the instance of the object on which the filter is defined.
-	 * @var      string               $callback         The name of the function definition on the $component.
+	 * @param      string               $callback         The name of the function definition on the $component.
-	 * @var      int      Optional    $priority         The priority at which the function should be fired.
+	 * @param      int      Optional    $priority         The priority at which the function should be fired.
-	 * @var      int      Optional    $accepted_args    The number of arguments that should be passed to the $callback.
+	 * @param      int      Optional    $accepted_args    The number of arguments that should be passed to the $callback.
 	 */
 	public function add_filter( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) {
 		$this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority, $accepted_args );
@@ -87,12 +87,12 @@ class Plugin_Name_Loader {
 	 *
 	 * @since    1.0.0
 	 * @access   private
-	 * @var      array                $hooks            The collection of hooks that is being registered (that is, actions or filters).
+	 * @param      array                $hooks            The collection of hooks that is being registered (that is, actions or filters).
-	 * @var      string               $hook             The name of the WordPress filter that is being registered.
+	 * @param      string               $hook             The name of the WordPress filter that is being registered.
-	 * @var      object               $component        A reference to the instance of the object on which the filter is defined.
+	 * @param      object               $component        A reference to the instance of the object on which the filter is defined.
-	 * @var      string               $callback         The name of the function definition on the $component.
+	 * @param      string               $callback         The name of the function definition on the $component.
-	 * @var      int      Optional    $priority         The priority at which the function should be fired.
+	 * @param      int      Optional    $priority         The priority at which the function should be fired.
-	 * @var      int      Optional    $accepted_args    The number of arguments that should be passed to the $callback.
+	 * @param      int      Optional    $accepted_args    The number of arguments that should be passed to the $callback.
 	 * @return   type                                   The collection of actions and filters registered with WordPress.
 	 */
 	private function add( $hooks, $hook, $component, $callback, $priority, $accepted_args ) {

plugin-name/trunk/includes/class-plugin-name.php

@@ -4,7 +4,7 @@
  * The file that defines the core plugin class
  *
  * A class definition that includes attributes and functions used across both the
- * public-facing side of the site and the dashboard.
+ * public-facing side of the site and the admin area.
  *
  * @link       http://example.com
  * @since      1.0.0
@@ -16,7 +16,7 @@
 /**
  * The core plugin class.
  *
- * This is used to define internationalization, dashboard-specific hooks, and
+ * This is used to define internationalization, admin-specific hooks, and
  * public-facing site hooks.
  *
  * Also maintains the unique identifier of this plugin as well as the current
@@ -61,7 +61,7 @@ class Plugin_Name {
 	 * Define the core functionality of the plugin.
 	 *
 	 * Set the plugin name and the plugin version that can be used throughout the plugin.
-	 * Load the dependencies, define the locale, and set the hooks for the Dashboard and
+	 * Load the dependencies, define the locale, and set the hooks for the admin area and
 	 * the public-facing side of the site.
 	 *
 	 * @since    1.0.0
@@ -85,7 +85,7 @@ class Plugin_Name {
 	 *
 	 * - Plugin_Name_Loader. Orchestrates the hooks of the plugin.
 	 * - Plugin_Name_i18n. Defines internationalization functionality.
-	 * - Plugin_Name_Admin. Defines all hooks for the dashboard.
+	 * - Plugin_Name_Admin. Defines all hooks for the admin area.
 	 * - Plugin_Name_Public. Defines all hooks for the public side of the site.
 	 *
 	 * Create an instance of the loader which will be used to register the hooks
@@ -109,7 +109,7 @@ class Plugin_Name {
 		require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-plugin-name-i18n.php';
 
 		/**
-		 * The class responsible for defining all actions that occur in the Dashboard.
+		 * The class responsible for defining all actions that occur in the admin area.
 		 */
 		require_once plugin_dir_path( dirname( __FILE__ ) ) . 'admin/class-plugin-name-admin.php';
 
@@ -142,7 +142,7 @@ class Plugin_Name {
 	}
 
 	/**
-	 * Register all of the hooks related to the dashboard functionality
+	 * Register all of the hooks related to the admin area functionality
 	 * of the plugin.
 	 *
 	 * @since    1.0.0

plugin-name/trunk/plugin-name.php

@@ -4,9 +4,9 @@
  * The plugin bootstrap file
  *
  * This file is read by WordPress to generate the plugin information in the plugin
- * Dashboard. This file also includes all of the dependencies used by the plugin,
+ * admin area. This file also includes all of the dependencies used by the plugin,
  * registers the activation and deactivation functions, and defines a function
- * this starts the plugin.
+ * that starts the plugin.
  *
  * @link              http://example.com
  * @since             1.0.0
@@ -15,7 +15,7 @@
  * @wordpress-plugin
  * Plugin Name:       WordPress Plugin Boilerplate
  * Plugin URI:        http://example.com/plugin-name-uri/
- * Description:       This is a short description of what the plugin does. It's displayed in the WordPress dashboard.
+ * Description:       This is a short description of what the plugin does. It's displayed in the WordPress admin area.
  * Version:           1.0.0
  * Author:            Your Name or Your Company
  * Author URI:        http://example.com/
@@ -32,25 +32,30 @@ if ( ! defined( 'WPINC' ) ) {
 
 /**
  * The code that runs during plugin activation.
+ * This action is documented in includes/class-plugin-name-activator.php
  */
-require_once plugin_dir_path( __FILE__ ) . 'includes/class-plugin-name-activator.php';
+function activate_plugin_name() {
+	require_once plugin_dir_path( __FILE__ ) . 'includes/class-plugin-name-activator.php';
+	Plugin_Name_Activator::activate();
+}
 
 /**
  * The code that runs during plugin deactivation.
+ * This action is documented in includes/class-plugin-name-deactivator.php
  */
-require_once plugin_dir_path( __FILE__ ) . 'includes/class-plugin-name-deactivator.php';
+function deactivate_plugin_name() {
+	require_once plugin_dir_path( __FILE__ ) . 'includes/class-plugin-name-deactivator.php';
+	Plugin_Name_Deactivator::deactivate();
+}
 
-/** This action is documented in includes/class-plugin-name-activator.php */
+register_activation_hook( __FILE__, 'activate_plugin_name' );
-register_activation_hook( __FILE__, array( 'Plugin_Name_Activator', 'activate' ) );
+register_deactivation_hook( __FILE__, 'deactivate_plugin_name' );
-
-/** This action is documented in includes/class-plugin-name-deactivator.php */
-register_activation_hook( __FILE__, array( 'Plugin_Name_Deactivator', 'deactivate' ) );
 
 /**
  * The core plugin class that is used to define internationalization,
- * dashboard-specific hooks, and public-facing site hooks.
+ * admin-specific hooks, and public-facing site hooks.
  */
-require_once plugin_dir_path( __FILE__ ) . 'includes/class-plugin-name.php';
+require plugin_dir_path( __FILE__ ) . 'includes/class-plugin-name.php';
 
 /**
  * Begins execution of the plugin.

plugin-name/trunk/public/class-plugin-name-public.php

@@ -7,17 +7,17 @@
  * @since      1.0.0
  *
  * @package    Plugin_Name
- * @subpackage Plugin_Name/includes
+ * @subpackage Plugin_Name/public
  */
 
 /**
  * The public-facing functionality of the plugin.
  *
  * Defines the plugin name, version, and two examples hooks for how to
- * enqueue the dashboard-specific stylesheet and JavaScript.
+ * enqueue the admin-specific stylesheet and JavaScript.
  *
  * @package    Plugin_Name
- * @subpackage Plugin_Name/admin
+ * @subpackage Plugin_Name/public
  * @author     Your Name <email@example.com>
  */
 class Plugin_Name_Public {
@@ -27,9 +27,9 @@ class Plugin_Name_Public {
 	 *
 	 * @since    1.0.0
 	 * @access   private
-	 * @var      string    $name    The ID of this plugin.
+	 * @var      string    $plugin_name    The ID of this plugin.
 	 */
-	private $name;
+	private $plugin_name;
 
 	/**
 	 * The version of this plugin.
@@ -44,12 +44,12 @@ class Plugin_Name_Public {
 	 * Initialize the class and set its properties.
 	 *
 	 * @since    1.0.0
-	 * @var      string    $name       The name of the plugin.
+	 * @param      string    $plugin_name       The name of the plugin.
-	 * @var      string    $version    The version of this plugin.
+	 * @param      string    $version    The version of this plugin.
 	 */
-	public function __construct( $name, $version ) {
+	public function __construct( $plugin_name, $version ) {
 
-		$this->name = $name;
+		$this->plugin_name = $plugin_name;
 		$this->version = $version;
 
 	}
@@ -65,15 +65,15 @@ class Plugin_Name_Public {
 		 * This function is provided for demonstration purposes only.
 		 *
 		 * An instance of this class should be passed to the run() function
-		 * defined in Plugin_Name_Public_Loader as all of the hooks are defined
+		 * defined in Plugin_Name_Loader as all of the hooks are defined
 		 * in that particular class.
 		 *
-		 * The Plugin_Name_Public_Loader will then create the relationship
+		 * The Plugin_Name_Loader will then create the relationship
 		 * between the defined hooks and the functions defined in this
 		 * class.
 		 */
 
-		wp_enqueue_style( $this->name, plugin_dir_url( __FILE__ ) . 'css/plugin-name-public.css', array(), $this->version, 'all' );
+		wp_enqueue_style( $this->plugin_name, plugin_dir_url( __FILE__ ) . 'css/plugin-name-public.css', array(), $this->version, 'all' );
 
 	}
 
@@ -88,15 +88,15 @@ class Plugin_Name_Public {
 		 * This function is provided for demonstration purposes only.
 		 *
 		 * An instance of this class should be passed to the run() function
-		 * defined in Plugin_Name_Public_Loader as all of the hooks are defined
+		 * defined in Plugin_Name_Loader as all of the hooks are defined
 		 * in that particular class.
 		 *
-		 * The Plugin_Name_Public_Loader will then create the relationship
+		 * The Plugin_Name_Loader will then create the relationship
 		 * between the defined hooks and the functions defined in this
 		 * class.
 		 */
 
-		wp_enqueue_script( $this->name, plugin_dir_url( __FILE__ ) . 'js/plugin-name-public.js', array( 'jquery' ), $this->version, FALSE );
+		wp_enqueue_script( $this->plugin_name, plugin_dir_url( __FILE__ ) . 'js/plugin-name-public.js', array( 'jquery' ), $this->version, false );
 
 	}