diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..8ff0039 --- /dev/null +++ b/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. diff --git a/ChangeLog.md b/ChangeLog.md deleted file mode 100644 index 151eee6..0000000 --- a/ChangeLog.md +++ /dev/null @@ -1,3 +0,0 @@ -# ChangeLog - -* (1 September 2015). Initial Release diff --git a/README.md b/README.md index a8971ff..57ba67c 100644 --- a/README.md +++ b/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. -2. In the WordPress dashboard, navigation to the *Plugins* page +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.” + +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/admin` is for all dashboard-specific functionality +* `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 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. \ No newline at end of file +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. diff --git a/plugin-name/trunk/admin/class-plugin-name-admin.php b/plugin-name/trunk/admin/class-plugin-name-admin.php index 1b365f2..3ef8d60 100644 --- a/plugin-name/trunk/admin/class-plugin-name-admin.php +++ b/plugin-name/trunk/admin/class-plugin-name-admin.php @@ -1,20 +1,20 @@ 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 ); } diff --git a/plugin-name/trunk/admin/css/plugin-name-admin.css b/plugin-name/trunk/admin/css/plugin-name-admin.css index e46ea29..00c8c7f 100644 --- a/plugin-name/trunk/admin/css/plugin-name-admin.css +++ b/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. */ \ No newline at end of file diff --git a/plugin-name/trunk/admin/js/plugin-name-admin.js b/plugin-name/trunk/admin/js/plugin-name-admin.js index 2633d7c..864fdb2 100644 --- a/plugin-name/trunk/admin/js/plugin-name-admin.js +++ b/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 diff --git a/plugin-name/trunk/admin/partials/plugin-name-admin-display.php b/plugin-name/trunk/admin/partials/plugin-name-admin-display.php index 65e68f5..f237c07 100644 --- a/plugin-name/trunk/admin/partials/plugin-name-admin-display.php +++ b/plugin-name/trunk/admin/partials/plugin-name-admin-display.php @@ -1,9 +1,9 @@ domain, - FALSE, + false, dirname( dirname( plugin_basename( __FILE__ ) ) ) . '/languages/' ); diff --git a/plugin-name/trunk/includes/class-plugin-name-loader.php b/plugin-name/trunk/includes/class-plugin-name-loader.php index 16398d1..3d2febc 100644 --- a/plugin-name/trunk/includes/class-plugin-name-loader.php +++ b/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. - * @var 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. - * @var 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 string $hook The name of the WordPress action that is being registered. + * @param object $component A reference to the instance of the object on which the action is defined. + * @param string $callback The name of the function definition on the $component. + * @param int Optional $priority The priority at which the function should be fired. + * @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. - * @var 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. - * @var 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 string $hook The name of the WordPress filter that is being registered. + * @param object $component A reference to the instance of the object on which the filter is defined. + * @param string $callback The name of the function definition on the $component. + * @param int Optional $priority The priority at which the function should be fired. + * @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). - * @var 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. - * @var string $callback The name of the function definition on the $component. - * @var 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 array $hooks The collection of hooks that is being registered (that is, actions or filters). + * @param string $hook The name of the WordPress filter that is being registered. + * @param object $component A reference to the instance of the object on which the filter is defined. + * @param string $callback The name of the function definition on the $component. + * @param int Optional $priority The priority at which the function should be fired. + * @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 ) { diff --git a/plugin-name/trunk/includes/class-plugin-name.php b/plugin-name/trunk/includes/class-plugin-name.php index 1e292a6..a62ea40 100644 --- a/plugin-name/trunk/includes/class-plugin-name.php +++ b/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 diff --git a/plugin-name/trunk/plugin-name.php b/plugin-name/trunk/plugin-name.php index dc2b43b..2538a0f 100644 --- a/plugin-name/trunk/plugin-name.php +++ b/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__, array( 'Plugin_Name_Activator', 'activate' ) ); - -/** This action is documented in includes/class-plugin-name-deactivator.php */ -register_activation_hook( __FILE__, array( 'Plugin_Name_Deactivator', 'deactivate' ) ); +register_activation_hook( __FILE__, 'activate_plugin_name' ); +register_deactivation_hook( __FILE__, 'deactivate_plugin_name' ); /** * 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. diff --git a/plugin-name/trunk/public/class-plugin-name-public.php b/plugin-name/trunk/public/class-plugin-name-public.php index b42cb51..f147d05 100644 --- a/plugin-name/trunk/public/class-plugin-name-public.php +++ b/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 */ 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. - * @var string $version The version of this plugin. + * @param string $plugin_name The name of the 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 ); }