wp/wp-admin/includes/class-wp-screen.php
changeset 21 48c4eec2b7e6
parent 19 3d72ae0968f4
equal deleted inserted replaced
20:7b1b88e27a20 21:48c4eec2b7e6
    10 /**
    10 /**
    11  * Core class used to implement an admin screen API.
    11  * Core class used to implement an admin screen API.
    12  *
    12  *
    13  * @since 3.3.0
    13  * @since 3.3.0
    14  */
    14  */
       
    15 #[AllowDynamicProperties]
    15 final class WP_Screen {
    16 final class WP_Screen {
    16 	/**
    17 	/**
    17 	 * Any action associated with the screen.
    18 	 * Any action associated with the screen.
    18 	 *
    19 	 *
    19 	 * 'add' for *-add.php and *-new.php screens. Empty otherwise.
    20 	 * 'add' for *-add.php and *-new.php screens. Empty otherwise.
    86 	 * This is derived from `$parent_file` by removing the query string and any .php extension.
    87 	 * This is derived from `$parent_file` by removing the query string and any .php extension.
    87 	 * `$parent_file` values of 'edit.php?post_type=page' and 'edit.php?post_type=post'
    88 	 * `$parent_file` values of 'edit.php?post_type=page' and 'edit.php?post_type=post'
    88 	 * have a `$parent_base` of 'edit'.
    89 	 * have a `$parent_base` of 'edit'.
    89 	 *
    90 	 *
    90 	 * @since 3.3.0
    91 	 * @since 3.3.0
    91 	 * @var string
    92 	 * @var string|null
    92 	 */
    93 	 */
    93 	public $parent_base;
    94 	public $parent_base;
    94 
    95 
    95 	/**
    96 	/**
    96 	 * The parent_file for the screen per the admin menu system.
    97 	 * The parent_file for the screen per the admin menu system.
    97 	 *
    98 	 *
    98 	 * Some `$parent_file` values are 'edit.php?post_type=page', 'edit.php', and 'options-general.php'.
    99 	 * Some `$parent_file` values are 'edit.php?post_type=page', 'edit.php', and 'options-general.php'.
    99 	 *
   100 	 *
   100 	 * @since 3.3.0
   101 	 * @since 3.3.0
   101 	 * @var string
   102 	 * @var string|null
   102 	 */
   103 	 */
   103 	public $parent_file;
   104 	public $parent_file;
   104 
   105 
   105 	/**
   106 	/**
   106 	 * The post type associated with the screen, if any.
   107 	 * The post type associated with the screen, if any.
   141 
   142 
   142 	/**
   143 	/**
   143 	 * The accessible hidden headings and text associated with the screen, if any.
   144 	 * The accessible hidden headings and text associated with the screen, if any.
   144 	 *
   145 	 *
   145 	 * @since 4.4.0
   146 	 * @since 4.4.0
   146 	 * @var array
   147 	 * @var string[]
   147 	 */
   148 	 */
   148 	private $_screen_reader_content = array();
   149 	private $_screen_reader_content = array();
   149 
   150 
   150 	/**
   151 	/**
   151 	 * Stores old string-based help.
   152 	 * Stores old string-based help.
   209 	public static function get( $hook_name = '' ) {
   210 	public static function get( $hook_name = '' ) {
   210 		if ( $hook_name instanceof WP_Screen ) {
   211 		if ( $hook_name instanceof WP_Screen ) {
   211 			return $hook_name;
   212 			return $hook_name;
   212 		}
   213 		}
   213 
   214 
       
   215 		$id              = '';
   214 		$post_type       = null;
   216 		$post_type       = null;
   215 		$taxonomy        = null;
   217 		$taxonomy        = null;
   216 		$in_admin        = false;
   218 		$in_admin        = false;
   217 		$action          = '';
   219 		$action          = '';
   218 		$is_block_editor = false;
   220 		$is_block_editor = false;
   219 
   221 
   220 		if ( $hook_name ) {
   222 		if ( $hook_name ) {
   221 			$id = $hook_name;
   223 			$id = $hook_name;
   222 		} else {
   224 		} elseif ( ! empty( $GLOBALS['hook_suffix'] ) ) {
   223 			$id = $GLOBALS['hook_suffix'];
   225 			$id = $GLOBALS['hook_suffix'];
   224 		}
   226 		}
   225 
   227 
   226 		// For those pesky meta boxes.
   228 		// For those pesky meta boxes.
   227 		if ( $hook_name && post_type_exists( $hook_name ) ) {
   229 		if ( $hook_name && post_type_exists( $hook_name ) ) {
   228 			$post_type = $id;
   230 			$post_type = $id;
   229 			$id        = 'post'; // Changes later. Ends up being $base.
   231 			$id        = 'post'; // Changes later. Ends up being $base.
   230 		} else {
   232 		} else {
   231 			if ( '.php' === substr( $id, -4 ) ) {
   233 			if ( str_ends_with( $id, '.php' ) ) {
   232 				$id = substr( $id, 0, -4 );
   234 				$id = substr( $id, 0, -4 );
   233 			}
   235 			}
   234 
   236 
   235 			if ( in_array( $id, array( 'post-new', 'link-add', 'media-new', 'user-new' ), true ) ) {
   237 			if ( in_array( $id, array( 'post-new', 'link-add', 'media-new', 'user-new' ), true ) ) {
   236 				$id     = substr( $id, 0, -4 );
   238 				$id     = substr( $id, 0, -4 );
   237 				$action = 'add';
   239 				$action = 'add';
   238 			}
   240 			}
   239 		}
   241 		}
   240 
   242 
   241 		if ( ! $post_type && $hook_name ) {
   243 		if ( ! $post_type && $hook_name ) {
   242 			if ( '-network' === substr( $id, -8 ) ) {
   244 			if ( str_ends_with( $id, '-network' ) ) {
   243 				$id       = substr( $id, 0, -8 );
   245 				$id       = substr( $id, 0, -8 );
   244 				$in_admin = 'network';
   246 				$in_admin = 'network';
   245 			} elseif ( '-user' === substr( $id, -5 ) ) {
   247 			} elseif ( str_ends_with( $id, '-user' ) ) {
   246 				$id       = substr( $id, 0, -5 );
   248 				$id       = substr( $id, 0, -5 );
   247 				$in_admin = 'user';
   249 				$in_admin = 'user';
   248 			}
   250 			}
   249 
   251 
   250 			$id = sanitize_key( $id );
   252 			$id = sanitize_key( $id );
   251 			if ( 'edit-comments' !== $id && 'edit-tags' !== $id && 'edit-' === substr( $id, 0, 5 ) ) {
   253 			if ( 'edit-comments' !== $id && 'edit-tags' !== $id && str_starts_with( $id, 'edit-' ) ) {
   252 				$maybe = substr( $id, 5 );
   254 				$maybe = substr( $id, 5 );
   253 				if ( taxonomy_exists( $maybe ) ) {
   255 				if ( taxonomy_exists( $maybe ) ) {
   254 					$id       = 'edit-tags';
   256 					$id       = 'edit-tags';
   255 					$taxonomy = $maybe;
   257 					$taxonomy = $maybe;
   256 				} elseif ( post_type_exists( $maybe ) ) {
   258 				} elseif ( post_type_exists( $maybe ) ) {
   428 	 * @since 3.3.0
   430 	 * @since 3.3.0
   429 	 */
   431 	 */
   430 	private function __construct() {}
   432 	private function __construct() {}
   431 
   433 
   432 	/**
   434 	/**
   433 	 * Indicates whether the screen is in a particular admin
   435 	 * Indicates whether the screen is in a particular admin.
   434 	 *
   436 	 *
   435 	 * @since 3.5.0
   437 	 * @since 3.5.0
   436 	 *
   438 	 *
   437 	 * @param string $admin The admin to check against (network | user | site).
   439 	 * @param string $admin The admin to check against (network | user | site).
   438 	 *                      If empty any of the three admins will result in true.
   440 	 *                      If empty any of the three admins will result in true.
   473 	public static function add_old_compat_help( $screen, $help ) {
   475 	public static function add_old_compat_help( $screen, $help ) {
   474 		self::$_old_compat_help[ $screen->id ] = $help;
   476 		self::$_old_compat_help[ $screen->id ] = $help;
   475 	}
   477 	}
   476 
   478 
   477 	/**
   479 	/**
   478 	 * Set the parent information for the screen.
   480 	 * Sets the parent information for the screen.
   479 	 *
   481 	 *
   480 	 * This is called in admin-header.php after the menu parent for the screen has been determined.
   482 	 * This is called in admin-header.php after the menu parent for the screen has been determined.
   481 	 *
   483 	 *
   482 	 * @since 3.3.0
   484 	 * @since 3.3.0
   483 	 *
   485 	 *
   503 	public function add_option( $option, $args = array() ) {
   505 	public function add_option( $option, $args = array() ) {
   504 		$this->_options[ $option ] = $args;
   506 		$this->_options[ $option ] = $args;
   505 	}
   507 	}
   506 
   508 
   507 	/**
   509 	/**
   508 	 * Remove an option from the screen.
   510 	 * Removes an option from the screen.
   509 	 *
   511 	 *
   510 	 * @since 3.8.0
   512 	 * @since 3.8.0
   511 	 *
   513 	 *
   512 	 * @param string $option Option ID.
   514 	 * @param string $option Option ID.
   513 	 */
   515 	 */
   514 	public function remove_option( $option ) {
   516 	public function remove_option( $option ) {
   515 		unset( $this->_options[ $option ] );
   517 		unset( $this->_options[ $option ] );
   516 	}
   518 	}
   517 
   519 
   518 	/**
   520 	/**
   519 	 * Remove all options from the screen.
   521 	 * Removes all options from the screen.
   520 	 *
   522 	 *
   521 	 * @since 3.8.0
   523 	 * @since 3.8.0
   522 	 */
   524 	 */
   523 	public function remove_options() {
   525 	public function remove_options() {
   524 		$this->_options = array();
   526 		$this->_options = array();
   525 	}
   527 	}
   526 
   528 
   527 	/**
   529 	/**
   528 	 * Get the options registered for the screen.
   530 	 * Gets the options registered for the screen.
   529 	 *
   531 	 *
   530 	 * @since 3.8.0
   532 	 * @since 3.8.0
   531 	 *
   533 	 *
   532 	 * @return array Options with arguments.
   534 	 * @return array Options with arguments.
   533 	 */
   535 	 */
   604 		}
   606 		}
   605 		return $this->_help_tabs[ $id ];
   607 		return $this->_help_tabs[ $id ];
   606 	}
   608 	}
   607 
   609 
   608 	/**
   610 	/**
   609 	 * Add a help tab to the contextual help for the screen.
   611 	 * Adds a help tab to the contextual help for the screen.
   610 	 *
   612 	 *
   611 	 * Call this on the `load-$pagenow` hook for the relevant screen,
   613 	 * Call this on the `load-$pagenow` hook for the relevant screen,
   612 	 * or fetch the `$current_screen` object, or use get_current_screen()
   614 	 * or fetch the `$current_screen` object, or use get_current_screen()
   613 	 * and then call the method from the object.
   615 	 * and then call the method from the object.
   614 	 *
   616 	 *
   680 	public function get_help_sidebar() {
   682 	public function get_help_sidebar() {
   681 		return $this->_help_sidebar;
   683 		return $this->_help_sidebar;
   682 	}
   684 	}
   683 
   685 
   684 	/**
   686 	/**
   685 	 * Add a sidebar to the contextual help for the screen.
   687 	 * Adds a sidebar to the contextual help for the screen.
   686 	 *
   688 	 *
   687 	 * Call this in template files after admin.php is loaded and before admin-header.php is loaded
   689 	 * Call this in template files after admin.php is loaded and before admin-header.php is loaded
   688 	 * to add a sidebar to the contextual help.
   690 	 * to add a sidebar to the contextual help.
   689 	 *
   691 	 *
   690 	 * @since 3.3.0
   692 	 * @since 3.3.0
   711 	public function get_columns() {
   713 	public function get_columns() {
   712 		return $this->columns;
   714 		return $this->columns;
   713 	}
   715 	}
   714 
   716 
   715 	/**
   717 	/**
   716 	 * Get the accessible hidden headings and text used in the screen.
   718 	 * Gets the accessible hidden headings and text used in the screen.
   717 	 *
   719 	 *
   718 	 * @since 4.4.0
   720 	 * @since 4.4.0
   719 	 *
   721 	 *
   720 	 * @see set_screen_reader_content() For more information on the array format.
   722 	 * @see set_screen_reader_content() For more information on the array format.
   721 	 *
   723 	 *
   722 	 * @return array An associative array of screen reader text strings.
   724 	 * @return string[] An associative array of screen reader text strings.
   723 	 */
   725 	 */
   724 	public function get_screen_reader_content() {
   726 	public function get_screen_reader_content() {
   725 		return $this->_screen_reader_content;
   727 		return $this->_screen_reader_content;
   726 	}
   728 	}
   727 
   729 
   728 	/**
   730 	/**
   729 	 * Get a screen reader text string.
   731 	 * Gets a screen reader text string.
   730 	 *
   732 	 *
   731 	 * @since 4.4.0
   733 	 * @since 4.4.0
   732 	 *
   734 	 *
   733 	 * @param string $key Screen reader text array named key.
   735 	 * @param string $key Screen reader text array named key.
   734 	 * @return string Screen reader text string.
   736 	 * @return string Screen reader text string.
   739 		}
   741 		}
   740 		return $this->_screen_reader_content[ $key ];
   742 		return $this->_screen_reader_content[ $key ];
   741 	}
   743 	}
   742 
   744 
   743 	/**
   745 	/**
   744 	 * Add accessible hidden headings and text for the screen.
   746 	 * Adds accessible hidden headings and text for the screen.
   745 	 *
   747 	 *
   746 	 * @since 4.4.0
   748 	 * @since 4.4.0
   747 	 *
   749 	 *
   748 	 * @param array $content {
   750 	 * @param array $content {
   749 	 *     An associative array of screen reader text strings.
   751 	 *     An associative array of screen reader text strings.
   766 
   768 
   767 		$this->_screen_reader_content = $content;
   769 		$this->_screen_reader_content = $content;
   768 	}
   770 	}
   769 
   771 
   770 	/**
   772 	/**
   771 	 * Remove all the accessible hidden headings and text for the screen.
   773 	 * Removes all the accessible hidden headings and text for the screen.
   772 	 *
   774 	 *
   773 	 * @since 4.4.0
   775 	 * @since 4.4.0
   774 	 */
   776 	 */
   775 	public function remove_screen_reader_content() {
   777 	public function remove_screen_reader_content() {
   776 		$this->_screen_reader_content = array();
   778 		$this->_screen_reader_content = array();
   777 	}
   779 	}
   778 
   780 
   779 	/**
   781 	/**
   780 	 * Render the screen's help section.
   782 	 * Renders the screen's help section.
   781 	 *
   783 	 *
   782 	 * This will trigger the deprecated filters for backward compatibility.
   784 	 * This will trigger the deprecated filters for backward compatibility.
   783 	 *
   785 	 *
   784 	 * @since 3.3.0
   786 	 * @since 3.3.0
   785 	 *
   787 	 *
   980 		</div>
   982 		</div>
   981 		<?php
   983 		<?php
   982 	}
   984 	}
   983 
   985 
   984 	/**
   986 	/**
   985 	 * @global array $wp_meta_boxes
   987 	 * @global array $wp_meta_boxes Global meta box state.
   986 	 *
   988 	 *
   987 	 * @return bool
   989 	 * @return bool
   988 	 */
   990 	 */
   989 	public function show_screen_options() {
   991 	public function show_screen_options() {
   990 		global $wp_meta_boxes;
   992 		global $wp_meta_boxes;
  1032 		$this->_show_screen_options = apply_filters( 'screen_options_show_screen', $show_screen, $this );
  1034 		$this->_show_screen_options = apply_filters( 'screen_options_show_screen', $show_screen, $this );
  1033 		return $this->_show_screen_options;
  1035 		return $this->_show_screen_options;
  1034 	}
  1036 	}
  1035 
  1037 
  1036 	/**
  1038 	/**
  1037 	 * Render the screen options tab.
  1039 	 * Renders the screen options tab.
  1038 	 *
  1040 	 *
  1039 	 * @since 3.3.0
  1041 	 * @since 3.3.0
  1040 	 *
  1042 	 *
  1041 	 * @param array $options {
  1043 	 * @param array $options {
  1042 	 *     Options for the tab.
  1044 	 *     Options for the tab.
  1095 
  1097 
  1096 		echo $form_end . $wrapper_end;
  1098 		echo $form_end . $wrapper_end;
  1097 	}
  1099 	}
  1098 
  1100 
  1099 	/**
  1101 	/**
  1100 	 * Render the meta boxes preferences.
  1102 	 * Renders the meta boxes preferences.
  1101 	 *
  1103 	 *
  1102 	 * @since 4.4.0
  1104 	 * @since 4.4.0
  1103 	 *
  1105 	 *
  1104 	 * @global array $wp_meta_boxes
  1106 	 * @global array $wp_meta_boxes Global meta box state.
  1105 	 */
  1107 	 */
  1106 	public function render_meta_boxes_preferences() {
  1108 	public function render_meta_boxes_preferences() {
  1107 		global $wp_meta_boxes;
  1109 		global $wp_meta_boxes;
  1108 
  1110 
  1109 		if ( ! isset( $wp_meta_boxes[ $this->id ] ) ) {
  1111 		if ( ! isset( $wp_meta_boxes[ $this->id ] ) ) {
  1112 		?>
  1114 		?>
  1113 		<fieldset class="metabox-prefs">
  1115 		<fieldset class="metabox-prefs">
  1114 		<legend><?php _e( 'Screen elements' ); ?></legend>
  1116 		<legend><?php _e( 'Screen elements' ); ?></legend>
  1115 		<p>
  1117 		<p>
  1116 			<?php _e( 'Some screen elements can be shown or hidden by using the checkboxes.' ); ?>
  1118 			<?php _e( 'Some screen elements can be shown or hidden by using the checkboxes.' ); ?>
  1117 			<?php _e( 'They can be expanded and collapsed by clickling on their headings, and arranged by dragging their headings or by clicking on the up and down arrows.' ); ?>
  1119 			<?php _e( 'Expand or collapse the elements by clicking on their headings, and arrange them by dragging their headings or by clicking on the up and down arrows.' ); ?>
  1118 		</p>
  1120 		</p>
       
  1121 		<div class="metabox-prefs-container">
  1119 		<?php
  1122 		<?php
  1120 
  1123 
  1121 		meta_box_prefs( $this );
  1124 		meta_box_prefs( $this );
  1122 
  1125 
  1123 		if ( 'dashboard' === $this->id && has_action( 'welcome_panel' ) && current_user_can( 'edit_theme_options' ) ) {
  1126 		if ( 'dashboard' === $this->id && has_action( 'welcome_panel' ) && current_user_can( 'edit_theme_options' ) ) {
  1133 			echo '<label for="wp_welcome_panel-hide">';
  1136 			echo '<label for="wp_welcome_panel-hide">';
  1134 			echo '<input type="checkbox" id="wp_welcome_panel-hide"' . checked( (bool) $welcome_checked, true, false ) . ' />';
  1137 			echo '<input type="checkbox" id="wp_welcome_panel-hide"' . checked( (bool) $welcome_checked, true, false ) . ' />';
  1135 			echo _x( 'Welcome', 'Welcome panel' ) . "</label>\n";
  1138 			echo _x( 'Welcome', 'Welcome panel' ) . "</label>\n";
  1136 		}
  1139 		}
  1137 		?>
  1140 		?>
       
  1141 		</div>
  1138 		</fieldset>
  1142 		</fieldset>
  1139 		<?php
  1143 		<?php
  1140 	}
  1144 	}
  1141 
  1145 
  1142 	/**
  1146 	/**
  1143 	 * Render the list table columns preferences.
  1147 	 * Renders the list table columns preferences.
  1144 	 *
  1148 	 *
  1145 	 * @since 4.4.0
  1149 	 * @since 4.4.0
  1146 	 */
  1150 	 */
  1147 	public function render_list_table_columns_preferences() {
  1151 	public function render_list_table_columns_preferences() {
  1148 
  1152 
  1186 		</fieldset>
  1190 		</fieldset>
  1187 		<?php
  1191 		<?php
  1188 	}
  1192 	}
  1189 
  1193 
  1190 	/**
  1194 	/**
  1191 	 * Render the option for number of columns on the page
  1195 	 * Renders the option for number of columns on the page.
  1192 	 *
  1196 	 *
  1193 	 * @since 3.3.0
  1197 	 * @since 3.3.0
  1194 	 */
  1198 	 */
  1195 	public function render_screen_layout() {
  1199 	public function render_screen_layout() {
  1196 		if ( ! $this->get_option( 'layout_columns' ) ) {
  1200 		if ( ! $this->get_option( 'layout_columns' ) ) {
  1218 		</fieldset>
  1222 		</fieldset>
  1219 		<?php
  1223 		<?php
  1220 	}
  1224 	}
  1221 
  1225 
  1222 	/**
  1226 	/**
  1223 	 * Render the items per page option
  1227 	 * Renders the items per page option.
  1224 	 *
  1228 	 *
  1225 	 * @since 3.3.0
  1229 	 * @since 3.3.0
  1226 	 */
  1230 	 */
  1227 	public function render_per_page_options() {
  1231 	public function render_per_page_options() {
  1228 		if ( null === $this->get_option( 'per_page' ) ) {
  1232 		if ( null === $this->get_option( 'per_page' ) ) {
  1273 		<fieldset class="screen-options">
  1277 		<fieldset class="screen-options">
  1274 		<legend><?php _e( 'Pagination' ); ?></legend>
  1278 		<legend><?php _e( 'Pagination' ); ?></legend>
  1275 			<?php if ( $per_page_label ) : ?>
  1279 			<?php if ( $per_page_label ) : ?>
  1276 				<label for="<?php echo esc_attr( $option ); ?>"><?php echo $per_page_label; ?></label>
  1280 				<label for="<?php echo esc_attr( $option ); ?>"><?php echo $per_page_label; ?></label>
  1277 				<input type="number" step="1" min="1" max="999" class="screen-per-page" name="wp_screen_options[value]"
  1281 				<input type="number" step="1" min="1" max="999" class="screen-per-page" name="wp_screen_options[value]"
  1278 					id="<?php echo esc_attr( $option ); ?>" maxlength="3"
  1282 					id="<?php echo esc_attr( $option ); ?>"
  1279 					value="<?php echo esc_attr( $per_page ); ?>" />
  1283 					value="<?php echo esc_attr( $per_page ); ?>" />
  1280 			<?php endif; ?>
  1284 			<?php endif; ?>
  1281 				<input type="hidden" name="wp_screen_options[option]" value="<?php echo esc_attr( $option ); ?>" />
  1285 				<input type="hidden" name="wp_screen_options[option]" value="<?php echo esc_attr( $option ); ?>" />
  1282 		</fieldset>
  1286 		</fieldset>
  1283 		<?php
  1287 		<?php
  1284 	}
  1288 	}
  1285 
  1289 
  1286 	/**
  1290 	/**
  1287 	 * Render the list table view mode preferences.
  1291 	 * Renders the list table view mode preferences.
  1288 	 *
  1292 	 *
  1289 	 * @since 4.4.0
  1293 	 * @since 4.4.0
  1290 	 *
  1294 	 *
  1291 	 * @global string $mode List table view mode.
  1295 	 * @global string $mode List table view mode.
  1292 	 */
  1296 	 */
  1336 		</fieldset>
  1340 		</fieldset>
  1337 		<?php
  1341 		<?php
  1338 	}
  1342 	}
  1339 
  1343 
  1340 	/**
  1344 	/**
  1341 	 * Render screen reader text.
  1345 	 * Renders screen reader text.
  1342 	 *
  1346 	 *
  1343 	 * @since 4.4.0
  1347 	 * @since 4.4.0
  1344 	 *
  1348 	 *
  1345 	 * @param string $key The screen reader text array named key.
  1349 	 * @param string $key The screen reader text array named key.
  1346 	 * @param string $tag Optional. The HTML tag to wrap the screen reader text. Default h2.
  1350 	 * @param string $tag Optional. The HTML tag to wrap the screen reader text. Default h2.