From 155746131f56f592a790b86f3603ff3d1a722d24 Mon Sep 17 00:00:00 2001
From: Drew Jaynes
Date: Mon, 24 Mar 2014 01:49:14 +0000
Subject: [PATCH] Inline documentation for hooks in wp-admin/includes/post.php.
Also moves the primary PHPDoc for the `edit_posts_per_page` hook to wp-admin/includes/post.php.
Props kpdesign for some cleanup.
Fixes #27431.
Built from https://develop.svn.wordpress.org/trunk@27667
git-svn-id: http://core.svn.wordpress.org/trunk@27510 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
.../includes/class-wp-posts-list-table.php | 9 +-
wp-admin/includes/post.php | 149 +++++++++++++++++-
2 files changed, 143 insertions(+), 15 deletions(-)
diff --git a/wp-admin/includes/class-wp-posts-list-table.php b/wp-admin/includes/class-wp-posts-list-table.php
index 6a465bdbd0..e5e4a81e8c 100644
--- a/wp-admin/includes/class-wp-posts-list-table.php
+++ b/wp-admin/includes/class-wp-posts-list-table.php
@@ -90,14 +90,7 @@ class WP_Posts_List_Table extends WP_List_Table {
$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.
- */
+ /** This filter is documented in wp-admin/includes/post.php */
$per_page = apply_filters( 'edit_posts_per_page', $per_page, $post_type );
if ( $this->hierarchical_display )
diff --git a/wp-admin/includes/post.php b/wp-admin/includes/post.php
index 030be77d26..b793c42e91 100644
--- a/wp-admin/includes/post.php
+++ b/wp-admin/includes/post.php
@@ -274,6 +274,7 @@ function edit_post( $post_data = null ) {
}
$attachment_data = isset( $post_data['attachments'][ $post_ID ] ) ? $post_data['attachments'][ $post_ID ] : array();
+
/** This filter is documented in wp-admin/includes/media.php */
$post_data = apply_filters( 'attachment_fields_to_save', $post_data, $attachment_data );
}
@@ -495,8 +496,34 @@ function get_default_post_to_edit( $post_type = 'post', $create_in_db = false )
$post = new WP_Post( $post );
}
+ /**
+ * Filter the default post content initially used in the "Write Post" form.
+ *
+ * @since 1.5.0
+ *
+ * @param string $post_content Default post content.
+ * @param WP_Post $post Post object.
+ */
$post->post_content = apply_filters( 'default_content', $post_content, $post );
- $post->post_title = apply_filters( 'default_title', $post_title, $post );
+
+ /**
+ * Filter the default post title initially used in the "Write Post" form.
+ *
+ * @since 1.5.0
+ *
+ * @param string $post_title Default post title.
+ * @param WP_Post $post Post object.
+ */
+ $post->post_title = apply_filters( 'default_title', $post_title, $post );
+
+ /**
+ * Filter the default post excerpt initially used in the "Write Post" form.
+ *
+ * @since 1.5.0
+ *
+ * @param string $post_excerpt Default post excerpt.
+ * @param WP_Post $post Post object.
+ */
$post->post_excerpt = apply_filters( 'default_excerpt', $post_excerpt, $post );
$post->post_name = '';
@@ -865,7 +892,30 @@ function wp_edit_posts_query( $q = false ) {
if ( empty( $posts_per_page ) || $posts_per_page < 1 )
$posts_per_page = 20;
+ /**
+ * Filter the number of items per page to show for a specific 'per_page' type.
+ *
+ * The dynamic hook name, $per_page, refers to a hook name comprised of the post type,
+ * preceded by 'edit_', and succeeded by '_per_page', e.g. 'edit_$post_type_per_page'.
+ *
+ * Some examples of filter hooks generated here include: 'edit_attachment_per_page',
+ * 'edit_post_per_page', 'edit_page_per_page', etc.
+ *
+ * @since 3.0.0
+ *
+ * @param int $posts_per_page Number of posts to display per page for the given 'per_page'
+ * type. Default 20.
+ */
$posts_per_page = apply_filters( $per_page, $posts_per_page );
+
+ /**
+ * Filter the number of posts displayed per page when specifically listing "posts".
+ *
+ * @since 2.8.0
+ *
+ * @param int $per_page Number of posts to be displayed. Default 20.
+ * @param string $post_type The post type.
+ */
$posts_per_page = apply_filters( 'edit_posts_per_page', $posts_per_page, $post_type );
$query = compact('post_type', 'post_status', 'perm', 'order', 'orderby', 'posts_per_page');
@@ -906,7 +956,6 @@ function get_available_post_mime_types($type = 'attachment') {
* can be passed in, which will override the arguments set by this function.
*
* @since 2.5.0
- * @uses apply_filters() Calls 'upload_per_page' on posts_per_page argument
*
* @param array|bool $q Array of query variables to use to build the query or false to use $_GET superglobal.
* @return array
@@ -927,6 +976,14 @@ function wp_edit_attachments_query( $q = false ) {
$media_per_page = (int) get_user_option( 'upload_per_page' );
if ( empty( $media_per_page ) || $media_per_page < 1 )
$media_per_page = 20;
+
+ /**
+ * Filter the number of items to list per page when listing media items.
+ *
+ * @since 2.9.0
+ *
+ * @param int $media_per_page Number of media to list. Default 20.
+ */
$q['posts_per_page'] = apply_filters( 'upload_per_page', $media_per_page );
$post_mime_types = get_post_mime_types();
@@ -966,6 +1023,16 @@ function postbox_classes( $id, $page ) {
$classes = array( '' );
}
+ /**
+ * Filter the postbox classes for a specific screen and screen ID combo.
+ *
+ * The dynamic portions of the hook name, $page, and $id, refer to
+ * the screen, and screen ID, respectively.
+ *
+ * @since 3.2.0
+ *
+ * @param array $classes An array of postbox classes.
+ */
$classes = apply_filters( "postbox_classes_{$page}_{$id}", $classes );
return implode( ' ', $classes );
}
@@ -1017,13 +1084,16 @@ function get_sample_permalink($id, $title = null, $name = null) {
$uri = untrailingslashit($uri);
$uri = strrev( stristr( strrev( $uri ), '/' ) );
$uri = untrailingslashit($uri);
+
+ /** This filter is documented in wp-admin/edit-tag-form.php */
$uri = apply_filters( 'editable_slug', $uri );
if ( !empty($uri) )
$uri .= '/';
$permalink = str_replace('%pagename%', "{$uri}%pagename%", $permalink);
}
- $permalink = array($permalink, apply_filters('editable_slug', $post->post_name));
+ /** This filter is documented in wp-admin/edit-tag-form.php */
+ $permalink = array( $permalink, apply_filters( 'editable_slug', $post->post_name ) );
$post->post_status = $original_status;
$post->post_date = $original_date;
$post->post_name = $original_name;
@@ -1067,7 +1137,17 @@ function get_sample_permalink_html( $id, $new_title = null, $new_slug = null ) {
if ( isset( $view_post ) )
$return .= "$view_post\n";
- $return = apply_filters('get_sample_permalink_html', $return, $id, $new_title, $new_slug);
+ /**
+ * Filter the sample permalink HTML markup.
+ *
+ * @since 2.9.0
+ *
+ * @param string $return Sample permalink HTML markup.
+ * @param int|WP_Post $id Post object or ID.
+ * @param string $new_title New sample permalink title.
+ * @param string $new_slug New sample permalink slug.
+ */
+ $return = apply_filters( 'get_sample_permalink_html', $return, $id, $new_title, $new_slug );
return $return;
}
@@ -1099,7 +1179,8 @@ function get_sample_permalink_html( $id, $new_title = null, $new_slug = null ) {
$return .= "$view_post\n";
}
- $return = apply_filters('get_sample_permalink_html', $return, $id, $new_title, $new_slug);
+ /** This filter is documented in wp-admin/includes/post.php */
+ $return = apply_filters( 'get_sample_permalink_html', $return, $id, $new_title, $new_slug );
return $return;
}
@@ -1137,6 +1218,14 @@ function _wp_post_thumbnail_html( $thumbnail_id = null, $post = null ) {
$content_width = $old_content_width;
}
+ /**
+ * Filter the admin post thumbnail HTML markup to return.
+ *
+ * @since 2.9.0
+ *
+ * @param string $content Admin post thumbnail HTML markup.
+ * @param int $post_id Post ID.
+ */
return apply_filters( 'admin_post_thumbnail_html', $content, $post->ID );
}
@@ -1159,6 +1248,7 @@ function wp_check_post_lock( $post_id ) {
$time = $lock[0];
$user = isset( $lock[1] ) ? $lock[1] : get_post_meta( $post->ID, '_edit_last', true );
+ /** This filter is documented in wp-admin/includes/ajax-actions.php */
$time_window = apply_filters( 'wp_check_post_lock_window', 150 );
if ( $time && $time > time() - $time_window && $user != get_current_user_id() )
@@ -1203,6 +1293,17 @@ function _admin_notice_post_locked() {
$user = get_userdata( $user_id );
if ( $user ) {
+
+ /**
+ * Filter whether to show the post locked dialog.
+ *
+ * Returning a falsey value to the filter will short-circuit displaying the dialog.
+ *
+ * @since 3.6.0
+ *
+ * @param bool $display Whether to display the dialog. Default true.
+ * @param WP_User|bool $user WP_User object on success, false otherwise.
+ */
if ( ! apply_filters( 'show_post_locked_dialog', true, $post, $user ) )
return;
@@ -1245,7 +1346,21 @@ function _admin_notice_post_locked() {
$preview_link = '';
}
+ /** This filter is documented in wp-admin/includes/meta-boxes.php */
$preview_link = apply_filters( 'preview_post_link', $preview_link );
+
+ /**
+ * Filter whether to allow the post lock to be overridden.
+ *
+ * Returning a falsey value to the filter will disable the ability
+ * to override the post lock.
+ *
+ * @since 3.6.0
+ *
+ * @param bool $override Whether to allow overriding post locks. Default true.
+ * @param WP_Post $post Post object.
+ * @param WP_User $user User object.
+ */
$override = apply_filters( 'override_post_lock', true, $post, $user );
$tab_last = $override ? '' : ' wp-tab-last';
@@ -1259,7 +1374,16 @@ function _admin_notice_post_locked() {
printf( ' ' . __( 'If you take over, %s will be blocked from continuing to edit.' ), esc_html( $user->display_name ) );
?>
-
+
@@ -1287,7 +1411,16 @@ function _admin_notice_post_locked() {
-
+
ID ) );
+
+ /** This filter is documented in wp-admin/includes/meta-boxes.php */
return apply_filters( 'preview_post_link', $url );
}