Home

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.

Getting Started

Initialize a configuration

Setting up backstage is simple. Create a function in the functions.php file of the theme, and hook it to the after_setup_theme hook.

function wp_backstage_init() {

	// Place backstage configurations here.

}

add_action( 'after_setup_theme', 'wp_backstage_init', 10 );

Working Example

See the following example of a working configuration. This example will create a custom post type with a single custom meta box containing a single text field. Ensure to prefix the function with the theme's prefix and replace all text domains with the theme's text domain. Once this is placed, visit "Settings -> Permalinks" in the WordPress admin dashboard and hit "Save" to flush the WordPress rewrite rules.

function wp_backstage_init() {

	WP_Backstage_Post_Type::add(
		'wp_backstage_post',
		array(
			'menu_name'     => __( 'Test Posts', 'wp_backstage_examples' ),
			'singular_name' => __( 'Test Post', 'wp_backstage_examples' ),
			'plural_name'   => __( 'Test Posts', 'wp_backstage_examples' ),
			'description'   => __( 'This is a test non-hierarchical post type.', 'wp_backstage_examples' ),
			'singular_base' => 'test-post',
			'archive_base'  => 'test-posts',
			'rest_base'     => 'test-posts',
			'taxonomies'    => array( 'category', 'post_tag' ),
			'glance_item'   => true,
			'meta_boxes'    => array(
				array(
					'id'          => 'wp_backstage_post_fields',
					'title'       => __( 'All Fields', 'wp_backstage_examples' ),
					'description' => __( 'These extra meta fields control further details about the test post. <a href="#">Example Link</a>', 'wp_backstage_examples' ),
					'context'     => 'normal',
					'priority'    => 'high',
					'fields'      => array(
                        array(
                            'type'        => 'text',
                            'name'        => 'wp_backstage_text_field',
                            'label'       => __( 'Text', 'wp_backstage_examples' ),
                            'description' => __( 'Enter some text.', 'wp_backstage_examples' ),
                            'has_column'  => true,
                            'is_sortable' => true,
                        ),
                    ),
				),
			),
		)
	);
}

add_action( 'after_setup_theme', 'wp_backstage_init', 10 );

Plugin Dependencies

This plugin currently requires that the Gutenberg Editor be disabled. To accomplish this in the cleanest possible way, two plugins should be installed.

Development Overview

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 fixing of code when developing WP Backstage.

Requirements

PHP 7.4+
Git 2.29+
Composer 2.4+

Setting Up Development

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".

Git Hooks

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 the update-hooks script to actually install them into the .git/hooks directory. This is done automatically upon installing or updating dependencies with Composer.

Bumping the version

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.

Development Commands

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.

Install dependencies

After installing or updating, Composer will run the update-hooks script which will install Git hooks like pre-commit.

composer install

Run a build

This will run both the build-pot and build-docs scripts.

composer run build

Build the translation file

This will use the WP CLI's i18n command to build the languages/wp-backstage.pot file.

composer run build-pot

Build the API reference

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

Clean build

Runs the clean-pot and clean-docs scripts, removing all built files.

composer run clean

Clean the translation file

Removes the languages/wp-backstage.pot file.

composer run clean-pot

Clean the API reference

Recursively remove all files from and including the docs/reference directory.

composer run clean-docs

Update git hooks

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 git 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 git hooks

Remove all Git hooks from the .git/hooks directory.

composer run remove-hooks

Lint all code

Runs the lint-php script.

composer run lint

Lint php files

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

Fix and format all code

Runs the fix-php script.

composer run fix

Fix and format php files

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

WP Backstage ― A WordPress Plugin