Advanced Sidebar Menu – Version 9.5

Version 9.5 of the Advanced Sidebar Menu plugin is now available and ready for general use.

Version 9.5 focused on modernizing the plugin code to put it inline with recent versions of WordPress core.

The changes listed in this article are actually a combination of version 9.4 and 9.5. Version 9.4 created the foundation for changes in 9.5.

CSS Class Targeting for Menu Styles

Until now the menu styles were rendered to the site while targeting the id of the menu. It looked something like this.

CSS

Using the id for targeting worked great for the menu styles coming from the block settings but made it difficult for themes to override or provide default styles.

Going forward the styles are now generated using a CSS class like so.

CSS

You can see the styles are still essentially the same but now they use a CSS class.

Panel Based Title and Exclude Options

Previously the title and exclude options for pages were loaded within a meta box on the page edit screen. This worked well for compatibility with post types which do not support the block editor.

In version 6.3 of WordPress core, the API version 3 for blocks was introduced. API version 3 added support for loading the page/post editor inside an iframe. Besides all blocks being on API version 3, another requirement for the iframe to be loaded was to have no legacy meta boxes loaded on the page.

To conform with version 3 of the API and allow our plugin users to have iframe editors, we have not converted the meta box to a Gutenberg panel.

Advanced Sidebar

TITLE

Title used for this page’s link when it is displayed in the Advanced Sidebar menus.

Excluded

Exclude this page from all Advanced Sidebar menus.

The functionality remains the same, with a slightly enhanced ui. We left the legacy meta boxes intact for post types which do not support the block editor.

New Utility Methods

As part of our initiative to reduce duplication between our basic and PRO versions we have begun to expand our Utils class.

First we introduced a new Utils_Interface which defines the signature of what can be expected in our Utils class. This allows us to guarantee backward compatibility for sites which run different versions of basic and PRO.

Next we introduced a few new methods.

is_truthy

WordPress supports only a limited number of data types when storing things like post meta. WordPress also has many combinations of values which may be perceived as true. Instead of using loose comparison or filling every comparison with all the possible values, the is_truthy method will determine if a passed value should be considered true.

PHP

get_post_type_label

Throughout various widget and block settings we adjust the shown label to match the selected post type. For example, if you have selected a custom post type like “Product” in a block, any corresponding labels will automatically change to “Products” instead of “Pages.” To keep things consistent when calculating the current post type’s label, the new utility method will be used throughout the basic and PRO version.

PHP

/**                                                                          
 * Get the label for used post type.                                         
 *                                                                           
 * For adjusting widget option labels.                                       
 *                                                                           
 * @since 9.5.0                                                              
 *                                                                           
 * @param string $type   – Post type to get label for.                       
 * @param bool   $single – Singular label or plural.                         
 *                                                                           
 * @return string                                                            
 */                                                                          
public function get_post_type_label( string $type, $single = true ): string {}

is_empty

It is very common when checking a widget setting to need to first check if the setting exists and then make sure it is not an empty string. Instead of doing a isset( $settings[ $key ] ) || '' === $settings[ $key ] check for every value, the is_empty utility method now exists.

PHP

Interface/Trait Structure for Widget Classes

As the engineering community moves toward composition over inheritance it is time for the Advanced Sidebar Menu plugin to start doing the same.

Do a quick search for, “PHP composition over inheritance” and you will find a ton of us have been advocating for this change for a while.

Back in version 7.2 (2018) we introduced a widget abstract to provide some shared functionality as well some rules for our widget classes. Back then we were supporting PHP 5.2 and based on the available technology at the time, it was a nice improvement for our code.

Fast forward to the present world of static analysis, type definitions, interfaces, and traits and the abstract class structure gave us the following problems.

Very difficult or impossible to analyze array shapes.
Uncertainty on backward compatibility signatures which slows development.
Misunderstanding of functionality limitations.
Using the abstract for type hinting when a local class is more relevant and accurate.
Test coverage uncertainty.

