Advanced Sidebar Menu – Version 9.6

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

Version 9.6 focused on phase 2 of bringing code modernization and flexibility between the PRO and basic versions of the plugin.

There is a lot of “nerd” information in this article.

Phase 2 of Code Modernization

Back in our last minor 9.5 version we completed phase 1 which laid the groundwork for phase 2. Now that the dust has settled on 9.5 and over 90% of our users are on 9.5 or newer, we’ve completed phase 2.

Phase 2 took what we introduced in the basic version in phase 1 and implemented it in the PRO version. We also used phase 2 to separate the remaining pieces of the Widget_Abstract into interfaces and traits for future phases. More on that later…

Why the multiple phases? The Advanced Sidebar plugin is running on 100s or thousands of websites, all of which use various versions. While the majority of our users keep the plugins up to date, some can fall behind on one of the versions. Phases allow us to provide an update window to our users to get both versions up to date before rolling out something which could conflict when one version is out of date.

We have a system in place to automatically disable one version or the other if there is a serious conflict which could cause a fatal error, but we prefer not to disable plugins on user sites wherever it can be avoided.

New `WidgetId` and `WithWidgetId` Interfaces

Previously, the Widget_Abstract accessed various information about the current widget being processed. This information came directly from properties available on the WP_Widget class.

If you are familiar with how PHP interfaces work, you’ll know that PHP interfaces do not support defining properties which are available. You can kind of cheat using @property in in PHP Docs which lets your IDE know the property is available but does not enforce it in code in any way. Using @property also removes helpful information during static analysis.

The logic of our Widget classes depends on these ids to generate things like menu styles and accordion configuration so we still needed to be able to access them. To solve this requirement we created a new WidgetId interface which defines a new set of methods which provide the necessary id information.

You can see from the method docs which WP_Widget properties were replaced with methods.

PHP

interface WidgetId {
	/**
	 * Get the base id from the `WP_Widget` class.
	 *
	 * Replacement for `$widget->id_base`.
	 *
	 * @return string
	 */
	public function get_id_base(): string;

/**
	 * Get the id from the `WP_Widget` class.
	 *
	 * Replacement for `$widget->id`.
	 *
	 * @return string
	 */
	public function get_id(): string;

/**
	 * Get the widget number.
	 *
	 * Replacement for `$widget->number`.
	 *
	 * @return string
	 */
	public function get_widget_number(): string;

/**
	 * Get the field id from the \WP_Widget class.
	 *
	 * @notice Definition must be compatible with \WP_Widget::get_field_id().
	 *
	 * @phpstan-param key-of<SETTINGS> $field_name
	 *
	 * @param string                   $field_name – Name of field.
	 *
	 * @return string
	 */
	public function get_field_id( $field_name );

/**
	 * Get the field name from the \WP_Widget class.
	 *
	 * @notice Definition must be compatible with \WP_Widget::get_field_name().
	 *
	 * @phpstan-param key-of<SETTINGS> $field_name
	 *
	 * @param string                   $field_name – Name of field.
	 *
	 * @return string
	 */
	public function get_field_name( $field_name );
}

In future phases our Widget classes will also implement the new WidgetId interface which is where WidgetWithId comes in. PHP lets a class implement multiple interfaces but it does not let you use multiple interfaces as method parameter types.

In the near future we’ll want our methods to know the Widget class provided has both the Widget methods and the WidgetId methods so we’ll change the type declarations to WidgetWithId and all requirements are satisfied.

PHP

New `WidgetIdAccess` and `Checkbox` Traits

To populate the contents of the Widget and Widget interfaces in a reusable way a number of PHP traits were created and made available from the basic version.

Logic is separated by trait to allow it to be or not be used by any classes requiring the same functionality. This provides an extremely flexible approach to shared logic. For our use cases, the PRO version can use a trait from the basic version to satisfy an interface to begin with. If we ever need to change the behavior of PRO, we simply stop using the trait and start using PRO only logic to satisfy the interface.

WidgetIdAccess

The WidgetIdAccess trait provides the methods required by the WidgetId interfaces. It is essentially a proxy which provides access to the original WP_Widget class properties.

PHP

Checkbox

The Checkbox trait provides some for the methods required by the Widget interface and allows reusable methods for rendering and interacting with checkbox fields within widgets.

PHP

