Summary: This article outlines the requirements for preparing a Wordpress Theme that includes a Plugin. This is for an item that would be uploaded to a Theme category. This article is Part 3 of the requirements for WordPress Theme authors. WordPress is a large topic, so you will also need Parts 1 - 6 of the requirements below;
- WordPress Theme Requirements Part 1 - General
- WordPress Requirements Part 2 - Features
- WordPress Requirements Part 3 - Theme Plugins (you are here!)
- WordPress Requirements Part 4 - Coding
- WordPress Requirements Part 5 - Theme Security
- WordPress Requirements Part 6 - Gutenberg
If you are a Code author looking for more information on Wordpress Plugins to upload to a code category, please refer to the Plugin Requirements.
Plugin Territory Functionality
Themes execute the presentation and styling of content, while plugins handle content creation and functionality. Anything users will lose upon switching themes is classified as plugin territory. Following are some common examples:
- Analytics code
- SEO options
- Non-design related meta boxes
- Resource caching
- Dashboard widgets
- Custom Post Types
- Custom Taxonomies
- Social media like, follow and, share buttons
Anything that falls into plugin territory must be added via a plugin.
Although design related metaboxes are allowed in the theme, it's recommended that all meta boxes/custom fields are added via a plugin (if you already use one). 'Design related' metaboxes are those that only change the visual presentation of the content, rather than which content is displayed. For example, switching between a light or dark style for the page; or choosing which order elements are displayed in.
Plugin Territory Fallbacks
Existing themes containing plugin territory functionality, as described above, must move this to a plugin by 31 May 2019.
To reduce the chance of users being negatively affected if they do not install/update the plugin, themes may choose to include a fallback until 30 November 2019. This is not compulsory.
During this time, we recommend that you display a message in the WordPress admin area / theme option page, informing users of what's coming, what they need to do and warning them of the consequences of not taking the necessary action.
Once the fallback period is over, the fallbacks must be removed
Third-Party Plugins & Libraries
Libraries and scripts included in a theme are considered to be part of the theme and must meet these requirements. For example, if Redux is included in the theme itself, it needs to comply with the above requirements, just as the rest of the theme does. The one exception is the TGM Plugin Activation library, where it has been generated using the ThemeForest option.
Note: Included third-party plugins do not need to meet these requirements, but theme-specific plugins must meet the WordPress Plugin Requirements.
As an Envato Author, you must ensure to meet the following requirements:
- You must keep included plugins and libraries up to date.
- You must make sure that themes work with the latest released version of an advertised compatible software, such as WordPress or WooCommerce, even if the Compatible With item attribute is set to an older version. As the third-party plugins or scripts may receive major/critical updates, it is unreasonable to expect customers to use old versions.
- If you choose to modify a third-party plugin for some reason, you must get the original author's permission in writing. You are then responsible for any bugs/security issues in the plugin. Any fixes in the original that apply to your version must be ported over as soon as they are released in the original.
- Removal of plugin purchase code verification from third party plugins used in your item is strictly prohibited. Please refer to the License FAQs for more information on including stock items within your larger stock project.
It is recommended that, where possible, support for third-party plugins is provided rather than reinventing the wheel. If a theme specific plugin is required, it must meet the WordPress Plugin Requirements.
If you include plugins with your theme, you must use the TGM Plugin Activation (TGM PA) library, or a TGM PA based solution, to allow the user to install them.
Note: You are no longer allowed to use non TGM PA based solutions or to include plugins without using any solution.
You must ensure to follow these requirements:
- Plugins must only be installed if the user:
- Is informed of what will be installed and
- Opts into this occurring (eg., by clicking a confirm button).
- The force_activation and force_deactivation TGM PA parameters must not be set to true.
- For plugins from wordpress.org, the latest version must be installed directly from wordpress.org rather than bundling them in the zip file. The source, external_url, and version TGM PA parameters must be left empty.
- For plugins included in the zip file, the version TGM PA parameter must be set and kept up to date (ie., it must match the actual version included in the zip file).
- You must not rename the original class-tgm-plugin-activation.php file to anything else. You will receive false positives when running the Envato Theme Check plugin if you do this.
- Bundled plugins must be included in the main zip file. You are allowed to offload the plugins to your server in order to reduce the size of the installable WordPress format zip file, as long as they are included elsewhere in the main zip.
- You must not hard code plugins into the theme’s code base. They must be included as proper plugins that are recognised as such by WordPress (ie., appear on the Plugins screen).
Out of the box
Themes must work out of the box before any plugins are activated. Full advertised functionality is not required, but they must do everything a basic WordPress theme should do, such as display posts, pages, archive pages, home page, blog page, search, etc., and they must be styled as closely as possible to the full design as shown in the demo.
Checking for Plugins
Do not use is_plugin_active() when checking whether a plugin is active or not. is_plugin_active() is not reliable as it depends on the plugin’s folder/filename(which may change). Instead, you can use function_exists() or class_exists() as these are more reliable. For more information, refer to Checking if a dependent plugin is active article.
Import & Export Plugin
It is recommended that themes provide importable demo content that allows users to set the theme up as close as possible to the demo site.
Note: It should only include as much content as needed to make it look like the demo site.
Importers must not add content without user permission. Importers must not overwrite current content without clear warnings to the user. Custom Importers must use the WP Filesystem API.
Import/export functionality should be included via a plugin such as One Click Demo Import, unless it’s necessary for it to be in the theme itself (For example, if being used in a setup wizard).
Built-In Health Check Utilities
If a built-in server health/theme requirements utility is provided, only users with switch_themes capability may have access to the utility.