mirror of
https://github.com/inretio/WordPress-Plugin-Boilerplate
synced 2024-12-22 11:53:53 +02:00
Documenting classes
Documenting classes that are core to each plugin, while also leaving other classes undocumented for an implementation-specific basis.
This commit is contained in:
Tom McFarlin
parent
f09ca373d8
commit
560e5959a5
6 changed files with 137 additions and 135 deletions
|
|
@ -24,29 +24,27 @@
|
|||
class Plugin_Name_Admin {
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
* The version of this plugin.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access private
|
||||
* @var type $var Description.
|
||||
* @var string $version The current version of this plugin.
|
||||
*/
|
||||
private $version;
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
* Initialize the class and set its properties.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access private
|
||||
* @var type $var Description.
|
||||
* @access public
|
||||
* @var string $version The version of this plugin.
|
||||
*/
|
||||
public function __construct( $version ) {
|
||||
$this->version = $version;
|
||||
}
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
*
|
||||
* Long description.
|
||||
* Register the stylesheets for the Dashboard.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*/
|
||||
|
|
@ -69,9 +67,7 @@ class Plugin_Name_Admin {
|
|||
}
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
*
|
||||
* Long description.
|
||||
* Register the JavaScript for the dashboard.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
/**
|
||||
* All of the CSS for your Dashboard-specific functionality should be
|
||||
* All of the CSS for your dashboard-specific functionality should be
|
||||
* included in this file.
|
||||
*/
|
||||
|
|
@ -1,22 +1,25 @@
|
|||
<?php
|
||||
|
||||
/**
|
||||
* Define a short description for what this class does (no period)
|
||||
* Define the internationalization functionality.
|
||||
*
|
||||
* Loads and defines the internationalization files for this plugin
|
||||
* so that its ready for translation.
|
||||
*
|
||||
* @link http://example.com
|
||||
* @since 1.0.0
|
||||
*
|
||||
* @package Plugin_Name
|
||||
* @subpackage Plugin_Name/includes
|
||||
* @author Your Name <email@example.com>
|
||||
* @license GPL-2.0+
|
||||
* @link http://example.com
|
||||
* @copyright 2014 Your Name or Company Name
|
||||
* @since 1.0.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* Define a short description for what this class does.
|
||||
* Define the internationalization functionality.
|
||||
*
|
||||
* Define a longer description for the purpose of this class.
|
||||
* Loads and defines the internationalization files for this plugin
|
||||
* so that its ready for translation.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @package Plugin_Name
|
||||
* @subpackage Plugin_Name/includes
|
||||
* @author Your Name <email@example.com>
|
||||
|
|
@ -24,7 +27,7 @@
|
|||
class Plugin_Name_i18n {
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
* Short Description. (use period)
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access private
|
||||
|
|
@ -33,27 +36,25 @@ class Plugin_Name_i18n {
|
|||
private $domain;
|
||||
|
||||
/**
|
||||
*
|
||||
* Load the plugin text domain for translation.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*/
|
||||
public function load_plugin_textdomain() {
|
||||
|
||||
$locale = apply_filters( 'plugin_locale', get_locale(), $this->domain );
|
||||
|
||||
load_textdomain( $this->domain, trailingslashit( WP_LANG_DIR ) . $this->domain . '/' . $this->domain . '-' . $locale . '.mo' );
|
||||
load_plugin_textdomain( $this->domain, FALSE, basename( plugin_dir_path( dirname( __FILE__ ) ) ) . '/languages/' );
|
||||
load_plugin_textdomain(
|
||||
$this->domain,
|
||||
FALSE,
|
||||
dirname( dirname( plugin_basename( __FILE__ ) ) ) . '/languages/'
|
||||
);
|
||||
|
||||
}
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
*
|
||||
* Long description.
|
||||
* Set the domain equal to that of the specified domain.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @param float $domain TODO
|
||||
* @param string $domain The domain that represents the locale of this plugin.
|
||||
*/
|
||||
public function set_domain( $domain ) {
|
||||
$this->domain = $domain;
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?php
|
||||
|
||||
/**
|
||||
* Define a short description for what this class does (no period)
|
||||
* Register all actions and filters
|
||||
*
|
||||
* @package Plugin_Name
|
||||
* @subpackage Plugin_Name/includes
|
||||
|
|
@ -13,9 +13,11 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
* Define a short description for what this class does.
|
||||
* Register all actions and filters.
|
||||
*
|
||||
* Define a longer description for the purpose of this class.
|
||||
* Maintain a list of all hooks that are registered throughout
|
||||
* the plugin, and register them with the WordPress API. Call the
|
||||
* run function to execute the list of actions and filters.
|
||||
*
|
||||
* @package Plugin_Name
|
||||
* @subpackage Plugin_Name/includes
|
||||
|
|
@ -24,28 +26,28 @@
|
|||
class Plugin_Name_Loader {
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
* The array of actions registered with WordPress.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access private
|
||||
* @var type $var Description.
|
||||
* @access protected
|
||||
* @var array $actions The actions registered with WordPress to fire when the plugin loads.
|
||||
*/
|
||||
protected $actions;
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
* The array of filters registered with WordPress.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access private
|
||||
* @var type $var Description.
|
||||
* @access protected
|
||||
* @var array $filters The filters registered with WordPress to fire when the plugin loads.
|
||||
*/
|
||||
protected $filters;
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
* Initialize the collections used to maintain the actions and filters.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access private
|
||||
* @access public
|
||||
*/
|
||||
public function __construct() {
|
||||
|
||||
|
|
@ -55,51 +57,57 @@ class Plugin_Name_Loader {
|
|||
}
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
* Add a new action to the collection to be registered with WordPress.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access private
|
||||
* @var type $var Description.
|
||||
* @var type $var Description.
|
||||
* @var type $var Description.
|
||||
* @var type Optional $var Description.
|
||||
* @access public
|
||||
* @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 array Optional $accepted_args The collection of arguments that should be passed to the $callback.
|
||||
*/
|
||||
public function add_action( $hook, $component, $callback, $priority = 10 ) {
|
||||
$this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority );
|
||||
public function add_action( $hook, $component, $callback, $priority = 10, $accepted_args = array() ) {
|
||||
$this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority, $accepted_args );
|
||||
}
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
* Add a new filter to the collection to be registered with WordPress.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access private
|
||||
* @var type $var Description.
|
||||
* @var type $var Description.
|
||||
* @var type $var Description.
|
||||
* @var type Optional $var Description.
|
||||
* @access public
|
||||
* @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 array Optional $accepted_args The collection of arguments that should be passed to the $callback.
|
||||
*/
|
||||
public function add_filter( $hook, $component, $callback, $priority = 10 ) {
|
||||
$this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority );
|
||||
public function add_filter( $hook, $component, $callback, $priority = 10, $accepted_args = array() ) {
|
||||
$this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority, $accepted_args = array() );
|
||||
}
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
* A utility function that is used to register the actions and hooks into a single
|
||||
* collection.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access private
|
||||
* @var type $var Description.
|
||||
* @var type $var Description.
|
||||
* @var type $var Description.
|
||||
* @var type $var Description.
|
||||
* @var type Optional $var Description.
|
||||
* @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 array Optional $accepted_args The collection 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 ) {
|
||||
private function add( $hooks, $hook, $component, $callback, $priority, $accepted_args ) {
|
||||
|
||||
$hooks[] = array(
|
||||
'hook' => $hook,
|
||||
'component' => $component,
|
||||
'callback' => $callback,
|
||||
'priority' => $priority
|
||||
'hook' => $hook,
|
||||
'component' => $component,
|
||||
'callback' => $callback,
|
||||
'priority' => $priority,
|
||||
'accepted_args' => $accepted_args
|
||||
);
|
||||
|
||||
return $hooks;
|
||||
|
|
@ -107,28 +115,18 @@ class Plugin_Name_Loader {
|
|||
}
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
*
|
||||
* Long description.
|
||||
* Register the filters and actions with WordPress.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*/
|
||||
public function run() {
|
||||
|
||||
/**
|
||||
* TODO:
|
||||
* This function is used to define the various hooks that are shared in the
|
||||
* both the dashboard and the public-facing areas of the plugin. This is
|
||||
* achieved via dependency injection by passing an instance of Plugin_Name
|
||||
* into this class.
|
||||
*/
|
||||
|
||||
foreach ( $this->filters as $hook ) {
|
||||
add_filter( $hook['hook'], array( $hook['component'], $hook['callback'] ), $hook['priority'] );
|
||||
add_filter( $hook['hook'], array( $hook['component'], $hook['callback'] ), $hook['priority'], $hook['accepted_args'] );
|
||||
}
|
||||
|
||||
foreach ( $this->actions as $hook ) {
|
||||
add_action( $hook['hook'], array( $hook['component'], $hook['callback'] ), $hook['priority'] );
|
||||
add_action( $hook['hook'], array( $hook['component'], $hook['callback'] ), $hook['priority'], $hook['accepted_args'] );
|
||||
}
|
||||
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,11 +1,15 @@
|
|||
<?php
|
||||
|
||||
/**
|
||||
* Short Description (no period)
|
||||
* The core plugin file
|
||||
*
|
||||
* Long Description.
|
||||
* This is the core plugin file that is used to define internationalization,
|
||||
* dashboard-specific hooks, and public-facing site hooks.
|
||||
*
|
||||
* @link http://example.com/
|
||||
* Also maintains the unique identifier of this plugin as well as the current
|
||||
* version of the plugin.
|
||||
*
|
||||
* @link http://example.com
|
||||
* @since 1.0.0
|
||||
*
|
||||
* @package Plugin_Name
|
||||
|
|
@ -25,34 +29,39 @@
|
|||
class Plugin_Name {
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
* The loader that's responsible for maintaining and registering all hooks that power
|
||||
* the plugin.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access (private, protected, or public)
|
||||
* @var type $var Description.
|
||||
* @access protected
|
||||
* @var type Plugin_Name_Loader Maintains and registers all hooks for the plugin.
|
||||
*/
|
||||
protected $loader;
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
* The unique identifier of this plugin.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access (private, protected, or public)
|
||||
* @var type $var Description.
|
||||
* @access protected
|
||||
* @var string $plugin_slug The slug used to uniquely identify this plugin.
|
||||
*/
|
||||
protected $plugin_slug;
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
* The current version of the plugin.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access (private, protected, or public)
|
||||
* @var type $var Description.
|
||||
* @access protected
|
||||
* @var string $version The current version of the plugin.
|
||||
*/
|
||||
protected $version;
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
* Define the core functionality of the plugin.
|
||||
*
|
||||
* Set the plugin slug 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
|
||||
* the public-facing side of the site.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*/
|
||||
|
|
@ -69,12 +78,20 @@ class Plugin_Name {
|
|||
}
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
* Load the required dependencies for this plugin.
|
||||
*
|
||||
* Long Description.
|
||||
* Include the following files that make up the plugin:
|
||||
*
|
||||
* - 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_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
|
||||
* with WordPress.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access (for functions: only use if private)
|
||||
* @access private
|
||||
*/
|
||||
private function load_dependencies() {
|
||||
|
||||
|
|
@ -106,57 +123,57 @@ class Plugin_Name {
|
|||
}
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
* Define the locale for this plugin for internationalization.
|
||||
*
|
||||
* Long Description.
|
||||
* Uses the Plugin_Name_i18n class in order to set the domain and to register the hook
|
||||
* with WordPress.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access (for functions: only use if private)
|
||||
* @access private
|
||||
*/
|
||||
private function set_locale() {
|
||||
|
||||
$plugin_i18n = new Plugin_Name_i18n();
|
||||
$plugin_i18n->set_domain( $this->get_plugin_slug() );
|
||||
|
||||
$this->loader->add_action( 'plugins_loaded', $plugin_i18n, 'load_plugin_textdomain' );
|
||||
|
||||
}
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
*
|
||||
* Long Description.
|
||||
* Register all of the hooks related to the dashboard functionality
|
||||
* of the plugin.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access (for functions: only use if private)
|
||||
* @access private
|
||||
*/
|
||||
private function define_admin_hooks() {
|
||||
|
||||
$plugin_admin = new Plugin_Name_Admin( $this->get_version() );
|
||||
|
||||
$this->loader->add_action( 'admin_enqueue_scripts', $plugin_admin, 'enqueue_styles' );
|
||||
$this->loader->add_action( 'admin_enqueue_scripts', $plugin_admin, 'enqueue_scripts' );
|
||||
|
||||
}
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
*
|
||||
* Long Description.
|
||||
* Register all of the hooks related to the public-facing functionality
|
||||
* of the plugin.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access (for functions: only use if private)
|
||||
* @access private
|
||||
*/
|
||||
private function define_public_hooks() {
|
||||
|
||||
$plugin_public = new Plugin_Name_Public( $this->get_version() );
|
||||
|
||||
$this->loader->add_action( 'wp_enqueue_scripts', $plugin_public, 'enqueue_styles' );
|
||||
$this->loader->add_action( 'wp_enqueue_scripts', $plugin_public, 'enqueue_scripts' );
|
||||
|
||||
}
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
*
|
||||
* Long Description.
|
||||
* Execute the loader to execute all of the hooks with WordPress.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*/
|
||||
|
|
@ -165,36 +182,31 @@ class Plugin_Name {
|
|||
}
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
*
|
||||
* Long Description.
|
||||
* The slug of the plugin used to uniquely identify it within the context of
|
||||
* WordPress and to define internationalization functionality.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @return type Description
|
||||
* @return string The slug of the plugin.
|
||||
*/
|
||||
public function get_plugin_slug() {
|
||||
return $this->plugin_slug;
|
||||
}
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
*
|
||||
* Long Description.
|
||||
* The reference to the class that orchestrates the hooks with the plugin.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @return type Description
|
||||
* @return Plugin_Name_Loader Orchestrates the hooks of the plugin.
|
||||
*/
|
||||
public function get_loader() {
|
||||
return $this->loader;
|
||||
}
|
||||
|
||||
/**
|
||||
* Short Description. (use period)
|
||||
*
|
||||
* Long Description.
|
||||
* Retrieve the version number of the plugin.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @return type Description
|
||||
* @return string The version number of the plugin.
|
||||
*/
|
||||
public function get_version() {
|
||||
return $this->version;
|
||||
|
|
|
|||
|
|
@ -24,30 +24,27 @@
|
|||
class Plugin_Name_Public {
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
* The version of this plugin.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @access private
|
||||
* @var type $var Description.
|
||||
* @var string $version The current version of this plugin.
|
||||
*/
|
||||
private $version;
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
*
|
||||
* Long description.
|
||||
* Initialize the class and set its properties.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @param float $version TODO
|
||||
* @access public
|
||||
* @var string $version The version of this plugin.
|
||||
*/
|
||||
public function __construct( $version ) {
|
||||
$this->version = $version;
|
||||
}
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
*
|
||||
* Long description.
|
||||
* Register the stylesheets for the public-facing side of the site.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*/
|
||||
|
|
@ -70,9 +67,7 @@ class Plugin_Name_Public {
|
|||
}
|
||||
|
||||
/**
|
||||
* Short description. (use period)
|
||||
*
|
||||
* Long description.
|
||||
* Register the stylesheets for the public-facing side of the site.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in a new issue