Changeset 27255

Timestamp:

02/25/2014 06:11:32 AM (11 years ago)

Author:

DrewAPicture

Message:

Inline documentation for hooks in wp-admin/includes/class-wp-posts-list-table.php.

Props nicolealleyinteractivecom, kpdesign.
Fixes #26397.

File:

• trunk/src/wp-admin/includes/class-wp-posts-list-table.php (modified) (11 diffs)

trunk/src/wp-admin/includes/class-wp-posts-list-table.php

@@ -90 +90 @@
         $post_type = $this->screen->post_type;
         $per_page = $this->get_items_per_page( 'edit_' . $post_type . '_per_page' );
+
+        /**
+         * Filter the number of posts displayed per page on the Posts list table.
+         *
+         * @since 2.8.0
+         *
+         * @param int    $per_page  Number of posts to be displayed. Default 20.
+         * @param string $post_type The post type.
+         */
         $per_page = apply_filters( 'edit_posts_per_page', $per_page, $post_type );
 
@@ -216 +225 @@
                 wp_dropdown_categories( $dropdown_options );
             }
+
+            /**
+             * Fires before the Filter button on the Posts and Pages list tables.
+             *
+             * The Filter button allows sorting by date and/or category on the
+             * Posts list table, and sorting by date on the Pages list table.
+             *
+             * @since 2.1.0
+             */
             do_action( 'restrict_manage_posts' );
+
             submit_button( __( 'Filter' ), 'button', false, false, array( 'id' => 'post-query-submit' ) );
         }
@@ -266 +285 @@
         $taxonomies = wp_filter_object_list( $taxonomies, array( 'show_admin_column' => true ), 'and', 'name' );
 
+        /**
+         * Filter the taxonomy columns in the Posts list table.
+         *
+         * The dynamic portion of the hook name, $post_type, refers to the post
+         * type slug.
+         *
+         * @since 3.5.0
+         *
+         * @param array  $taxonomies Array of taxonomies to show columns for.
+         * @param string $post_type  The post type.
+         */
         $taxonomies = apply_filters( "manage_taxonomies_for_{$post_type}_columns", $taxonomies, $post_type );
         $taxonomies = array_filter( $taxonomies, 'taxonomy_exists' );
@@ -286 +316 @@
         $posts_columns['date'] = __( 'Date' );
 
-        if ( 'page' == $post_type )
+        if ( 'page' == $post_type ) {
+
+            /**
+             * Filter the columns displayed in the Pages list table.
+             *
+             * @since 2.5.0
+             *
+             * @param array $post_columns An array of column names.
+             */
             $posts_columns = apply_filters( 'manage_pages_columns', $posts_columns );
-        else
+        } else {
+
+            /**
+             * Filter the columns displayed in the Posts list table.
+             *
+             * @since 1.5.0
+             *
+             * @param array  $posts_columns An array of column names.
+             * @param string $post_type     The post type slug.
+             */
             $posts_columns = apply_filters( 'manage_posts_columns', $posts_columns, $post_type );
+        }
+
+        /**
+         * Filter the columns displayed in the Posts list table for a specific post type.
+         *
+         * The dynamic portion of the hook name, $post_type, refers to the post type slug.
+         *
+         * @since 3.0.0
+         *
+         * @param array $post_columns An array of column names.
+         */
         $posts_columns = apply_filters( "manage_{$post_type}_posts_columns", $posts_columns );
 
@@ -347 +405 @@
 
         /*
-         * arrange pages into two parts: top level pages and children_pages
+         * Arrange pages into two parts: top level pages and children_pages
          * children_pages is two dimensional array, eg.
          * children_pages[10][] contains all sub-pages whose parent is 10.
@@ -606 +664 @@
                 if ( $post_type_object->public ) {
                     if ( in_array( $post->post_status, array( 'pending', 'draft', 'future' ) ) ) {
-                        if ( $can_edit_post )
+                        if ( $can_edit_post ) {
+
+                            /** This filter is documented in wp-admin/includes/meta-boxes.php */
                             $actions['view'] = '<a href="' . esc_url( apply_filters( 'preview_post_link', set_url_scheme( add_query_arg( 'preview', 'true', get_permalink( $post->ID ) ) ) ) ) . '" title="' . esc_attr( sprintf( __( 'Preview &#8220;%s&#8221;' ), $title ) ) . '" rel="permalink">' . __( 'Preview' ) . '</a>';
+                        }
                     } elseif ( 'trash' != $post->post_status ) {
                         $actions['view'] = '<a href="' . get_permalink( $post->ID ) . '" title="' . esc_attr( sprintf( __( 'View &#8220;%s&#8221;' ), $title ) ) . '" rel="permalink">' . __( 'View' ) . '</a>';
@@ -613 +674 @@
                 }
 
