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]
 16final 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		$registered_pointers = array(
 52			// None currently.
 53		);
 54
 55		// Check if screen related pointer is registered.
 56		if ( empty( $registered_pointers[ $hook_suffix ] ) ) {
 57			return;
 58		}
 59
 60		$pointers = (array) $registered_pointers[ $hook_suffix ];
 61
 62		/*
 63		 * Specify required capabilities for feature pointers
 64		 *
 65		 * Format:
 66		 *     array(
 67		 *         pointer callback => Array of required capabilities
 68		 *     )
 69		 *
 70		 * Example:
 71		 *     array(
 72		 *         'wp390_widgets' => array( 'edit_theme_options' )
 73		 *     )
 74		 */
 75		$caps_required = array(
 76			// None currently.
 77		);
 78
 79		// Get dismissed pointers.
 80		$dismissed = explode( ',', (string) get_user_meta( get_current_user_id(), 'dismissed_wp_pointers', true ) );
 81
 82		$got_pointers = false;
 83		foreach ( array_diff( $pointers, $dismissed ) as $pointer ) {
 84			if ( isset( $caps_required[ $pointer ] ) ) {
 85				foreach ( $caps_required[ $pointer ] as $cap ) {
 86					if ( ! current_user_can( $cap ) ) {
 87						continue 2;
 88					}
 89				}
 90			}
 91
 92			// Bind pointer print function.
 93			add_action( 'admin_print_footer_scripts', array( 'WP_Internal_Pointers', 'pointer_' . $pointer ) );
 94			$got_pointers = true;
 95		}
 96
 97		if ( ! $got_pointers ) {
 98			return;
 99		}
100
101		// Add pointers script and style to queue.
102		wp_enqueue_style( 'wp-pointer' );
103		wp_enqueue_script( 'wp-pointer' );
104	}
105
106	/**
107	 * Prints the pointer JavaScript data.
108	 *
109	 * @since 3.3.0
110	 *
111	 * @param string $pointer_id The pointer ID.
112	 * @param string $selector The HTML elements, on which the pointer should be attached.
113	 * @param array  $args Arguments to be passed to the pointer JS (see wp-pointer.js).
114	 */
115	private static function print_js( $pointer_id, $selector, $args ) {
116		if ( empty( $pointer_id ) || empty( $selector ) || empty( $args ) || empty( $args['content'] ) ) {
117			return;
118		}
119
120		?>
121		<script type="text/javascript">
122		(function($){
123			var options = <?php echo wp_json_encode( $args, JSON_HEX_TAG | JSON_UNESCAPED_SLASHES ); ?>, setup;
124
125			if ( ! options )
126				return;
127
128			options = $.extend( options, {
129				close: function() {
130					$.post( ajaxurl, {
131						pointer: '<?php echo $pointer_id; ?>',
132						action: 'dismiss-wp-pointer'
133					});
134				}
135			});
136
137			setup = function() {
138				$('<?php echo $selector; ?>').first().pointer( options ).pointer('open');
139			};
140
141			if ( options.position && options.position.defer_loading )
142				$(window).bind( 'load.wp-pointers', setup );
143			else
144				$( function() {
145					setup();
146				} );
147
148		})( jQuery );
149		</script>
150		<?php
151	}
152
153	public static function pointer_wp330_toolbar() {}
154	public static function pointer_wp330_media_uploader() {}
155	public static function pointer_wp330_saving_widgets() {}
156	public static function pointer_wp340_customize_current_theme_link() {}
157	public static function pointer_wp340_choose_image_from_library() {}
158	public static function pointer_wp350_media() {}
159	public static function pointer_wp360_revisions() {}
160	public static function pointer_wp360_locks() {}
161	public static function pointer_wp390_widgets() {}
162	public static function pointer_wp410_dfw() {}
163	public static function pointer_wp496_privacy() {}
164
165	/**
166	 * Prevents new users from seeing existing 'new feature' pointers.
167	 *
168	 * @since 3.3.0
169	 *
170	 * @param int $user_id User ID.
171	 */
172	public static function dismiss_pointers_for_new_users( $user_id ) {
173		add_user_meta( $user_id, 'dismissed_wp_pointers', '' );
174	}
175}
176