trait Checkbox {
	/**
	 * 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 {
		$hide = false;
		if ( ( $reverse && $this->checked( $controlling_checkbox ) ) || ( ! $reverse && ! $this->checked( $controlling_checkbox ) ) ) {
			$hide = true;
		}

if ( null !== $element_key ) {
			?> data-js="<?php echo esc_attr( $this->get_field_id( $element_key ) ); ?>"
			class="advanced-sidebar-menu-<?php echo esc_attr( $element_key ); ?>"
			<?php
		}
		// Append the hide to a data attribute, so it can be picked up only if the advanced-sidebar-menu JS is present.
		// Prevents hiding of elements when widgets are loaded in unique ways like ajax.
		if ( $hide ) {
			?>
			data-advanced-sidebar-menu-hide="1"
			<?php
		}
	}

/**
	 * Outputs a <input type="checkbox"> with the id and name filled.
	 *
	 * @param string  $name              – Name of field.
	 * @param ?string $element_to_reveal – Element to reveal/hide when box is checked/unchecked.
	 *
	 * @return void
	 */
	public function checkbox( $name, $element_to_reveal = null ): void {
		?>
		<!–suppress HtmlFormInputWithoutLabel –>
		<input
			id="<?php echo esc_attr( $this->get_field_id( $name ) ); ?>"
			name="<?php echo esc_attr( $this->get_field_name( $name ) ); ?>"
			type="checkbox"
			value="checked"
			data-js="advanced-sidebar-menu/widget/<?php echo esc_attr( __Temp_Id_Proxy::factory( $this )->get_id_base() ); ?>/<?php echo esc_attr( $name ); ?>"
			<?php
			if ( null !== $element_to_reveal ) {
				echo ' onclick="window.advancedSidebarMenuAdmin.clickReveal( \'' . esc_attr( $this->get_field_id( $element_to_reveal ) ) . '\')" ';
			}
			echo $this->checked( $name ) ? 'checked' : '';
			?>
		/>
		<?php
	}

/**
	 * 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 {
		return Utils::instance()->is_checked( $name, $this->widget_settings );
	}
}

You may notice the checked method is simply calling another method which makes it a code smell. This remains in place to satisfy the Widget::checkbox rule. Without the Widget interface it may seem intuitive to refactor/remove this method, but the interface tells us that another version of the PRO plugin is expected to be there so we must leave it alone.

Now Using the `Widget` Interface

Version 9.5 introduced a Widget interface to align the rules of widget classes without locking them down with shared methods and inheritance. We’ve now implemented the interface throughout the PRO version and converted all logic to expect the interface instead of the new deprecated abstract.

This may not sound like a big deal but it is! This means the PRO version can now evolve independently from the basic version without issues with backwards compatibility.

Revamped Browser Debugging

For several years this plugin has supporting getting information about any menus rendered on the page in the browser by adding an asm_debug=true parameter to the current URL. This worked great but it came with a clunky process for locating and populating information in the browser console. It was also dedious to use the URL menu settings overrides.

Version 9.6 brought in a new intuitive way to debug the current menus.

Did you know? You can turn on script debugging for the Advanced Sidebar JavaScript and CSS files by adding script-debug=true to the current URL.

Adding `asm_debug=true` to the Current URL

Now when menus load with asm_debug in the current URL, information for the menus is automatically outputted in the browser console without any additional steps.

The information is separated into sections instead of one giant blob.

New `advancedSidebarMenuDebug` Function

In addition to the information provided in the console when asm_debug is enabled, a new advancedSidebarMenuDebug JavaScript function is now available to simplify the override parameters which may be passed to the URL.

Passing an object to the advancedSidebarMenuDebug function will automatically reload the browser with the object’s keys and values passed to the URL as override parameters.

Note: The advancedSidebarMenuDebug function is only available in the browser when asm_debug=true has been passed to the URL.

New `advanced-sidebar-menu/meta/page-meta/link-text` Filter

Using the Advanced Sidebar panel the title used for a link may be changed when it displays in one of the plugin’s menus. This works well when you want a title to be the same in every menu and/or want to change the title from the page edit screen.

But what if you want to change the label programmatically? In the past this required adding a filter to the the_title only when rendering a menu using some creative ordering of filters and actions. It probably looked something like this.

PHP

Since the Advanced Sidebar plugin already handles this complex logic when filtering the title, it makes sense to provide a filter when the plugin is performing the logic. Now changing the label looks like this.

PHP

PHP Based Translations

WordPress 6.5 included the ability to load translations from a PHP array instead of just .mo file files for greatly improved translation performance.

The Advanced Sidebar plugin now generates .php translation files to take advantage of the new translations system. You will see a nice performance improvement on any non-English sites using our plugin.

We kept the .mo files intact for backward compatibility so translations will continue to work on sites running WordPress versions older than 6.5.

New PHP Version Requirements

While WordPress Core still technically supports PHP 7.0+, it is recommended to run PHP 7.4 and most plugins already require PHP 7.4+. A couple years ago we started keeping track of which PHP version is being used on your plugins and as of July 2024, less than .1% of our users who are updating their plugins are running a PHP version older than 7.4.

Our plugins already leverage static analysis to test changes before committing them. Having PHP 7.4 available means more definitive types in our code and more modern testing tools to make sure our code is solid as changes are introduced. This also means we’ll be able to support new versions of PHP faster because of less backwards compatibility considerations.

Going forward we are no longer supporting PHP 7.2 and 7.3.

Really, this won’t impact your sites. 🙂

Miscellaneous

Tested to WordPress core version 6.6.1.
Bumped minimum supported WordPress version to 6.2.0.
Fixed ‘current-menu-ancestor’ CSS class on category menus.
Fixed missing aria-expanded attribute on accordion icons.
Dropped support for React 17 in favor of 18+.

In Closing

We understand there is a lot of technical information in this article that is probably more for the nerds out there than anyone else. The main takeaway is we are taking the future of this plugin very seriously and making huge investments now into the architecture and planning for the future.

The changes we are making now will allow future changes to not only happen faster, but to be more reliable and backwards compatible. With WordPress making a large number of changes in every version which not only change structure but break backwards compatibility with plugins and themes, it is more important than ever for a plugin to be nimble and support rapid updates. We are investing in processes to continue doing just that.