-                $actions = apply_filters( is_post_type_hierarchical( $post->post_type ) ? 'page_row_actions' : 'post_row_actions', $actions, $post );
+                if ( is_post_type_hierarchical( $post->post_type ) ) {
+
+                    /**
+                     * Filter the array of row action links on the Pages list table.
+                     *
+                     * The filter is evaluated only for hierarchical post types.
+                     *
+                     * @since 2.8.0
+                     *
+                     * @param array   $actions An array of row action links. Defaults are
+                     *                         'Edit', 'Quick Edit', 'Restore, 'Trash',
+                     *                         'Delete Permanently', 'Preview', and 'View'.
+                     * @param WP_Post $post    The post object.
+                     */
+                    $actions = apply_filters( 'page_row_actions', $actions, $post );
+                } else {
+
+                    /**
+                     * Filter the array of row action links on the Posts list table.
+                     *
+                     * The filter is evaluated only for non-hierarchical post types.
+                     *
+                     * @since 2.8.0
+                     *
+                     * @param array   $actions An array of row action links. Defaults are
+                     *                         'Edit', 'Quick Edit', 'Restore, 'Trash',
+                     *                         'Delete Permanently', 'Preview', and 'View'.
+                     * @param WP_Post $post    The post object.
+                     */
+                    $actions = apply_filters( 'post_row_actions', $actions, $post );
+                }
+
                 echo $this->row_actions( $actions );
 
@@ -638 +730 @@
 
                 echo '<td ' . $attributes . '>';
-                if ( 'excerpt' == $mode )
+                if ( 'excerpt' == $mode ) {
+
+                    /**
+                     * Filter the published time of the post.
+                     *
+                     * If $mode equals 'excerpt', the published time and date are both displayed.
+                     * If $mode equals 'list' (default), the publish date is displayed, with the
+                     * time and date together available as an abbreviation definition.
+                     *
+                     * @since 2.5.1
+                     *
+                     * @param array   $t_time      The published time.
+                     * @param WP_Post $post        Post object.
+                     * @param string  $column_name The column name.
+                     * @param string  $mode        The list display mode ('excerpt' or 'list').
+                     */
                     echo apply_filters( 'post_date_column_time', $t_time, $post, $column_name, $mode );
-                else
+                } else {
+
+                    /** This filter is documented in wp-admin/includes/class-wp-posts-list-table.php */
                     echo '<abbr title="' . $t_time . '">' . apply_filters( 'post_date_column_time', $h_time, $post, $column_name, $mode ) . '</abbr>';
+                }
                 echo '<br />';
                 if ( 'publish' == $post->post_status ) {
@@ -720 +830 @@
             ?>
             <td <?php echo $attributes ?>><?php
-                if ( is_post_type_hierarchical( $post->post_type ) )
+                if ( is_post_type_hierarchical( $post->post_type ) ) {
+
+                    /**
+                     * Fires in each custom column on the Posts list table.
+                     *
+                     * This hook only fires if the current post type is hierarchical,
+                     * such as pages.
+                     *
+                     * @since 2.5.0
+                     *
+                     * @param string $column_name The name of the column to display.
+                     * @param int    $post_id     The current post ID.
+                     */
                     do_action( 'manage_pages_custom_column', $column_name, $post->ID );
-                else
+                } else {
+
+                    /**
+                     * Fires in each custom column in the Posts list table.
+                     *
+                     * This hook only fires if the current post type is non-hierarchical,
+                     * such as posts.
+                     *
+                     * @since 1.5.0
+                     *
+                     * @param string $column_name The name of the column to display.
+                     * @param int    $post_id     The current post ID.
+                     */
                     do_action( 'manage_posts_custom_column', $column_name, $post->ID );
+                }
+
+                /**
+                 * Fires for each custom column of a specific post type in the Posts list table.
+                 *
+                 * The dynamic portion of the hook name, $post->post_type, refers to the post type.
+                 *
+                 * @since 3.1.0
+                 *
+                 * @param string $column_name The name of the column to display.
+                 * @param int    $post_id     The current post ID.
+                 */
                 do_action( "manage_{$post->post_type}_posts_custom_column", $column_name, $post->ID );
             ?></td>
@@ -907 +1053 @@
         if ( $bulk )
             $dropdown_args['show_option_no_change'] =  __( '&mdash; No Change &mdash;' );
+
+        /**
+         * Filter the arguments used to generate the Quick Edit page-parent drop-down.
+         *
+         * @since 2.7.0
+         *
+         * @see wp_dropdown_pages()
+         *
+         * @param array $dropdown_args An array of arguments.
+         */
         $dropdown_args = apply_filters( 'quick_edit_dropdown_pages_args', $dropdown_args );
+
         wp_dropdown_pages( $dropdown_args );
     ?>
@@ -1080 +1237 @@
             if ( isset( $core_columns[$column_name] ) )
                 continue;
-            do_action( $bulk ? 'bulk_edit_custom_box' : 'quick_edit_custom_box', $column_name, $screen->post_type );
+
+            if ( $bulk ) {
+
+                /**
+                 * Fires once for each column in Bulk Edit mode.
+                 *
+                 * @since 2.7.0
+                 *
+                 * @param string  $column_name Name of the column to edit.
+                 * @param WP_Post $post_type   The post type slug.
+                 */
+                do_action( 'bulk_edit_custom_box', $column_name, $screen->post_type );
+            } else {
+
+                /**
+                 * Fires once for each column in Quick Edit mode.
+                 *
+                 * @since 2.7.0
+                 *
+                 * @param string  $column_name Name of the column to edit.
+                 * @param WP_Post $post_type   The post type slug.
+                 */
+                do_action( 'quick_edit_custom_box', $column_name, $screen->post_type );
+            }
+
         }
     ?>