<?php
namespace WPForms\SetupChecklist;
/**
* Setup Checklist admin menu item.
*
* Adds the "Setup Checklist" entry to the top of the WPForms submenu (above "All
* Forms"), rendering the section-progress bar inside the menu label. The parent
* menu still lands on All Forms — this only adds a sibling link, visible to
* admins. Once the checklist is dismissed the link is removed and a direct hit on
* its URL redirects to the Forms overview — dismissal is permanent per site.
*
* The bar's CSS is printed inline on `admin_head`: the menu renders on every
* admin screen, but the main WPForms admin stylesheet only loads on WPForms
* pages, so a reused stylesheet would leave the bar unstyled everywhere else.
*
* @since 2.0.0
*/
class Menu {
/**
* CSS class added to the menu link so the inline styles target only this item.
*
* @since 2.0.0
*
* @var string
*/
private const ITEM_CLASS = 'wpforms-setup-checklist-menu-item';
/**
* WPForms parent menu slug the item is attached to.
*
* @since 2.0.0
*
* @var string
*/
private const PARENT_SLUG = 'wpforms-overview';
/**
* Checklist model (source of the progress percentage).
*
* @since 2.0.0
*
* @var Checklist
*/
private $checklist;
/**
* Per-site state store (dismissal).
*
* @since 2.0.0
*
* @var State
*/
private $state;
/**
* Constructor.
*
* @since 2.0.0
*
* @param Checklist $checklist Checklist model.
* @param State $state Per-site state store.
*/
public function __construct( Checklist $checklist, State $state ) {
$this->checklist = $checklist;
$this->state = $state;
}
/**
* Register hooks.
*
* @since 2.0.0
*/
public function hooks(): void {
add_action( 'wpforms_admin_menu', [ $this, 'register' ] );
add_action( 'admin_menu', [ $this, 'reorder' ], PHP_INT_MAX );
add_action( 'admin_page_access_denied', [ $this, 'maybe_redirect_dismissed' ] );
add_action( 'admin_head', [ $this, 'print_styles' ] );
}
/**
* Send a dismissed checklist's page back to the Forms overview.
*
* @since 2.0.0
*/
public function maybe_redirect_dismissed(): void {
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
$page = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : '';
if ( $page !== Page::SLUG || ! $this->state->is_dismissed() ) {
return;
}
wp_safe_redirect( admin_url( 'admin.php?page=' . self::PARENT_SLUG ) );
exit;
}
/**
* Register the submenu item and the page route under the WPForms menu.
*
* @since 2.0.0
*
* @param object $menu WPForms admin menu instance passed by the action.
*/
public function register( $menu ): void {
$capability = wpforms_get_capability_manage_options();
if ( ! current_user_can( $capability ) ) {
return;
}
$title = $this->state->is_dismissed()
? esc_html__( 'Setup Checklist', 'wpforms-lite' )
: $this->get_menu_title();
add_submenu_page(
self::PARENT_SLUG,
esc_html__( 'WPForms Setup Checklist', 'wpforms-lite' ),
$title,
$capability,
Page::SLUG,
[ $menu, 'admin_page' ]
);
}
/**
* Position the item, or hide its link when the checklist is dismissed.
*
* @since 2.0.0
*/
public function reorder(): void {
if ( ! current_user_can( wpforms_get_capability_manage_options() ) ) {
return;
}
if ( $this->state->is_dismissed() ) {
remove_submenu_page( self::PARENT_SLUG, Page::SLUG );
return;
}
$this->move_after_overview();
}
/**
* Output the inline menu styles on every admin screen the menu shows on.
*
* @since 2.0.0
*/
public function print_styles(): void {
if ( $this->state->is_dismissed() || ! current_user_can( wpforms_get_capability_manage_options() ) ) {
return;
}
$item = '#adminmenu .wp-submenu a.' . self::ITEM_CLASS;
$styles =
$item . '{box-sizing:border-box;display:flex;flex-direction:column;justify-content:center;align-items:flex-start;gap:8px;padding:12px 12px 13px;border-bottom:1px solid #3C434A;}'
. $item . ' .wpforms-setup-checklist-menu-label{width:100%;font-weight:500;font-size:13px;line-height:16px;}'
. $item . ' .wpforms-setup-checklist-menu-progress{position:relative;width:100%;height:4px;background:#1D2327;border-radius:2px;overflow:hidden;}'
. $item . ' .wpforms-setup-checklist-menu-progress-bar{display:block;height:4px;min-width:4px;background:#00BA37;border-radius:2px;}';
// "All Forms" stays first in the markup so the top-level link targets it;
// flex `order` lifts the checklist above it visually. The submenu head (shown
// only when the menu is collapsed) is kept on top.
$submenu_sel = '#adminmenu #toplevel_page_' . self::PARENT_SLUG . ' .wp-submenu';
$styles .=
$submenu_sel . '{display:flex;flex-direction:column;}'
. $submenu_sel . ' .wp-submenu-head{order:-2;}'
. $submenu_sel . ' li:has(> a.' . self::ITEM_CLASS . '){order:-1;}';
// On mobile, core hides closed submenus with `display:none`, which the
// higher-specificity flex rule above would override — re-hide them here.
$styles .=
'@media screen and (max-width:782px){'
. '#adminmenu #toplevel_page_' . self::PARENT_SLUG . ':not(.wp-menu-open):not(.selected) .wp-submenu{display:none;}'
. '}';
// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
printf( '<style id="wpforms-setup-checklist-menu-styles">%s</style>', $styles );
}
/**
* Build the menu label markup: the title plus the progress bar.
*
* @since 2.0.0
*
* @return string
*/
private function get_menu_title(): string {
$percent = (int) $this->checklist->get_progress()['percent'];
$percent = max( 0, min( 100, $percent ) );
return sprintf(
'<span class="wpforms-setup-checklist-menu-label">%1$s</span>'
. '<span class="wpforms-setup-checklist-menu-progress">'
. '<span class="wpforms-setup-checklist-menu-progress-bar" style="width:%2$d%%;"></span>'
. '<span class="screen-reader-text">%3$s</span>'
. '</span>',
esc_html__( 'Setup Checklist', 'wpforms-lite' ),
$percent,
esc_html(
sprintf(
/* translators: %d: setup checklist completion percentage. */
__( '%d%% complete', 'wpforms-lite' ),
$percent
)
)
);
}
/**
* Place the checklist item right after "All Forms" in the WPForms submenu.
*
* @since 2.0.0
*/
private function move_after_overview(): void {
global $submenu;
if ( empty( $submenu[ self::PARENT_SLUG ] ) ) {
return;
}
$items = $submenu[ self::PARENT_SLUG ];
$ours = null;
foreach ( $items as $key => $item ) {
if ( isset( $item[2] ) && $item[2] === Page::SLUG ) {
$ours = $item;
unset( $items[ $key ] );
break;
}
}
if ( $ours === null ) {
return;
}
// The 5th element becomes a class on the menu link (see adjust_pro_menu_item).
$ours[4] = empty( $ours[4] ) ? self::ITEM_CLASS : $ours[4] . ' ' . self::ITEM_CLASS;
$items = array_values( $items );
$position = 1;
// Insert just after "All Forms" (the parent's own page) so it stays first.
foreach ( $items as $key => $item ) {
if ( isset( $item[2] ) && $item[2] === self::PARENT_SLUG ) {
$position = $key + 1;
break;
}
}
array_splice( $items, $position, 0, [ $ours ] );
// phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited
$submenu[ self::PARENT_SLUG ] = $items;
}
}