wp-admin/includes/screen.php

   1 <?php
   2 /**
   3  * WordPress Administration Screen API.
   4  *
   5  * @package WordPress
   6  * @subpackage Administration
   7  */
   8
   9 /**
  10  * Get the column headers for a screen
  11  *
  12  * @since 2.7.0
  13  *
  14  * @staticvar array $column_headers
  15  *
  16  * @param string|WP_Screen $screen The screen you want the headers for
  17  * @return array Containing the headers in the format id => UI String
  18  */
  19 function get_column_headers( $screen ) {
  20         if ( is_string( $screen ) )
  21                 $screen = convert_to_screen( $screen );
  22
  23         static $column_headers = array();
  24
  25         if ( ! isset( $column_headers[ $screen->id ] ) ) {
  26
  27                 /**
  28                  * Filters the column headers for a list table on a specific screen.
  29                  *
  30                  * The dynamic portion of the hook name, `$screen->id`, refers to the
  31                  * ID of a specific screen. For example, the screen ID for the Posts
  32                  * list table is edit-post, so the filter for that screen would be
  33                  * manage_edit-post_columns.
  34                  *
  35                  * @since 3.0.0
  36                  *
  37                  * @param array $columns An array of column headers. Default empty.
  38                  */
  39                 $column_headers[ $screen->id ] = apply_filters( "manage_{$screen->id}_columns", array() );
  40         }
  41
  42         return $column_headers[ $screen->id ];
  43 }
  44
  45 /**
  46  * Get a list of hidden columns.
  47  *
  48  * @since 2.7.0
  49  *
  50  * @param string|WP_Screen $screen The screen you want the hidden columns for
  51  * @return array
  52  */
  53 function get_hidden_columns( $screen ) {
  54         if ( is_string( $screen ) ) {
  55                 $screen = convert_to_screen( $screen );
  56         }
  57
  58         $hidden = get_user_option( 'manage' . $screen->id . 'columnshidden' );
  59
  60         $use_defaults = ! is_array( $hidden );
  61
  62         if ( $use_defaults ) {
  63                 $hidden = array();
  64
  65                 /**
  66                  * Filters the default list of hidden columns.
  67                  *
  68                  * @since 4.4.0
  69                  *
  70                  * @param array     $hidden An array of columns hidden by default.
  71                  * @param WP_Screen $screen WP_Screen object of the current screen.
  72                  */
  73                 $hidden = apply_filters( 'default_hidden_columns', $hidden, $screen );
  74         }
  75
  76         /**
  77          * Filters the list of hidden columns.
  78          *
  79          * @since 4.4.0
  80          * @since 4.4.1 Added the `use_defaults` parameter.
  81          *
  82          * @param array     $hidden An array of hidden columns.
  83          * @param WP_Screen $screen WP_Screen object of the current screen.
  84          * @param bool      $use_defaults Whether to show the default columns.
  85          */
  86         return apply_filters( 'hidden_columns', $hidden, $screen, $use_defaults );
  87 }
  88
  89 /**
  90  * Prints the meta box preferences for screen meta.
  91  *
  92  * @since 2.7.0
  93  *
  94  * @global array $wp_meta_boxes
  95  *
  96  * @param WP_Screen $screen
  97  */
  98 function meta_box_prefs( $screen ) {
  99         global $wp_meta_boxes;
 100
 101         if ( is_string( $screen ) )
 102                 $screen = convert_to_screen( $screen );
 103
 104         if ( empty($wp_meta_boxes[$screen->id]) )
 105                 return;
 106
 107         $hidden = get_hidden_meta_boxes($screen);
 108
 109         foreach ( array_keys( $wp_meta_boxes[ $screen->id ] ) as $context ) {
 110                 foreach ( array( 'high', 'core', 'default', 'low' ) as $priority ) {
 111                         if ( ! isset( $wp_meta_boxes[ $screen->id ][ $context ][ $priority ] ) ) {
 112                                 continue;
 113                         }
 114                         foreach ( $wp_meta_boxes[ $screen->id ][ $context ][ $priority ] as $box ) {
 115                                 if ( false == $box || ! $box['title'] )
 116                                         continue;
 117                                 // Submit box cannot be hidden
 118                                 if ( 'submitdiv' == $box['id'] || 'linksubmitdiv' == $box['id'] )
 119                                         continue;
 120
 121                                 $widget_title = $box['title'];
 122
 123                                 if ( is_array( $box['args'] ) && isset( $box['args']['__widget_basename'] ) ) {
 124                                         $widget_title = $box['args']['__widget_basename'];
 125                                 }
 126
 127                                 printf(
 128                                         '<label for="%1$s-hide"><input class="hide-postbox-tog" name="%1$s-hide" type="checkbox" id="%1$s-hide" value="%1$s" %2$s />%3$s</label>',
 129                                         esc_attr( $box['id'] ),
 130                                         checked( in_array( $box['id'], $hidden ), false, false ),
 131                                         $widget_title
 132                                 );
 133                         }
 134                 }
 135         }
 136 }
 137
 138 /**
 139  * Get Hidden Meta Boxes
 140  *
 141  * @since 2.7.0
 142  *
 143  * @param string|WP_Screen $screen Screen identifier
 144  * @return array Hidden Meta Boxes
 145  */
 146 function get_hidden_meta_boxes( $screen ) {
 147         if ( is_string( $screen ) )
 148                 $screen = convert_to_screen( $screen );
 149
 150         $hidden = get_user_option( "metaboxhidden_{$screen->id}" );
 151
 152         $use_defaults = ! is_array( $hidden );
 153
 154         // Hide slug boxes by default
 155         if ( $use_defaults ) {
 156                 $hidden = array();
 157                 if ( 'post' == $screen->base ) {
 158                         if ( 'post' == $screen->post_type || 'page' == $screen->post_type || 'attachment' == $screen->post_type )
 159                                 $hidden = array('slugdiv', 'trackbacksdiv', 'postcustom', 'postexcerpt', 'commentstatusdiv', 'commentsdiv', 'authordiv', 'revisionsdiv');
 160                         else
 161                                 $hidden = array( 'slugdiv' );
 162                 }
 163
 164                 /**
 165                  * Filters the default list of hidden meta boxes.
 166                  *
 167                  * @since 3.1.0
 168                  *
 169                  * @param array     $hidden An array of meta boxes hidden by default.
 170                  * @param WP_Screen $screen WP_Screen object of the current screen.
 171                  */
 172                 $hidden = apply_filters( 'default_hidden_meta_boxes', $hidden, $screen );
 173         }
 174
 175         /**
 176          * Filters the list of hidden meta boxes.
 177          *
 178          * @since 3.3.0
 179          *
 180          * @param array     $hidden       An array of hidden meta boxes.
 181          * @param WP_Screen $screen       WP_Screen object of the current screen.
 182          * @param bool      $use_defaults Whether to show the default meta boxes.
 183          *                                Default true.
 184          */
 185         return apply_filters( 'hidden_meta_boxes', $hidden, $screen, $use_defaults );
 186 }
 187
 188 /**
 189  * Register and configure an admin screen option
 190  *
 191  * @since 3.1.0
 192  *
 193  * @param string $option An option name.
 194  * @param mixed $args Option-dependent arguments.
 195  */
 196 function add_screen_option( $option, $args = array() ) {
 197         $current_screen = get_current_screen();
 198
 199         if ( ! $current_screen )
 200                 return;
 201
 202         $current_screen->add_option( $option, $args );
 203 }
 204
 205 /**
 206  * Get the current screen object
 207  *
 208  * @since 3.1.0
 209  *
 210  * @global WP_Screen $current_screen
 211  *
 212  * @return WP_Screen|null Current screen object or null when screen not defined.
 213  */
 214 function get_current_screen() {
 215         global $current_screen;
 216
 217         if ( ! isset( $current_screen ) )
 218                 return null;
 219
 220         return $current_screen;
 221 }
 222
 223 /**
 224  * Set the current screen object
 225  *
 226  * @since 3.0.0
 227  *
 228  * @param mixed $hook_name Optional. The hook name (also known as the hook suffix) used to determine the screen,
 229  *                             or an existing screen object.
 230  */
 231 function set_current_screen( $hook_name = '' ) {
 232         WP_Screen::get( $hook_name )->set_current_screen();
 233 }