-
Notifications
You must be signed in to change notification settings - Fork 0
Development
This plugin uses Composer to manage dependencies and development scripting, and Git for version control. Several Composer scripts and Git hooks are included in order to make development easier. It is recommended to use Microsoft Visual Studio Code (VSCode) as an IDE as there are also recommended plugins and settings that are bundled with this package that will allow for PHP Intellisense, live linting and live autoformatting of code when developing WP Backstage.
- PHP
7.4+
- Git
2.29+
- Composer
2.4+
- WordPress
5.8+
- Spin up a local WordPress environment using Local by Flywheel.
- Clone the plugin's repository to the WordPress install's plugins directory at
wp-content/plugins
. - Navigate to the "Plugins" screen in the WordPress admin dashboard.
- Locate WP Backstage in the plugins list and click "Activate" to activate the plugin.
Note: Though the plugin attempts to flush the WordPress rewrite rules on activation and deactivation, it is good practice to flush the rewrite rules manually by navigating to the permalink settings page at "Settings -> Permalinks" and clicking "Save".
Tests can be enabled by declaring theme support for wp-backstage
and setting tests-enabled
to true
. This will automatically enable all test configurations that come bundled with WP Backstage. Once this is added, navigate to "Settings -> Permalinks" and hit "Save" to flush the rewrite rules. It is good practice to flush the rewrite rules whenever you turn the tests on or off (or whenever any post type or taxonomy configuration changes).
add_theme_support( 'wp-backstage', array(
'tests-enabled' => true,
) );
The repository comes with a pre-commit
hook, found in the root of the project, that runs a build and adds the output to the commit automatically. This means that the developer rarely, if ever, needs to run a build. The developer can just write, and commit, ensuring that the translation file and generated API reference will always be in sync with the committed code.
Note: WP Backstage keeps the git hook scripts in the root of the project. When making changes to the
pre-commit
file, it is necessary to use theupdate-hooks
script to actually install them into the.git/hooks
directory. This is done automatically upon installing or updating dependencies with Composer.
The version needs to be updated manually, both in the README.md
file, and the php file comment at the top of the main wp-backstage.php
file.
The following is a list of all development commands available to be run with Composer. In most cases, these will be run for the developer in the normal course of development by using Composer and Git hooks.
After installing or updating, Composer will run the update-hooks
script which will install Git hooks like pre-commit
.
composer install
This will run both the build-pot
and build-docs
scripts.
composer run build
This will use the WP CLI's i18n command to build the languages/wp-backstage.pot
file.
composer run build-pot
This will use phpDocumentor to generate an API reference for the plugin automatically using the code and doc blocks. The output will be placed in /docs/reference
.
composer run build-docs
Runs the clean-pot
and clean-docs
scripts, removing all built files.
composer run clean
Removes the languages/wp-backstage.pot
file.
composer run clean-pot
Recursively remove all files from and including the docs/reference
directory.
composer run clean-docs
Install the Git hooks like pre-commit
found in the root of the project to the .git/hooks
directory. After making updates to the pre-commit
hook file found in the root, run this command to install it. This allows for simpler management of the Git hook scripts. Runs the remove-hooks
and add-hooks
scripts.
composer run update-hooks
Add the Git hooks like pre-commit
found in the root of the project to the .git/hooks
directory. Typically, the update-hooks
script should be used instead to install the Git hooks, as it will run the remove-hooks
script to remove existing hooks before installing the new ones.
composer run add-hooks
Remove all Git hooks from the .git/hooks
directory.
composer run remove-hooks
Runs the lint-php
script.
composer run lint
Uses PHP Code Sniffer (phpcs) managed by the configuration found in the phpcs.xml
file to lint php files using the WordPress coding standards.
composer run lint-php
Runs the fix-php
script.
composer run fix
Uses PHP Code Sniffer's Code Beautifier and Fixer (phpcbf) managed by the configuration found in the phpcs.xml
file to fix and format php files using the WordPress coding standards.
composer run fix-php
When adding a new field type, there are a few things to consider in order to make the field type work in all situations; including the customizer, movable and collapsible UI elements, etc.
- Add a
render_{field_type}
method to theWP_Backstage_Component
class. - Add a case for
{field_type}
using therender_{field_type}
method to theWP_Backstage_Component::render_field_by_type()
method. - Add a
$default_${field_type}_args
variable to theWP_Backstage_Component
class if the field has extra arguments. - Add
{field_type}
to the$non_regular_text_fields
array variable on theWP_Backstage_Component
class if necessary. - Add
{field_type}
to the$remove_label_for_fields
array variable on theWP_Backstage_Component
class if necessary. - Add
{field_type}
to the$textarea_control_fields
array variable on theWP_Backstage_Component
class if necessary. - Add a
sanitize_{field_type}
method to theWP_Backstage_Component
class. - Add a case for
{field_type}
using thesanitize_{field_type}
method to theWP_Backstage_Component::sanitize_field()
method. - Add a case for
{field_type}
referencing thesanitize_{field_type}
method to theWP_Backstage_Component::get_sanitize_callback()
method. - Add a case for
{field_type}
to format the value to theWP_Backstage_Component::format_field_value()
method. - Add a case for
{field_type}
to thesetControlElementValue()
JS function inWP_Backstage::inline_nav_menu_item_customizer_script()
method. - Add a case for
{field_type}
to theinitControlElementChangeHandler()
JS function inWP_Backstage::inline_nav_menu_item_customizer_script()
method. - If necessary, add an
inline_{field_type}_style
method to theWP_Backstage
class, and hook toadmin_print_styles
. - If necessary, add an
inline_{field_type}_script
method to theWP_Backstage
class, and hook toadmin_print_footer_scripts
. This should attach functionality to thewindow.wpBackstage.{fieldType}
object and should have at minimum aninit
andinitAll
method. These methods should then be triggered in the inline JS functions for all components in theWP_Backstage
class. See Field JavaScript for boilerplate code. - Add test examples to the
$all_fields
array in thewp_backstage_init()
function inexamples/tests.php
file. - Add documentation to the Fields Wiki.
<script
id="wp_backstage_{field_type}_script"
type="text/javascript">
(function($) {
function init(field = null) {
const fieldId = field.getAttribute('data-field-id');
const input = field.querySelector('#' + fieldId);
// Initialize the field.
}
function destroy(field = null) {
const fieldId = field.getAttribute('data-field-id');
const input = field.querySelector('#' + fieldId);
// Destroy the field.
}
function initAll(container = null) {
container = container || document;
const fields = container.querySelectorAll('.wp-backstage-field--type-{field-type}');
if (fields && (fields.length > 0)) {
for (var i = 0; i < fields.length; i++) {
init(fields[i]);
}
}
}
function destroyAll(container = null) {
container = container || document;
const fields = container.querySelectorAll('.wp-backstage-field--type-{field-type}');
if (fields && (fields.length > 0)) {
for (var i = 0; i < fields.length; i++) {
destroy(fields[i]);
}
}
}
window.wpBackstage.{fieldType} = Object.assign(window.wpBackstage.{fieldType}, {
initAll: initAll,
init: init,
destroyAll: destroyAll,
destroy: destroy,
});
})(jQuery);
</script>
Note: Replace
{field_type}
with the field type in snake case. Replace{fieldType}
with the field type in camel case. Replace{field-type}
with the the field type in param case.
Create standardized and deployable WordPress objects like post types with meta boxes and custom fields, taxonomy terms with custom fields, options pages with custom fields and widgets with custom fields; and extend existing WordPress objects like pages, posts, attachments, categories, tags, users and nav menu items.
Website | GitHub | Docs | Issues | API Reference
© Copyright 2018-2022 Dreamsicle. All Rights Reserved.