This should fix the incorrect pattern of using a variable where we
should be using the plugin-name instead. Same goes for any translatable
strings within the plugin (no more using $this->plugin-name etc).
Moving the activation and deactivation hooks into its own functions, makes so we dont have to include class-plugin-name-deactivator and class-plugin-name-activator on every page load.
* leaving the de/activation code here for now
* moving all bootstrap code into class-plugin-name.php
* setting up this file to fire the plugin so that it's prepared to handle any hooks given to the loader
also getting rid of the version constant in place of a properly, defining a single entry point with the run function, and defining the plugin slug as a property
as per GaryJones notes, "You can't have tags come before the short / long description, otherwise the descriptions end up as part of a multiline tag."
removing these @TODO's until the team decides whether or not to replace them with something clearer, or to discuss it to the documentation
updating the documentation for the core admin plugin file with docblocks and example functions for how they should be used and their relationship to the public loader
updating the documentation for the core admin plugin file with docblocks and example functions for how they should be used and their relationship to the admin loader
this helps with cleaner diffs. It's also on one of the PSRs, and it's one of the WPCS rules. (ht @garyjones for the reminder)
Signed-off-by: Tom McFarlin <tom@tommcfarlin.com>
this are the files that will be used to define the actions and filters for their respective area of the plugin
Signed-off-by: Tom McFarlin <tom@tommcfarlin.com>
As per https://github.com/nextgenthemes/advanced-responsive-video-embedder/issues/7 I was informed that this would make my plugin work with PHP 5.2.x. I personally have not tested this code yet but I assume @andrejpavlovic did so I thought if this is the only thing that makes the Boilerplate require PHP 5.3 this might be a good change since WordPress itself only requires PHP 5.2.4.
Replacement `class-plugin-name-admin.php` for `class-plugin-admin.php` was made in `plugin-name.php` on line 72. The change better allows find-replace functionality.
Removing `load_plugin_textdomain` and leaving only `load_textdomain`.
This is standard as per new WordPress practices[0].
Ultimately, it makes language files more portable as they are still accessible via WordPress even if the plugin developer did not include them with the plugin itself.
Related #120
[0] d2eb67079b (commitcomment-4644357)
Signed-off-by: Tom McFarlin <tom@tommcfarlin.com>
Removing `load_plugin_textdomain` and leaving only `load_textdomain`.
This is standard as per new WordPress practices[0].
Ultimately, it makes language files more portable as they are still accessible via WordPress even if the plugin developer did not include them with the plugin itself.
Related #120
[0] d2eb67079b (commitcomment-4644357)
Signed-off-by: Tom McFarlin <tom@tommcfarlin.com>
With the move to /admin and /public directory, the class-plugin-name-admin.php needed to be changed to use __DIR__ instead of __FILE__ to create the $plugin_basename, otherwise the hook would be something like plugin_action_links_plugin-name/admin/plugin-name.php which doesn't work.
Perhaps mention uninstall.php in stead?
```
// Register hooks that are fired when the plugin is activated or deactivated.
// When the plugin is deleted, the uninstall.php file is loaded.
```
I am not sure if it's a good idea to use 'read' here, as more people will use the plugins page for options that subscribers... should never see.
I am not blaming you, it was me not paying attention but after migrating my plugin to this awesome boilerplate it ended up on WP.org with 'read' for the entire options page and people are now complaining ;)
We assume that someone defining WP_LANG_DIR will do so without a trailing slash, since we then add our own before adding in the rest of the path to the .mo file.
This change gets removes that assumption by removing our own slash from the string, and wrapping WP_LANG_DIR in trailingslashit() instead.
* Moving the activation hooks outside of the class and marking the methods as static
* Removing the @version tag from everything but the core plugin class
* Removing deprecating @subpackage tags
* Renaming the changelog filename to follow the canonical convention
* Including an `assets` directory with sample images and instructions for how to use it
* Finalized page-level documentation to the PHP files
* Moving to the plugin boilerplate to its own class
* Adding DocBlocks to the views
* Generalizing the name, language, and email address in the `.pot` file
* Updating the DocBlock in the uninstall file
* Adding the 'Domain Path' to the header of the plugin file
* Moving the changelog into its own file
* Updating GPL licensing and adding a note about licensing with the GPL and the Apache license
* Removing terminating code comments from the admin view
* Removing the localization functions from plugin page parameters
* Adding 'Text Domain' to the plugin header
* Adding gettext and plural forms to the `.pot` file
* Replacing all midline tabs and replacing them with tabs
* Removing tabs and spaces from empty lines
* Adding a security check to prevent the plugin file from being accessed directly
* Improving spacing to better comply with coding conventions
* Adding LICENSE.txt and removing it from the plugin's header
## 2.2.1 (10 May 2013)
* Updating the `.pot` file as it was resulting in a minor error in one of the translation tools.
## 2.2.0 (10 May 2013)
* Updating the README so the demo changelog is more accurate
* Renaming the core plugin file to match the name of the plugin (specifically `plugin-boilerplate.php` from `plugin.php`)
* Removing the default `.po` file and introducing the `plugin-boilerplate.pot` catalog
* Removing all terminating code block comments
* Adding braces around the `uninstall.php` conditional
* Changing access modifiers from `private` to `protected`. See [this discussion](https://github.com/tommcfarlin/WordPress-Plugin-Boilerplate/issues/36) for more details.
* Removing redundant headers since properties, constructors, and methods are clearly defined and segmented throughout the code.
## 2.1.0 (9 May 2013)
* Refactoring the ternary operator in the constructor to make the code more readable for developers and to avoid returning an orphaned object
* Updating certain function names to use verbs to be clearer in their purpose
* Updating versioning in the plugin and in the `README` to use the `x.y.z` convention rather than the `x.y` convention
* Adding class property DocBlocks
* Adding `@since` tags to each of the DocBlocks for methods
* Cleaning up the PHP code formatting for easier readability
* Adding a note about POEdit and it being used as my preferred translations
* Automatically displaying the name of the plugin admin page
* Changing 'directives' to 'tags'
* Updating page-level DocBlocks for `plugin.php` and for `uninstall.php`
## 2.0.1 (7 May 2013)
* Updating the year of the release of 2.0
## 2.0.0 (7 May 2013)
* Disabling the admin menu by default
* Initializing the attributes
* Combining the `admin_open` and `admin_close` into a single `admin` view
* Bringing some of the code up to the WordPress coding standards
* Added access modifiers for functions
* Implemented the single pattern
* **japh**. Merged upstream changes, maintained separation of uninstall functionality
* **mikkelbreum**. Restricted scripts and styles to load only on plugin settings page if it is enabled.
* **mikkelbreum**. Added the option for a plugin settings page
* **mikkelbreum**. Removed the need to customize the URL for `wp_enqueue_style` and `wp_enqueue_scripts`
* **mikkelbreum**. Corrected action book for `register_admin_styles`
* **tbwiii**. Listed jQuery as a dependency for both JavaScript sources
* **japh**. Added an `uninstall.php` placeholder
* **leewillis77**. Improved the way language files are loaded
* **wesbos**. Updated the year to 2013
## 1.0 (29 November 2012)
* Official Release
## Author Information
The WordPress Plugin Boilerplate was originally started and is maintained by [Tom McFarlin](http://twitter.com/tommcfarlin/), but is constantly under development thanks to the contributions from the many WordPress developers throughout the world.
The WordPress Plugin Boilerplate serves as a foundation and aims to provide a clear and consistent guide for building your WordPress plugins.
## Features
* The Plugin Boilerplate is fully-based on the WordPress [Plugin API](http://codex.wordpress.org/Plugin_API)
* Uses [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) conventions for easily following the code
* Liberal use of `TODO` to guide you through what you need to change
* Uses a strict file organization scheme to make sure the assets are easily maintainable
* Note that this boilerplate uses `plugin.po` to provide a translation file. This is compatible with [POEdit](http://www.poedit.net/)
A standardized, organized, object-oriented foundation for building high-quality WordPress Plugins.
## Contents
The WordPress Plugin Boilerplate includes the following files:
* This `README`
* A subdirectory called `plugin-boilerplate`
* `.gitignore`. Used to exclude certain files from the repository.
* `CHANGELOG.md`. The list of changes to the core project.
* `README.md`. The file that you’re currently reading.
* A `plugin-name` directory that contains the source code - a fully executable WordPress plugin.
## Features
1. Copy the `plugin-boilerplate` directory into your `wp-content/plugins` directory
2. Navigate to the *Plugins* dashboard page
3. Locate the menu item that reads *TODO*
4. Click on *Activate*
* The Boilerplate is based on the [Plugin API](http://codex.wordpress.org/Plugin_API), [Coding Standards](http://codex.wordpress.org/WordPress_Coding_Standards), and [Documentation Standards](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/).
* All classes, functions, and variables are documented so that you know what you need to change.
* The Boilerplate uses a strict file organization scheme that corresponds both to the WordPress Plugin Repository structure, and that makes it easy to organize the files that compose the plugin.
* The project includes a `.pot` file as a starting point for internationalization.
This will activate the WordPress Plugin Boilerplate. Because the Boilerplate has no real functionality, nothing will be added to WordPress; however, this demonstrates exactly how your plugin should behave as you're working with it.
## Installation
If you opt to uncomment Line 77 which contains the following line:
The Boilerplate can be installed directly into your plugins folder "as-is". You will want to rename it and the classes inside of it to fit your needs. For example, if your plugin is named 'example-me' then:
Then a new menu item will be added to the *Plugins* menu.
It's safe to activate the plugin at this point. Because the Boilerplate has no real functionality there will be no menu items, meta boxes, or custom post types added until you write the code.
## WordPress.org Preparation
The original launch of this version of the boilerplate included the folder structure needed for using your plugin on WordPress.org. That folder structure has been moved to its own repo here: https://github.com/DevinVinson/Plugin-Directory-Boilerplate
## Recommended Tools
### i18n Tools
The WordPress Plugin Boilerplate uses a variable to store the text domain used when internationalizing strings throughout the Boilerplate. To take advantage of this method, there are tools that are recommended for providing correct, translatable files:
Any of the above tools should provide you with the proper tooling to internationalize the plugin.
## License
The WordPress Plugin Boilerplate is licensed under the GPL v2 or later.
> This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2, as
published by the Free Software Foundation.
> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation.
> This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
> This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
> You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
> You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
A copy of the license is included in the root of the plugin’s directory. The file is named `LICENSE`.
## Important Notes
### Licensing
The WordPress Plugin Boilerplate is licensed under the GPL2+ or later; however, if you opt to use third-party frameworks
such as [Bootstrap](http://twitter.github.io/bootstrap/) in your work, then you should be aware of this:
The WordPress Plugin Boilerplate is licensed under the GPL v2 or later; however, if you opt to use third-party code that is not compatible with v2, then you may need to switch to using code that is GPL v3 compatible.
> The most likely occurrence of this issue is with Themes developed using Twitter Bootstrap. When reviewing such Themes, please be sure to check that, if the Theme is licensed under GPL, that the license specifies either unversioned GPL, or GPLv3.0.
For reference, [here's a discussion](http://make.wordpress.org/themes/2013/03/04/licensing-note-apache-and-gpl/) that covers the Apache 2.0 License used by [Bootstrap](http://twitter.github.io/bootstrap/).
For reference, [here's the full conversation](http://make.wordpress.org/themes/2013/03/04/licensing-note-apache-and-gpl/).
### Includes
## Assets
Note that if you include your own classes, or third-party libraries, there are three locations in which said files may go:
The assets directory provides two files that are used to represent plugin header images.
* `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
When committing your work to the WordPress Plugin Repository, these files should reside in their own `assets` directory, not in the root of the plugin. The initaly repository will contain three directories:
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.
1. `branches`
2. `tags`
3. `trunk`
The example code provided shows how to register your hooks with the Loader class.
You'll need to add an `assets` directory into the root of the repository. So the final directory structure should include *four* directories:
### What About Other Features?
1. `assets`
2. `branches`
3. `tags`
4. `trunk`
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).
Next, copy the contents of the `assets` directory that are bundled with the Boilerplate into the root of the repository. This is how the WordPress Plugin Repository will retrieving the plugin header image.
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.
Of course, you'll want to customize the header images from the place holders that are provided with 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, these features have been removed and will be introduced in other editions, and will be listed and maintained on the project homepage.
For more, in-depth information about this, read [this post](http://make.wordpress.org/plugins/2012/09/13/last-december-we-added-header-images-to-the/) by Otto.
# Credits
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 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
If you’re interested in writing any documentation or creating tutorials please [let me know](http://devinvinson.com/contact/) .