| @@ -19,8 +19,42 @@ | ||
| 19 | 19 | use WPDeveloper\BetterDocs\Dependencies\DI\Container; |
| 20 | 20 | |
| 21 | 21 | class Admin extends Base { |
| 22 | 22 | /** |
| 23 | + * Per-user flag recording that this administrator has opened the Content IQ | |
| 24 | + * screen — the discovery badge (ADR-063) now flags Content Intelligence, the | |
| 25 | + * headline feature, rather than MCP. | |
| 26 | + * | |
| 27 | + * Stores the timestamp of the first visit, but only its **presence** is read: | |
| 28 | + * absent means "this user has not seen Content IQ yet", which is what puts the | |
| 29 | + * one-time discovery badge on the menu. Per user on purpose — two administrators | |
| 30 | + * each get their own first look, and neither clears the other's. A deliberately | |
| 31 | + * fresh meta key (not the old `betterdocs_mcp_seen`) so a user who already | |
| 32 | + * dismissed the MCP badge still gets this one for the new feature. | |
| 33 | + * | |
| 34 | + * The private `*_mcp_*` helper names below are kept as-is to hold the diff to | |
| 35 | + * the target slug + this key; they now paint the Content IQ item. | |
| 36 | + * | |
| 37 | + * @var string | |
| 38 | + * @since 4.9.0 | |
| 39 | + */ | |
| 40 | + const MCP_SEEN_META = 'betterdocs_content_iq_seen'; | |
| 41 | + | |
| 42 | + /** | |
| 43 | + * Whether this request painted the MCP discovery badge onto the menu. | |
| 44 | + * | |
| 45 | + * Decided once in `menus()` (on `admin_menu`) and read again in | |
| 46 | + * `mcp_badge_styles()` (on `admin_head`), rather than re-deciding, because the | |
| 47 | + * two must agree: on the request that opens the MCP screen the badge is still | |
| 48 | + * painted while the meta is already written, and re-deciding at `admin_head` | |
| 49 | + * would leave that one painted pill unstyled. | |
| 50 | + * | |
| 51 | + * @var bool | |
| 52 | + * @since 4.9.0 | |
| 53 | + */ | |
| 54 | + private $mcp_badge = false; | |
| 55 | + | |
| 56 | + /** | |
| 23 | 57 | * @var CacheBank |
| 24 | 58 | */ |
| 25 | 59 | private static $cache_bank; |
| 26 | 60 | /** |
| @@ -72,9 +106,8 @@ | ||
| 72 | 106 | * |
| 73 | 107 | * @var FAQBuilder |
| 74 | 108 | */ |
| 75 | 109 | private $faq_builder; |
| 76 | - private $glossaries; | |
| 77 | 110 | |
| 78 | 111 | public function __construct( Container $container, PostType $type, Enqueue $assets, Settings $settings, KBMigration $kbmigration ) { |
| 79 | 112 | $this->container = $container; |
| 80 | 113 | $this->assets = $assets; |
| @@ -88,9 +121,8 @@ | ||
| 88 | 121 | $type->init(); |
| 89 | 122 | $type->admin_init(); |
| 90 | 123 | |
| 91 | 124 | $this->faq_builder = $this->container->get( FAQBuilder::class ); |
| 92 | - $this->glossaries = $this->container->get( Glossaries::class ); | |
| 93 | 125 | |
| 94 | 126 | /** |
| 95 | 127 | * Register usage tracking (including the daily `put_do_weekly_action` cron |
| 96 | 128 | * handler) on every request — WP-Cron runs with is_admin() === false, so |
| @@ -107,14 +139,31 @@ | ||
| 107 | 139 | |
| 108 | 140 | $this->installer = new PluginInstaller(); |
| 109 | 141 | |
| 110 | 142 | add_action( 'admin_notices', array( $this, 'compatibility_notices' ) ); |
| 143 | + // The WPNotice CacheBank wipes all admin_notices at priority 10 on BetterDocs | |
| 144 | + // screens, so the hook above never renders inside the BetterDocs panels. | |
| 145 | + // Re-add the compatibility notice after that wipe (in_admin_header, priority | |
| 146 | + // 999) so it shows on the panels like the review / license notices. | |
| 147 | + add_action( 'in_admin_header', function () { | |
| 148 | + $screen = function_exists( 'get_current_screen' ) ? get_current_screen() : null; | |
| 149 | + if ( $screen && betterdocs()->is_betterdocs_screen( $screen->id ) ) { | |
| 150 | + add_action( 'admin_notices', array( $this, 'compatibility_notices' ) ); | |
| 151 | + } | |
| 152 | + }, 999 ); | |
| 111 | 153 | // add_action( 'admin_init', [$this, 'notices'], 9 ); |
| 112 | 154 | add_filter( 'admin_init', array( $this, 'save_admin_page' ), 99 ); |
| 113 | 155 | |
| 114 | 156 | add_action( 'admin_menu', array( $this, 'menus' ) ); |
| 157 | + // The badge's clear runs on `admin_init` — a hook that fires for every | |
| 158 | + // admin request — and identifies the screen by its page slug, rather | |
| 159 | + // than on `load-{$hook_suffix}` (ADR-065). `admin_init` fires *after* | |
| 160 | + // `admin_menu`, measured on the rig, so the badge is still painted on | |
| 161 | + // the request that opens the screen exactly as before. | |
| 162 | + add_action( 'admin_init', array( $this, 'mark_mcp_seen' ) ); | |
| 115 | 163 | add_action( 'admin_menu', array( $this, 'reset_submenu' ) ); |
| 116 | 164 | add_action( 'admin_head', array( $this, 'add_custom_classes_to_menu_items' ) ); |
| 165 | + add_action( 'admin_head', array( $this, 'mcp_badge_styles' ) ); | |
| 117 | 166 | add_filter( 'plugin_action_links_' . BETTERDOCS_PLUGIN_BASENAME, array( $this, 'insert_plugin_links' ) ); |
| 118 | 167 | |
| 119 | 168 | // $this->container->get( SetupWizard::class )->init(); |
| 120 | 169 | |
| @@ -126,8 +175,10 @@ | ||
| 126 | 175 | add_filter( 'admin_body_class', array( $this, 'body_classes' ) ); |
| 127 | 176 | add_filter( 'parent_file', array( $type, 'highlight_admin_menu' ) ); |
| 128 | 177 | add_filter( 'submenu_file', array( $type, 'highlight_admin_submenu' ), 10, 2 ); |
| 129 | 178 | add_filter( 'betterdocs_admin_menu', array( $this, 'quick_setup_menu' ), 10, 1 ); |
| 179 | + // Runs last so it also orders items Pro/add-ons append through this filter. | |
| 180 | + add_filter( 'betterdocs_admin_menu', array( $this, 'order_admin_menu' ), 999, 1 ); | |
| 130 | 181 | |
| 131 | 182 | /** |
| 132 | 183 | * Remove Comments Column from List Table. |
| 133 | 184 | */ |
| @@ -249,9 +300,11 @@ | ||
| 249 | 300 | if ( betterdocs()->is_pro_active() ) { |
| 250 | 301 | $plugins = Helper::get_plugins(); |
| 251 | 302 | $plugin_data = $plugins['betterdocs-pro/betterdocs-pro.php']; |
| 252 | 303 | |
| 253 | - if ( isset( $plugin_data['Version'] ) && version_compare( $plugin_data['Version'], '2.5.0', '>=' ) ) { | |
| 304 | + // Require the paired Pro release: the Analytics UI is version-coupled to | |
| 305 | + // Pro's advanced modules, so an older Pro renders a broken/partial panel. | |
| 306 | + if ( isset( $plugin_data['Version'] ) && version_compare( $plugin_data['Version'], '4.0.0', '>=' ) ) { | |
| 254 | 307 | return; |
| 255 | 308 | } |
| 256 | 309 | |
| 257 | 310 | betterdocs()->views->get( 'admin/notices/compatibility', array( 'version' => $plugin_data['Version'] ) ); |
| @@ -430,8 +483,26 @@ | ||
| 430 | 483 | ) |
| 431 | 484 | ); |
| 432 | 485 | } |
| 433 | 486 | |
| 487 | + // BetterDocs' own admin screens. Promotional notices are limited to these | |
| 488 | + // (WP.org guideline 11), never the whole of wp-admin. | |
| 489 | + $betterdocs_screens = array( | |
| 490 | + 'toplevel_page_betterdocs-dashboard', | |
| 491 | + 'admin_page_betterdocs-admin', | |
| 492 | + 'betterdocs_page_betterdocs-admin', | |
| 493 | + 'betterdocs_page_betterdocs-settings', | |
| 494 | + 'betterdocs_page_betterdocs-faq', | |
| 495 | + 'betterdocs_page_betterdocs-analytics', | |
| 496 | + 'betterdocs_page_betterdocs-glossaries', | |
| 497 | + 'betterdocs_page_betterdocs-ai-chatbot', | |
| 498 | + 'betterdocs_page_betterdocs-api-docs', | |
| 499 | + 'betterdocs_page_betterdocs-doc-categories', | |
| 500 | + 'betterdocs_page_betterdocs-doc-tags', | |
| 501 | + 'edit-doc_category', | |
| 502 | + 'edit-doc_tag', | |
| 503 | + ); | |
| 504 | + | |
| 434 | 505 | $summer_campaign_message = '<div class="betterdocs-summer-notice-body"><p style="margin-top: 0; margin-bottom: 0;">🏖️ <strong>Summer Savings:</strong> Build AI-powered Knowledge Bases & FAQs to cut support tickets and improve user experience – now <strong>up to $100 OFF!</strong></p></div>'; |
| 435 | 506 | $_summer_campaign_notice = array( |
| 436 | 507 | 'thumbnail' => $this->assets->icon( 'betterdocs-logo.svg', true ), |
| 437 | 508 | 'html' => $summer_campaign_message, |
| @@ -446,10 +517,11 @@ | ||
| 446 | 517 | ), |
| 447 | 518 | 'maybe_later' => array( |
| 448 | 519 | 'label' => __( 'I’ll Grab It Later', 'betterdocs' ), |
| 449 | 520 | 'attributes' => array( |
| 450 | - 'target' => '_blank', | |
| 451 | - 'data-later' => true, | |
| 521 | + 'target' => '_blank', | |
| 522 | + // A promo dismissal is permanent: no 15-day re-show. | |
| 523 | + 'data-dismiss' => true, | |
| 452 | 524 | 'class' => 'dismiss-btn', |
| 453 | 525 | ), |
| 454 | 526 | ), |
| 455 | 527 | ), |
| @@ -461,11 +533,11 @@ | ||
| 461 | 533 | array( |
| 462 | 534 | 'start' => $notices->time(), |
| 463 | 535 | 'recurrence' => false, |
| 464 | 536 | 'dismissible' => true, |
| 465 | - 'refresh' => BETTERDOCS_VERSION, | |
| 466 | 537 | 'expire' => strtotime( '11:59:59pm June 25, 2026' ), |
| 467 | 538 | 'display_if' => ! is_plugin_active( 'betterdocs-pro/betterdocs-pro.php' ), |
| 539 | + 'screens' => $betterdocs_screens, | |
| 468 | 540 | ) |
| 469 | 541 | ); |
| 470 | 542 | |
| 471 | 543 | self::$cache_bank->create_account( $notices ); |
| @@ -471,22 +543,9 @@ | ||
| 471 | 543 | self::$cache_bank->create_account( $notices ); |
| 472 | 544 | self::$cache_bank->calculate_deposits( $notices ); |
| 473 | 545 | if ( method_exists( self::$cache_bank, 'clear_notices_in_' ) ) { |
| 474 | 546 | self::$cache_bank->clear_notices_in_( |
| 475 | - array( | |
| 476 | - 'toplevel_page_betterdocs-dashboard', | |
| 477 | - 'admin_page_betterdocs-admin', | |
| 478 | - 'betterdocs_page_betterdocs-admin', | |
| 479 | - 'betterdocs_page_betterdocs-settings', | |
| 480 | - 'betterdocs_page_betterdocs-faq', | |
| 481 | - 'betterdocs_page_betterdocs-analytics', | |
| 482 | - 'betterdocs_page_betterdocs-glossaries', | |
| 483 | - 'betterdocs_page_betterdocs-ai-chatbot', | |
| 484 | - 'betterdocs_page_betterdocs-doc-categories', | |
| 485 | - 'betterdocs_page_betterdocs-doc-tags', | |
| 486 | - 'edit-doc_category', | |
| 487 | - 'edit-doc_tag', | |
| 488 | - ), | |
| 547 | + $betterdocs_screens, | |
| 489 | 548 | $notices, |
| 490 | 549 | true |
| 491 | 550 | ); |
| 492 | 551 | } |
| @@ -550,8 +609,9 @@ | ||
| 550 | 609 | 'betterdocs-settings', |
| 551 | 610 | 'betterdocs-admin', |
| 552 | 611 | 'betterdocs-dashboard', |
| 553 | 612 | 'betterdocs-analytics', |
| 613 | + 'betterdocs-content-iq', | |
| 554 | 614 | 'betterdocs-glossaries', |
| 555 | 615 | 'betterdocs-faq', |
| 556 | 616 | 'betterdocs-doc-categories', |
| 557 | 617 | 'betterdocs-doc-tags', |
| @@ -558,8 +618,15 @@ | ||
| 558 | 618 | 'edit-doc_category', |
| 559 | 619 | 'edit-doc_tag', |
| 560 | 620 | 'edit-knowledge_base', |
| 561 | 621 | 'betterdocs-ai-chatbot', |
| 622 | + 'betterdocs-api-docs', | |
| 623 | + // Without this the MCP screen never receives `betterdocs-admin`, and | |
| 624 | + // the design tokens' dark-mode overrides — which are declared on | |
| 625 | + // `.betterdocs-admin.betterdocs-dark-mode` — can never apply there: | |
| 626 | + // the switcher in the header flips the cookie and the page stays | |
| 627 | + // light. @since 4.9.0 | |
| 628 | + 'betterdocs-mcp', | |
| 562 | 629 | ) ); |
| 563 | 630 | |
| 564 | 631 | if ( in_array( $current_screen_id, $registered_screens ) ) { |
| 565 | 632 | $classes .= ' betterdocs-admin '; |
| @@ -819,15 +886,34 @@ | ||
| 819 | 886 | 'dashboard_mode' => get_option( 'dashboard_mode' ), |
| 820 | 887 | 'betterdocs_pro_plugin' => betterdocs()->is_pro_active(), |
| 821 | 888 | 'betterdocs_pro_version' => betterdocs()->pro_version(), |
| 822 | 889 | 'analytics_older' => version_compare( betterdocs()->pro_version(), '3.3.4', '<=' ), |
| 823 | - 'disabled_embed_model_option' => get_option( 'disabled_embed_model_option' ), | |
| 824 | 890 | 'betterdocs_ChatBot_plugin' => is_plugin_active( 'betterdocs-ai-chatbot/betterdocs-ai-chatbot.php' ), |
| 891 | + 'api_docs_teaser' => betterdocs()->show_api_docs_teaser(), | |
| 892 | + 'glossaries_teaser' => betterdocs()->show_glossary_teaser(), | |
| 893 | + 'glossaries_needs_pro_update' => betterdocs()->glossaries_needs_pro_update(), | |
| 894 | + 'glossaries_min_pro_version' => betterdocs()->glossaries_min_pro_version(), | |
| 895 | + 'glossaries_pro_update_url' => self_admin_url( 'plugins.php' ), | |
| 896 | + 'content_intelligence_teaser' => betterdocs()->show_content_intelligence_teaser(), | |
| 825 | 897 | 'is_woocommerce_active' => class_exists( 'WooCommerce' ), |
| 826 | 898 | 'total_doc_category_terms' => wp_count_terms( 'doc_category' ), |
| 827 | 899 | 'current_admin_language' => Helper::get_current_admin_language(), |
| 828 | 900 | 'is_multilingual' => Helper::is_multilingual_active(), |
| 829 | 901 | 'languages' => Helper::get_admin_languages(), |
| 902 | + /** | |
| 903 | + * MCP page bootstrap. `abilities_api_available` decides whether the | |
| 904 | + * page offers a connection at all: without the Abilities API there | |
| 905 | + * is no tool catalog, so an AI client would connect and find | |
| 906 | + * nothing. `enabled` is only the initial paint — the toggle owns | |
| 907 | + * the value from then on. | |
| 908 | + * | |
| 909 | + * @since 4.9.0 | |
| 910 | + */ | |
| 911 | + 'mcp' => array( | |
| 912 | + 'abilities_api_available' => function_exists( 'wp_register_ability' ), | |
| 913 | + 'enabled' => (bool) betterdocs()->settings->get( 'enable_mcp', false ), | |
| 914 | + 'rest' => 'betterdocs/v1', | |
| 915 | + ), | |
| 830 | 916 | ) |
| 831 | 917 | ); |
| 832 | 918 | |
| 833 | 919 | // If wp-date (which includes moment.js) is not registered, enqueue your custom moment.js |
| @@ -858,10 +944,11 @@ | ||
| 858 | 944 | |
| 859 | 945 | // Get settings and remove unnecessary keys |
| 860 | 946 | $betterdocs_settings = get_option( 'betterdocs_settings', false ); |
| 861 | 947 | if ( is_array( $betterdocs_settings ) && ! current_user_can( 'edit_docs_settings' ) ) { |
| 862 | - unset( $betterdocs_settings['ai_autowrite_api_key'] ); | |
| 863 | - unset( $betterdocs_settings['ai_chatbot_api_key'] ); | |
| 948 | + foreach ( Settings::sensitive_api_key_fields() as $sensitive_key ) { | |
| 949 | + unset( $betterdocs_settings[ $sensitive_key ] ); | |
| 950 | + } | |
| 864 | 951 | } |
| 865 | 952 | |
| 866 | 953 | betterdocs()->assets->localize( |
| 867 | 954 | 'betterdocs-admin-faq', |
| @@ -874,24 +961,10 @@ | ||
| 874 | 961 | 'betterdocs_settings' => $betterdocs_settings, |
| 875 | 962 | ) |
| 876 | 963 | ); |
| 877 | 964 | |
| 878 | - // Glossaries Related Localization | |
| 879 | - betterdocs()->assets->enqueue( 'betterdocs-admin-glossaries', 'admin/css/faq.css' ); | |
| 880 | - | |
| 881 | - betterdocs()->assets->enqueue( 'betterdocs-admin-glossaries', 'admin/js/glossaries.js' ); | |
| 882 | - | |
| 883 | - betterdocs()->assets->localize( | |
| 884 | - 'betterdocs-admin-glossaries', | |
| 885 | - 'betterdocsGlossary', | |
| 886 | - array( | |
| 887 | - 'dir_url' => BETTERDOCS_ABSURL, | |
| 888 | - 'rest_url' => esc_url_raw( rest_url() ), | |
| 889 | - 'free_version' => betterdocs()->version, | |
| 890 | - 'nonce' => wp_create_nonce( 'wp_rest' ), | |
| 891 | - 'betterdocs_settings' => $betterdocs_settings, | |
| 892 | - ) | |
| 893 | - ); | |
| 965 | + // Glossaries is Pro — Pro's Core\Glossaries::enqueue() owns that bundle | |
| 966 | + // and both of its localized objects (`betterdocs`, `betterdocsGlossary`). | |
| 894 | 967 | } |
| 895 | 968 | |
| 896 | 969 | /** |
| 897 | 970 | * All admin pages header |
| @@ -948,8 +1021,13 @@ | ||
| 948 | 1021 | |
| 949 | 1022 | // Always register both UI endpoints |
| 950 | 1023 | $this->register_modern_ui_fallback(); |
| 951 | 1024 | |
| 1025 | + // The one-time MCP discovery badge (ADR-063). Decided once, here, and | |
| 1026 | + // remembered for `mcp_badge_styles()`: the pill's markup and the pill's | |
| 1027 | + // stylesheet have to be printed on the same requests as each other. | |
| 1028 | + $this->mcp_badge = self::should_flag_mcp(); | |
| 1029 | + | |
| 952 | 1030 | foreach ( $this->menu_list() as $key => $value ) { |
| 953 | 1031 | if ( 'betterdocs' === $key ) { |
| 954 | 1032 | $callable = 'add_menu_page'; |
| 955 | 1033 | $value = wp_parse_args( $value, $default_args ); |
| @@ -978,10 +1056,203 @@ | ||
| 978 | 1056 | } |
| 979 | 1057 | ++$_menu_position; |
| 980 | 1058 | } |
| 981 | 1059 | } |
| 1060 | + | |
| 1061 | + $this->paint_mcp_badge(); | |
| 982 | 1062 | } |
| 983 | 1063 | |
| 1064 | + /** | |
| 1065 | + * Append the discovery badge to the registered menu titles. | |
| 1066 | + * | |
| 1067 | + * **After** registration, editing `$menu` / `$submenu` in place — the same | |
| 1068 | + * shape `add_custom_classes_to_menu_items()` uses — and never by passing a | |
| 1069 | + * decorated title to `add_menu_page()`. That distinction is not cosmetic: | |
| 1070 | + * core stores `sanitize_title( $menu_title )` as `$admin_page_hooks[ $slug ]` | |
| 1071 | + * (`wp-admin/includes/plugin.php:1397`) and builds every child page's hook | |
| 1072 | + * suffix from it (`get_plugin_page_hookname()`), so markup in the parent's | |
| 1073 | + * title renames `betterdocs_page_betterdocs-mcp` — and the MCP screen, whose | |
| 1074 | + * asset enqueue is keyed on that exact suffix, silently loads no React | |
| 1075 | + * bundle at all. Measured: the first visit came back 102,513 bytes with no | |
| 1076 | + * `dashboard.js`, against 489,272 bytes once the badge had cleared. | |
| 1077 | + * | |
| 1078 | + * Titles are only ever appended to, never rebuilt: the menu list is filtered | |
| 1079 | + * (`betterdocs_admin_menu`), so whatever a filter put in a title survives. | |
| 1080 | + * | |
| 1081 | + * @return void | |
| 1082 | + * @since 4.9.0 | |
| 1083 | + */ | |
| 1084 | + private function paint_mcp_badge() { | |
| 1085 | + if ( ! $this->mcp_badge ) { | |
| 1086 | + return; | |
| 1087 | + } | |
| 1088 | + | |
| 1089 | + global $menu, $submenu; | |
| 1090 | + | |
| 1091 | + if ( is_array( $menu ) ) { | |
| 1092 | + foreach ( $menu as &$item ) { | |
| 1093 | + if ( isset( $item[2] ) && $this->slug === $item[2] ) { | |
| 1094 | + $item[0] .= self::mcp_parent_bubble(); | |
| 1095 | + break; | |
| 1096 | + } | |
| 1097 | + } | |
| 1098 | + unset( $item ); | |
| 1099 | + } | |
| 1100 | + | |
| 1101 | + if ( isset( $submenu[ $this->slug ] ) && is_array( $submenu[ $this->slug ] ) ) { | |
| 1102 | + foreach ( $submenu[ $this->slug ] as &$sub_item ) { | |
| 1103 | + if ( isset( $sub_item[2] ) && 'betterdocs-content-iq' === $sub_item[2] ) { | |
| 1104 | + $sub_item[0] .= self::mcp_submenu_pill(); | |
| 1105 | + break; | |
| 1106 | + } | |
| 1107 | + } | |
| 1108 | + unset( $sub_item ); | |
| 1109 | + } | |
| 1110 | + } | |
| 1111 | + | |
| 1112 | + /** | |
| 1113 | + * Whether the current user should see the one-time MCP discovery badge. | |
| 1114 | + * | |
| 1115 | + * True only for a user who can actually reach the screen and has never | |
| 1116 | + * opened it. The capability is the one the MCP menu item is already | |
| 1117 | + * registered with (`manage_options`) rather than a second, re-derived rule — | |
| 1118 | + * so the badge can never advertise a page its reader cannot open. | |
| 1119 | + * | |
| 1120 | + * @return bool | |
| 1121 | + * @since 4.9.0 | |
| 1122 | + */ | |
| 1123 | + public static function should_flag_mcp() { | |
| 1124 | + if ( ! current_user_can( 'manage_options' ) ) { | |
| 1125 | + return false; | |
| 1126 | + } | |
| 1127 | + | |
| 1128 | + $user_id = get_current_user_id(); | |
| 1129 | + | |
| 1130 | + if ( ! $user_id ) { | |
| 1131 | + return false; | |
| 1132 | + } | |
| 1133 | + | |
| 1134 | + // `get_user_meta( …, true )` answers '' for a key that is not there, and | |
| 1135 | + // the value written is always `time()` — so an empty string is the only | |
| 1136 | + // shape "never opened" takes. | |
| 1137 | + return '' === get_user_meta( $user_id, self::MCP_SEEN_META, true ); | |
| 1138 | + } | |
| 1139 | + | |
| 1140 | + /** | |
| 1141 | + * WordPress' own update-count bubble, for the BetterDocs parent menu item. | |
| 1142 | + * | |
| 1143 | + * Core's markup on purpose: the red bubble, its position and its dark-mode | |
| 1144 | + * colours are already in `wp-admin`'s stylesheet, so this needs no CSS of | |
| 1145 | + * ours and cannot drift from the Plugins/Updates bubbles beside it. | |
| 1146 | + * | |
| 1147 | + * @return string | |
| 1148 | + * @since 4.9.0 | |
| 1149 | + */ | |
| 1150 | + private static function mcp_parent_bubble() { | |
| 1151 | + return ' <span class="update-plugins count-1"><span class="update-count">1</span></span>'; | |
| 1152 | + } | |
| 1153 | + | |
| 1154 | + /** | |
| 1155 | + * The green "New" pill for the MCP submenu item. | |
| 1156 | + * | |
| 1157 | + * Core has no submenu-badge markup, so this one is ours — styled by | |
| 1158 | + * `mcp_badge_styles()`. | |
| 1159 | + * | |
| 1160 | + * @return string | |
| 1161 | + * @since 4.9.0 | |
| 1162 | + */ | |
| 1163 | + private static function mcp_submenu_pill() { | |
| 1164 | + return ' <span class="bd-menu-pill">' . esc_html__( 'New', 'betterdocs' ) . '</span>'; | |
| 1165 | + } | |
| 1166 | + | |
| 1167 | + /** | |
| 1168 | + * Whether this request is the MCP screen being opened by someone who can | |
| 1169 | + * open it. | |
| 1170 | + * | |
| 1171 | + * The whole of the clearing decision, in one static so it can be pinned by | |
| 1172 | + * a test. It reads the **page slug** rather than an admin hook suffix | |
| 1173 | + * because the suffix is derived state: core builds it from | |
| 1174 | + * `sanitize_title()` of the *parent* menu title (`get_plugin_page_hookname()`), | |
| 1175 | + * that title is filtered (`betterdocs_admin_menu`), and the parent slug is | |
| 1176 | + * spelled two ways in this class already. `?page=betterdocs-mcp` is the one | |
| 1177 | + * thing that identifies this screen on every install (ADR-065). | |
| 1178 | + * | |
| 1179 | + * The capability is `manage_options`, the same one the MCP menu item is | |
| 1180 | + * registered with and the same one {@see self::should_flag_mcp()} gates on: | |
| 1181 | + * nothing may be written for a user who cannot reach the page. | |
| 1182 | + * | |
| 1183 | + * @return bool | |
| 1184 | + * @since 4.9.0 | |
| 1185 | + */ | |
| 1186 | + public static function is_mcp_screen_request() { | |
| 1187 | + // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only screen detection; see mark_mcp_seen(). | |
| 1188 | + $page = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : ''; | |
| 1189 | + | |
| 1190 | + if ( 'betterdocs-content-iq' !== $page ) { | |
| 1191 | + return false; | |
| 1192 | + } | |
| 1193 | + | |
| 1194 | + return current_user_can( 'manage_options' ); | |
| 1195 | + } | |
| 1196 | + | |
| 1197 | + /** | |
| 1198 | + * Record that this user has now seen the MCP screen. | |
| 1199 | + * | |
| 1200 | + * Bound to `admin_init` — which fires for every admin request — and gated on | |
| 1201 | + * the page slug, rather than to `load-{$hook_suffix}` for the one suffix | |
| 1202 | + * `add_submenu_page()` happened to return. `admin_menu` has already run by | |
| 1203 | + * the time `admin_init` fires (measured), so the badge is still painted on | |
| 1204 | + * *this* request and is gone from the next admin page — that is expected and | |
| 1205 | + * correct. Do not add JavaScript to strip it mid-request. | |
| 1206 | + * | |
| 1207 | + * **No nonce, on purpose.** A nonce protects a state change an attacker | |
| 1208 | + * could make a logged-in administrator perform unknowingly. The only state | |
| 1209 | + * here is "this administrator has now been shown the MCP screen once", it is | |
| 1210 | + * written for the current user alone, it holds no attacker-chosen value, and | |
| 1211 | + * the worst a forged request can achieve is hiding a discovery badge from | |
| 1212 | + * the person it was drawn for. A nonce on a plain page view would also have | |
| 1213 | + * to survive the menu link, which carries none. | |
| 1214 | + * | |
| 1215 | + * @return void | |
| 1216 | + * @since 4.9.0 | |
| 1217 | + */ | |
| 1218 | + public function mark_mcp_seen() { | |
| 1219 | + if ( ! self::is_mcp_screen_request() ) { | |
| 1220 | + return; | |
| 1221 | + } | |
| 1222 | + | |
| 1223 | + $user_id = get_current_user_id(); | |
| 1224 | + | |
| 1225 | + if ( ! $user_id ) { | |
| 1226 | + return; | |
| 1227 | + } | |
| 1228 | + | |
| 1229 | + update_user_meta( $user_id, self::MCP_SEEN_META, time() ); | |
| 1230 | + } | |
| 1231 | + | |
| 1232 | + /** | |
| 1233 | + * The handful of declarations the "New" pill needs, inline, and only while | |
| 1234 | + * it is being shown. | |
| 1235 | + * | |
| 1236 | + * The menu is read from the WordPress Dashboard, and `styles()` above | |
| 1237 | + * early-returns on non-BetterDocs screens — so `admin/css/dashboard.css` is | |
| 1238 | + * not loaded where this pill is seen. Loading the whole BetterDocs admin | |
| 1239 | + * stylesheet globally, or shipping a stylesheet file for nine declarations, | |
| 1240 | + * both cost far more than printing them here. The accent is written out | |
| 1241 | + * rather than taken from `--base-color-700`: that token lives in | |
| 1242 | + * `dashboard.css`, which is exactly the file that is not loaded here. | |
| 1243 | + * | |
| 1244 | + * @return void | |
| 1245 | + * @since 4.9.0 | |
| 1246 | + */ | |
| 1247 | + public function mcp_badge_styles() { | |
| 1248 | + if ( ! $this->mcp_badge ) { | |
| 1249 | + return; | |
| 1250 | + } | |
| 1251 | + | |
| 1252 | + echo '<style id="betterdocs-menu-pill">#adminmenu .bd-menu-pill{display:inline-block;background:#00b884;color:#fff;font-size:10px;text-transform:uppercase;line-height:1.6;padding:1px 6px;margin-left:6px;border-radius:9px;}</style>' . "\n"; | |
| 1253 | + } | |
| 1254 | + | |
| 984 | 1255 | private function register_modern_ui_fallback() { |
| 985 | 1256 | // Add the submenu with valid parent slug |
| 986 | 1257 | add_submenu_page( |
| 987 | 1258 | 'betterdocs', // Valid parent slug |
| @@ -1102,8 +1373,18 @@ | ||
| 1102 | 1373 | 'output', |
| 1103 | 1374 | ), |
| 1104 | 1375 | $parent_slug |
| 1105 | 1376 | ), |
| 1377 | + 'mcp' => $this->normalize_menu( | |
| 1378 | + __( 'MCP', 'betterdocs' ), | |
| 1379 | + 'betterdocs-mcp', | |
| 1380 | + 'manage_options', | |
| 1381 | + array( | |
| 1382 | + $this, | |
| 1383 | + 'output', | |
| 1384 | + ), | |
| 1385 | + $parent_slug | |
| 1386 | + ), | |
| 1106 | 1387 | 'analytics' => $this->normalize_menu( |
| 1107 | 1388 | __( 'Analytics', 'betterdocs' ), |
| 1108 | 1389 | 'betterdocs-analytics', |
| 1109 | 1390 | 'read_docs_analytics', |
| @@ -1112,8 +1393,18 @@ | ||
| 1112 | 1393 | 'output', |
| 1113 | 1394 | ), |
| 1114 | 1395 | $parent_slug |
| 1115 | 1396 | ), |
| 1397 | + 'content_intelligence' => $this->normalize_menu( | |
| 1398 | + __( 'Content IQ', 'betterdocs' ), | |
| 1399 | + 'betterdocs-content-iq', | |
| 1400 | + 'read_docs_analytics', | |
| 1401 | + array( | |
| 1402 | + $this, | |
| 1403 | + 'output', | |
| 1404 | + ), | |
| 1405 | + $parent_slug | |
| 1406 | + ), | |
| 1116 | 1407 | 'faq' => $this->normalize_menu( |
| 1117 | 1408 | __( 'FAQ Builder', 'betterdocs' ), |
| 1118 | 1409 | 'betterdocs-faq', |
| 1119 | 1410 | 'read_faq_builder', |
| @@ -1124,13 +1415,25 @@ | ||
| 1124 | 1415 | $parent_slug |
| 1125 | 1416 | ), |
| 1126 | 1417 | ); |
| 1127 | 1418 | |
| 1128 | - if ( betterdocs()->is_pro_active() && betterdocs()->settings->get( 'enable_glossaries' ) == true ) { | |
| 1419 | + // Content Intelligence ships in Pro, which overwrites that same key in place. | |
| 1420 | + // Unlike API Docs it has to sit directly after Analytics, and `menus()` walks | |
| 1421 | + // this array in insertion order — so the slot is declared inside the literal | |
| 1422 | + // above and only withdrawn here. Appending it after the fact, api_docs-style, | |
| 1423 | + // would park it at the bottom of the menu. | |
| 1424 | + if ( ! ( betterdocs()->show_content_intelligence_teaser() || betterdocs()->has_content_intelligence() ) ) { | |
| 1425 | + unset( $betterdocs_admin_pages['content_intelligence'] ); | |
| 1426 | + } | |
| 1427 | + | |
| 1428 | + // Glossaries is Pro. Reserve this same 'glossaries' slot for Free's locked | |
| 1429 | + // teaser so the item keeps this position; once Pro is active the real | |
| 1430 | + // screen overwrites the key in place (same pattern as API Docs below). | |
| 1431 | + if ( betterdocs()->show_glossary_teaser() || ( betterdocs()->is_pro_active() && betterdocs()->settings->get( 'enable_glossaries' ) == true ) ) { | |
| 1129 | 1432 | $betterdocs_admin_pages['glossaries'] = $this->normalize_menu( |
| 1130 | 1433 | __( 'Glossaries', 'betterdocs' ), |
| 1131 | 1434 | 'betterdocs-glossaries', |
| 1132 | - 'read_docs_analytics', | |
| 1435 | + betterdocs()->show_glossary_teaser() ? 'manage_options' : 'read_docs_analytics', | |
| 1133 | 1436 | array( |
| 1134 | 1437 | $this, |
| 1135 | 1438 | 'output', |
| 1136 | 1439 | ), |
| @@ -1137,8 +1440,24 @@ | ||
| 1137 | 1440 | $parent_slug |
| 1138 | 1441 | ); |
| 1139 | 1442 | } |
| 1140 | 1443 | |
| 1444 | + // API Docs ships in Pro, which overwrites this same key in place — declaring | |
| 1445 | + // the slot here is what keeps the item in this position. Without Pro it | |
| 1446 | + // holds Free's locked teaser instead. | |
| 1447 | + if ( betterdocs()->show_api_docs_teaser() || betterdocs()->has_api_docs() ) { | |
| 1448 | + $betterdocs_admin_pages['api_docs'] = $this->normalize_menu( | |
| 1449 | + __( 'API Docs', 'betterdocs' ), | |
| 1450 | + 'betterdocs-api-docs', | |
| 1451 | + apply_filters( 'betterdocs_api_ref_capability', 'manage_options' ), | |
| 1452 | + array( | |
| 1453 | + $this, | |
| 1454 | + 'output', | |
| 1455 | + ), | |
| 1456 | + $parent_slug | |
| 1457 | + ); | |
| 1458 | + } | |
| 1459 | + | |
| 1141 | 1460 | if ( ! betterdocs()->is_chatbot_active() ) { |
| 1142 | 1461 | $betterdocs_admin_pages['ai_chatbot'] = $this->normalize_menu( |
| 1143 | 1462 | __( 'AI Chatbot', 'betterdocs' ), |
| 1144 | 1463 | 'betterdocs-ai-chatbot', |
| @@ -1153,8 +1472,70 @@ | ||
| 1153 | 1472 | |
| 1154 | 1473 | return apply_filters( 'betterdocs_admin_menu', $betterdocs_admin_pages, array( $this, 'output' ), $parent_slug ); |
| 1155 | 1474 | } |
| 1156 | 1475 | |
| 1476 | + /** | |
| 1477 | + * Put the BetterDocs submenu in a deliberate order. | |
| 1478 | + * | |
| 1479 | + * Order used to be an accident of *when* each item was added: Free declares | |
| 1480 | + * most of them inline, and reserves in-place slots for `glossaries` / | |
| 1481 | + * `api_docs` so Pro can overwrite the key without moving it. Anything added | |
| 1482 | + * purely through this filter, though, could only land at the end — which is | |
| 1483 | + * why Multiple KB (Pro, priority 100) and AI Chatbot Logs sat after | |
| 1484 | + * everything else regardless of where they belong. | |
| 1485 | + * | |
| 1486 | + * Sorting here, at priority 999, fixes that for every source at once: Free's | |
| 1487 | + * own entries, Pro's, and any add-on's. Knowledge Base now follows Tags (it | |
| 1488 | + * is the third taxonomy-ish thing, so it belongs with Categories and Tags | |
| 1489 | + * rather than past Analytics), and API Docs follows Knowledge Base. | |
| 1490 | + * | |
| 1491 | + * Keys not listed keep their relative order and are appended, so an add-on | |
| 1492 | + * that registers something unknown to this list is never dropped. | |
| 1493 | + * | |
| 1494 | + * @param array $pages Menu pages keyed by slug id. | |
| 1495 | + * @return array | |
| 1496 | + */ | |
| 1497 | + public function order_admin_menu( $pages ) { | |
| 1498 | + if ( ! is_array( $pages ) ) { | |
| 1499 | + return $pages; | |
| 1500 | + } | |
| 1501 | + | |
| 1502 | + $order = array( | |
| 1503 | + 'betterdocs', | |
| 1504 | + 'dashboard', | |
| 1505 | + 'all_docs', | |
| 1506 | + 'add_new', | |
| 1507 | + 'categories', | |
| 1508 | + 'tags', | |
| 1509 | + 'multiple_kb', | |
| 1510 | + 'api_docs', | |
| 1511 | + 'settings', | |
| 1512 | + 'mcp', | |
| 1513 | + 'analytics', | |
| 1514 | + // Content IQ reads as a second Analytics screen, so it has to stay | |
| 1515 | + // pinned directly behind it. Without this entry it would fall into | |
| 1516 | + // the unknown-key bucket below and be appended to the bottom of the | |
| 1517 | + // menu — the exact placement the menu literal avoids by declaring | |
| 1518 | + // the slot inline rather than filtering it in api_docs-style. | |
| 1519 | + 'content_intelligence', | |
| 1520 | + 'faq', | |
| 1521 | + 'glossaries', | |
| 1522 | + 'ai_chatbot', | |
| 1523 | + 'ai_chatbot_logs', | |
| 1524 | + ); | |
| 1525 | + | |
| 1526 | + $ordered = array(); | |
| 1527 | + foreach ( $order as $key ) { | |
| 1528 | + if ( array_key_exists( $key, $pages ) ) { | |
| 1529 | + $ordered[ $key ] = $pages[ $key ]; | |
| 1530 | + unset( $pages[ $key ] ); | |
| 1531 | + } | |
| 1532 | + } | |
| 1533 | + | |
| 1534 | + // `$pages` now holds only unknown keys, still in their original order. | |
| 1535 | + return array_merge( $ordered, $pages ); | |
| 1536 | + } | |
| 1537 | + | |
| 1157 | 1538 | public function add_custom_classes_to_menu_items() { |
| 1158 | 1539 | global $menu, $submenu; |
| 1159 | 1540 | |
| 1160 | 1541 | $menu_items = array( |
| @@ -1163,12 +1544,15 @@ | ||
| 1163 | 1544 | 'betterdocs_page_add_new' => 'betterdocs-add-new', |
| 1164 | 1545 | 'betterdocs-doc-categories' => 'betterdocs-categories', |
| 1165 | 1546 | 'betterdocs-doc-tags' => 'betterdocs-tags', |
| 1166 | 1547 | 'betterdocs-settings' => 'betterdocs-settings', |
| 1548 | + 'betterdocs-mcp' => 'betterdocs-mcp', | |
| 1167 | 1549 | 'betterdocs-analytics' => 'betterdocs-analytics', |
| 1550 | + 'betterdocs-content-iq' => 'betterdocs-content-iq', | |
| 1168 | 1551 | 'betterdocs-faq' => 'betterdocs-faq', |
| 1169 | 1552 | 'betterdocs-glossaries' => 'betterdocs-glossaries', |
| 1170 | 1553 | 'betterdocs-ai-chatbot' => 'betterdocs-ai-chatbot', |
| 1554 | + 'betterdocs-api-docs' => 'betterdocs-api-docs', | |
| 1171 | 1555 | 'edit-tags.php?taxonomy=knowledge_base&post_type=docs' => 'betterdocs-multiplekb', |
| 1172 | 1556 | ); |
| 1173 | 1557 | |
| 1174 | 1558 | foreach ( $menu as &$item ) { |