Widget Interface

We begin the process of removing the widget abstract by introducing a new Widget interface. The interface gives the following benefits:

Guaranteed backwards compatibility between plugin versions.
Full class array shapes.
Separation of responsibility between the widget classes.

PHP

/**
 * Interface for the widget.
 *
 * @since  9.5.0
 *
 * @phpstan-template SETTINGS of array
 * @phpstan-template DEFAULTS of array
 */
interface Widget {
	/**
	 * Store the instance to this class.
	 * We do this manually because filters hit the instance before we
	 * get to self::form() and self::widget()
	 *
	 * @see   \WP_Widget::form_callback()
	 *
	 * @phpstan-param SETTINGS $instance
	 * @phpstan-param DEFAULTS $defaults
	 *
	 * @param array            $instance – widget settings.
	 * @param array            $defaults – defaults for all widgets.
	 *
	 * @phpstan-return SETTINGS
	 * @return array
	 */
	public function set_instance( array $instance, array $defaults ): array;

/**
	 * Is this checkbox checked?
	 *
	 * Checks first for a value then verifies the value = 'checked'.
	 *
	 * @param string $name – Name of checkbox.
	 *
	 * @return bool
	 */
	public function checked( $name ): bool;

/**
	 * Hide an element_key if a controlling_checkbox is checked.
	 *
	 * @param string $controlling_checkbox – Name of controlling_checkbox field which controls whether to hide this
	 *                                     element or not.
	 * @param string $element_key          – Match the `element_to_reveal` passed to $this->checkbox() for the checkbox
	 *                                     which controls this.
	 * @param bool   $reverse              – hide on check instead of show on check.
	 *
	 * @return void
	 */
	public function hide_element( $controlling_checkbox, $element_key = null, $reverse = false ): void;

/**
	 * Outputs a <input type="checkbox"> with id and name filled.
	 *
	 * @param string      $name              – Name of field.
	 * @param string|null $element_to_reveal – Element to reveal/hide when box is checked/unchecked.
	 *
	 * @return void
	 */
	public function checkbox( $name, $element_to_reveal = null ): void;
}

You’ll notice the interface support passing generic array shapes to allow static analysis to validate the array shapes as the methods are used.

Instance Trait

As we start to pull previously shared functionality out of the widget abstract, we’re going to introduce traits where beneficial. A traits allows us to satisfy the rules of an interface in a reusable yet optional way. The greatest benefit of using traits for us, outside of keeping things dry of course, is the ability to define the data shapes within the class during static analysis.

We started this process by introducing a new Instance trait.

PHP

Miscellaneous

Dropped support for PHP 7.0 in favor of 7.2.
Bumped minimum supported WordPress version to 6.1.
Tested to WordPress 6.4.3.
Fully support PHP 8.2.
Fixed translation loading in blocks.
Split REST API extending to a new \Advanced_Sidebar_Menu\Api\Rest\Page class.
Improved PHPCS, CSS, and JS linting.
Removed all uses of the deprecated @wordpress/elements package.
Bumped the required basic version to 9.1+.
Updated Yarn to version 4.
Updated Node to version 20.
Updated all block’s API version to 3.
Required PRO version 9.1.8+.
Converted deprecated block registering arguments to WordPress 6.1 version.
Fixed excluding of child items if the top level parent is excluded.
Introduced deactivate callbacks to clear caches when the plugin is deactivated.
Improved default values for widget settings.
Introduced full array shapes for widget settings.

Conclusion

If you’ve made it this far you’ve realized that the version 9.5 release was much larger than usual. This release contains the groundwork for many planned future enhancements. Now that we have the tools in place to more accurately validate effects on backwards compatibility, we can increase the efficiency and reliability of future enhancements.

We hope you are enjoying the Advanced Sidebar Menu plugin as much as we are!