[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Administration API: WP_Internal_Pointers class
   4   *
   5   * @package WordPress
   6   * @subpackage Administration
   7   * @since 4.4.0
   8   */
   9  
  10  /**
  11   * Core class used to implement an internal admin pointers API.
  12   *
  13   * @since 3.3.0
  14   */
  15  #[AllowDynamicProperties]
  16  final class WP_Internal_Pointers {
  17      /**
  18       * Initializes the new feature pointers.
  19       *
  20       * @since 3.3.0
  21       *
  22       * All pointers can be disabled using the following:
  23       *     remove_action( 'admin_enqueue_scripts', array( 'WP_Internal_Pointers', 'enqueue_scripts' ) );
  24       *
  25       * Individual pointers (e.g. wp390_widgets) can be disabled using the following:
  26       *
  27       *    function yourprefix_remove_pointers() {
  28       *        remove_action(
  29       *            'admin_print_footer_scripts',
  30       *            array( 'WP_Internal_Pointers', 'pointer_wp390_widgets' )
  31       *        );
  32       *    }
  33       *    add_action( 'admin_enqueue_scripts', 'yourprefix_remove_pointers', 11 );
  34       *
  35       * @param string $hook_suffix The current admin page.
  36       */
  37  	public static function enqueue_scripts( $hook_suffix ) {
  38          /**
  39           * Register feature pointers
  40           *
  41           * Format:
  42           *     array(
  43           *         hook_suffix => pointer callback
  44           *     )
  45           *
  46           * Example:
  47           *     array(
  48           *         'themes.php' => 'wp390_widgets'
  49           *     )
  50           *
  51           * @var array<string, string|string[]> $registered_pointers
  52           */
  53          $registered_pointers = array(
  54              // None currently.
  55          );
  56  
  57          // Check if screen related pointer is registered.
  58          if ( empty( $registered_pointers[ $hook_suffix ] ) ) {
  59              return;
  60          }
  61  
  62          $pointers = (array) $registered_pointers[ $hook_suffix ];
  63  
  64          /**
  65           * Specify required capabilities for feature pointers
  66           *
  67           * Format:
  68           *     array(
  69           *         pointer callback => Array of required capabilities
  70           *     )
  71           *
  72           * Example:
  73           *     array(
  74           *         'wp390_widgets' => array( 'edit_theme_options' )
  75           *     )
  76           *
  77           * @var array<string, string[]> $caps_required
  78           */
  79          $caps_required = array(
  80              // None currently.
  81          );
  82  
  83          // Get dismissed pointers.
  84          $dismissed = explode( ',', (string) get_user_meta( get_current_user_id(), 'dismissed_wp_pointers', true ) );
  85  
  86          $got_pointers = false;
  87          foreach ( array_diff( $pointers, $dismissed ) as $pointer ) {
  88              if ( isset( $caps_required[ $pointer ] ) ) {
  89                  foreach ( $caps_required[ $pointer ] as $cap ) {
  90                      if ( ! current_user_can( $cap ) ) {
  91                          continue 2;
  92                      }
  93                  }
  94              }
  95  
  96              // Bind pointer print function.
  97              add_action( 'admin_print_footer_scripts', array( 'WP_Internal_Pointers', 'pointer_' . $pointer ) );
  98              $got_pointers = true;
  99          }
 100  
 101          if ( ! $got_pointers ) {
 102              return;
 103          }
 104  
 105          // Add pointers script and style to queue.
 106          wp_enqueue_style( 'wp-pointer' );
 107          wp_enqueue_script( 'wp-pointer' );
 108      }
 109  
 110      /**
 111       * Prints the pointer JavaScript data.
 112       *
 113       * @since 3.3.0
 114       *
 115       * @param string $pointer_id The pointer ID.
 116       * @param string $selector   The HTML elements, on which the pointer should be attached.
 117       * @param array  $args       Arguments to be passed to the pointer JS (see wp-pointer.js).
 118       */
 119  	private static function print_js( $pointer_id, $selector, $args ) {
 120          if ( empty( $pointer_id ) || empty( $selector ) || empty( $args ) || empty( $args['content'] ) ) {
 121              return;
 122          }
 123  
 124          ?>
 125          <script>
 126          (function($){
 127              var options = <?php echo wp_json_encode( $args, JSON_HEX_TAG | JSON_UNESCAPED_SLASHES ); ?>, setup;
 128  
 129              if ( ! options )
 130                  return;
 131  
 132              options = $.extend( options, {
 133                  close: function() {
 134                      $.post( ajaxurl, {
 135                          pointer: '<?php echo $pointer_id; ?>',
 136                          action: 'dismiss-wp-pointer'
 137                      });
 138                  }
 139              });
 140  
 141              setup = function() {
 142                  $('<?php echo $selector; ?>').first().pointer( options ).pointer('open');
 143              };
 144  
 145              if ( options.position && options.position.defer_loading )
 146                  $(window).bind( 'load.wp-pointers', setup );
 147              else
 148                  $( function() {
 149                      setup();
 150                  } );
 151  
 152          })( jQuery );
 153          </script>
 154          <?php
 155      }
 156  
 157  	public static function pointer_wp330_toolbar() {}
 158  	public static function pointer_wp330_media_uploader() {}
 159  	public static function pointer_wp330_saving_widgets() {}
 160  	public static function pointer_wp340_customize_current_theme_link() {}
 161  	public static function pointer_wp340_choose_image_from_library() {}
 162  	public static function pointer_wp350_media() {}
 163  	public static function pointer_wp360_revisions() {}
 164  	public static function pointer_wp360_locks() {}
 165  	public static function pointer_wp390_widgets() {}
 166  	public static function pointer_wp410_dfw() {}
 167  	public static function pointer_wp496_privacy() {}
 168  
 169      /**
 170       * Prevents new users from seeing existing 'new feature' pointers.
 171       *
 172       * @since 3.3.0
 173       *
 174       * @param int $user_id User ID.
 175       */
 176  	public static function dismiss_pointers_for_new_users( $user_id ) {
 177          add_user_meta( $user_id, 'dismissed_wp_pointers', '' );
 178      }
 179  }