';
// If the front page is a page, add it to the exclude list
if (get_option('show_on_front') == 'page') {
if ( !empty( $list_args['exclude'] ) ) {
@@ -922,6 +1248,17 @@ function wp_page_menu( $args = array() ) {
$menu = '
' . $menu . '
';
$menu = '
' . $menu . "
\n";
+
+ /**
+ * Filter the HTML output of a page-based menu.
+ *
+ * @since 2.7.0
+ *
+ * @see wp_page_menu()
+ *
+ * @param string $menu The HTML output.
+ * @param array $args An array of arguments.
+ */
$menu = apply_filters( 'wp_page_menu', $menu, $args );
if ( $args['echo'] )
echo $menu;
@@ -938,14 +1275,24 @@ function wp_page_menu( $args = array() ) {
*
* @uses Walker_Page to create HTML list content.
* @since 2.1.0
- * @see Walker_Page::walk() for parameters and return description.
+ *
+ * @param array $pages
+ * @param int $depth
+ * @param int $current_page
+ * @param array $r
+ * @return string
*/
-function walk_page_tree($pages, $depth, $current_page, $r) {
+function walk_page_tree( $pages, $depth, $current_page, $r ) {
if ( empty($r['walker']) )
$walker = new Walker_Page;
else
$walker = $r['walker'];
+ foreach ( (array) $pages as $page ) {
+ if ( $page->post_parent )
+ $r['pages_with_children'][ $page->post_parent ] = true;
+ }
+
$args = array($pages, $depth, $r, $current_page);
return call_user_func_array(array($walker, 'walk'), $args);
}
@@ -956,6 +1303,8 @@ function walk_page_tree($pages, $depth, $current_page, $r) {
* @uses Walker_PageDropdown to create HTML dropdown content.
* @since 2.1.0
* @see Walker_PageDropdown::walk() for parameters and return description.
+ *
+ * @return string
*/
function walk_page_dropdown_tree() {
$args = func_get_args();
@@ -970,7 +1319,6 @@ function walk_page_dropdown_tree() {
/**
* Create HTML list of pages.
*
- * @package WordPress
* @since 2.1.0
* @uses Walker
*/
@@ -980,7 +1328,7 @@ class Walker_Page extends Walker {
* @since 2.1.0
* @var string
*/
- var $tree_type = 'page';
+ public $tree_type = 'page';
/**
* @see Walker::$db_fields
@@ -988,17 +1336,17 @@ class Walker_Page extends Walker {
* @todo Decouple this.
* @var array
*/
- var $db_fields = array ('parent' => 'post_parent', 'id' => 'ID');
+ public $db_fields = array ('parent' => 'post_parent', 'id' => 'ID');
/**
* @see Walker::start_lvl()
* @since 2.1.0
*
* @param string $output Passed by reference. Used to append additional content.
- * @param int $depth Depth of page. Used for padding.
- * @param array $args
+ * @param int $depth Depth of page. Used for padding.
+ * @param array $args
*/
- function start_lvl( &$output, $depth = 0, $args = array() ) {
+ public function start_lvl( &$output, $depth = 0, $args = array() ) {
$indent = str_repeat("\t", $depth);
$output .= "\n$indent
\n";
}
@@ -1008,10 +1356,10 @@ class Walker_Page extends Walker {
* @since 2.1.0
*
* @param string $output Passed by reference. Used to append additional content.
- * @param int $depth Depth of page. Used for padding.
- * @param array $args
+ * @param int $depth Depth of page. Used for padding.
+ * @param array $args
*/
- function end_lvl( &$output, $depth = 0, $args = array() ) {
+ public function end_lvl( &$output, $depth = 0, $args = array() ) {
$indent = str_repeat("\t", $depth);
$output .= "$indent
\n";
}
@@ -1020,43 +1368,82 @@ class Walker_Page extends Walker {
* @see Walker::start_el()
* @since 2.1.0
*
- * @param string $output Passed by reference. Used to append additional content.
- * @param object $page Page data object.
- * @param int $depth Depth of page. Used for padding.
- * @param int $current_page Page ID.
- * @param array $args
+ * @param string $output Passed by reference. Used to append additional content.
+ * @param object $page Page data object.
+ * @param int $depth Depth of page. Used for padding.
+ * @param int $current_page Page ID.
+ * @param array $args
*/
- function start_el( &$output, $page, $depth, $args, $current_page = 0 ) {
- if ( $depth )
- $indent = str_repeat("\t", $depth);
- else
+ public function start_el( &$output, $page, $depth = 0, $args = array(), $current_page = 0 ) {
+ if ( $depth ) {
+ $indent = str_repeat( "\t", $depth );
+ } else {
$indent = '';
+ }
- extract($args, EXTR_SKIP);
- $css_class = array('page_item', 'page-item-'.$page->ID);
- if ( !empty($current_page) ) {
+ $css_class = array( 'page_item', 'page-item-' . $page->ID );
+
+ if ( isset( $args['pages_with_children'][ $page->ID ] ) ) {
+ $css_class[] = 'page_item_has_children';
+ }
+
+ if ( ! empty( $current_page ) ) {
$_current_page = get_post( $current_page );
- if ( in_array( $page->ID, $_current_page->ancestors ) )
+ if ( $_current_page && in_array( $page->ID, $_current_page->ancestors ) ) {
$css_class[] = 'current_page_ancestor';
- if ( $page->ID == $current_page )
+ }
+ if ( $page->ID == $current_page ) {
$css_class[] = 'current_page_item';
- elseif ( $_current_page && $page->ID == $_current_page->post_parent )
+ } elseif ( $_current_page && $page->ID == $_current_page->post_parent ) {
$css_class[] = 'current_page_parent';
+ }
} elseif ( $page->ID == get_option('page_for_posts') ) {
$css_class[] = 'current_page_parent';
}
- $css_class = implode( ' ', apply_filters( 'page_css_class', $css_class, $page, $depth, $args, $current_page ) );
-
- $output .= $indent . '
' . $link_before . apply_filters( 'the_title', $page->post_title, $page->ID ) . $link_after . '';
+ /**
+ * Filter the list of CSS classes to include with each page item in the list.
+ *
+ * @since 2.8.0
+ *
+ * @see wp_list_pages()
+ *
+ * @param array $css_class An array of CSS classes to be applied
+ * to each list item.
+ * @param WP_Post $page Page data object.
+ * @param int $depth Depth of page, used for padding.
+ * @param array $args An array of arguments.
+ * @param int $current_page ID of the current page.
+ */
+ $css_classes = implode( ' ', apply_filters( 'page_css_class', $css_class, $page, $depth, $args, $current_page ) );
+
+ if ( '' === $page->post_title ) {
+ /* translators: %d: ID of a post */
+ $page->post_title = sprintf( __( '#%d (no title)' ), $page->ID );
+ }
- if ( !empty($show_date) ) {
- if ( 'modified' == $show_date )
+ $args['link_before'] = empty( $args['link_before'] ) ? '' : $args['link_before'];
+ $args['link_after'] = empty( $args['link_after'] ) ? '' : $args['link_after'];
+
+ /** This filter is documented in wp-includes/post-template.php */
+ $output .= $indent . sprintf(
+ '
%s%s%s',
+ $css_classes,
+ get_permalink( $page->ID ),
+ $args['link_before'],
+ apply_filters( 'the_title', $page->post_title, $page->ID ),
+ $args['link_after']
+ );
+
+ if ( ! empty( $args['show_date'] ) ) {
+ if ( 'modified' == $args['show_date'] ) {
$time = $page->post_modified;
- else
+ } else {
$time = $page->post_date;
+ }
- $output .= " " . mysql2date($date_format, $time);
+ $date_format = empty( $args['date_format'] ) ? '' : $args['date_format'];
+ $output .= " " . mysql2date( $date_format, $time );
}
}
@@ -1066,10 +1453,10 @@ class Walker_Page extends Walker {
*
* @param string $output Passed by reference. Used to append additional content.
* @param object $page Page data object. Not used.
- * @param int $depth Depth of page. Not Used.
- * @param array $args
+ * @param int $depth Depth of page. Not Used.
+ * @param array $args
*/
- function end_el( &$output, $page, $depth = 0, $args = array() ) {
+ public function end_el( &$output, $page, $depth = 0, $args = array() ) {
$output .= "
\n";
}
@@ -1078,7 +1465,6 @@ class Walker_Page extends Walker {
/**
* Create HTML dropdown list of pages.
*
- * @package WordPress
* @since 2.1.0
* @uses Walker
*/
@@ -1088,7 +1474,7 @@ class Walker_PageDropdown extends Walker {
* @since 2.1.0
* @var string
*/
- var $tree_type = 'page';
+ public $tree_type = 'page';
/**
* @see Walker::$db_fields
@@ -1096,26 +1482,46 @@ class Walker_PageDropdown extends Walker {
* @todo Decouple this
* @var array
*/
- var $db_fields = array ('parent' => 'post_parent', 'id' => 'ID');
+ public $db_fields = array ('parent' => 'post_parent', 'id' => 'ID');
/**
* @see Walker::start_el()
* @since 2.1.0
*
* @param string $output Passed by reference. Used to append additional content.
- * @param object $page Page data object.
- * @param int $depth Depth of page in reference to parent pages. Used for padding.
- * @param array $args Uses 'selected' argument for selected page to set selected HTML attribute for option element.
- * @param int $id
+ * @param object $page Page data object.
+ * @param int $depth Depth of page in reference to parent pages. Used for padding.
+ * @param array $args Uses 'selected' argument for selected page to set selected HTML attribute for option
+ * element. Uses 'value_field' argument to fill "value" attribute. See {@see wp_dropdown_pages()}.
+ * @param int $id
*/
- function start_el(&$output, $page, $depth, $args, $id = 0) {
+ public function start_el( &$output, $page, $depth = 0, $args = array(), $id = 0 ) {
$pad = str_repeat(' ', $depth * 3);
- $output .= "\t\n";
}
@@ -1130,10 +1536,10 @@ class Walker_PageDropdown extends Walker {
*
* @since 2.0.0
*
- * @param int $id Optional. Post ID.
- * @param bool $fullsize Optional, default is false. Whether to use full size.
- * @param bool $deprecated Deprecated. Not used.
- * @param bool $permalink Optional, default is false. Whether to include permalink.
+ * @param int|WP_Post $id Optional. Post ID or post object.
+ * @param bool $fullsize Optional, default is false. Whether to use full size.
+ * @param bool $deprecated Deprecated. Not used.
+ * @param bool $permalink Optional, default is false. Whether to include permalink.
*/
function the_attachment_link( $id = 0, $fullsize = false, $deprecated = false, $permalink = false ) {
if ( !empty( $deprecated ) )
@@ -1149,16 +1555,16 @@ function the_attachment_link( $id = 0, $fullsize = false, $deprecated = false, $
* Retrieve an attachment page link using an image or icon, if possible.
*
* @since 2.5.0
- * @uses apply_filters() Calls 'wp_get_attachment_link' filter on HTML content with same parameters as function.
*
- * @param int $id Optional. Post ID.
- * @param string $size Optional, default is 'thumbnail'. Size of image, either array or string.
- * @param bool $permalink Optional, default is false. Whether to add permalink to image.
- * @param bool $icon Optional, default is false. Whether to include icon.
- * @param string|bool $text Optional, default is false. If string, then will be link text.
+ * @param int|WP_Post $id Optional. Post ID or post object.
+ * @param string $size Optional, default is 'thumbnail'. Size of image, either array or string.
+ * @param bool $permalink Optional, default is false. Whether to add permalink to image.
+ * @param bool $icon Optional, default is false. Whether to include icon.
+ * @param string|bool $text Optional, default is false. If string, then will be link text.
+ * @param array|string $attr Optional. Array or string of attributes.
* @return string HTML content.
*/
-function wp_get_attachment_link( $id = 0, $size = 'thumbnail', $permalink = false, $icon = false, $text = false ) {
+function wp_get_attachment_link( $id = 0, $size = 'thumbnail', $permalink = false, $icon = false, $text = false, $attr = '' ) {
$id = intval( $id );
$_post = get_post( $id );
@@ -1168,26 +1574,36 @@ function wp_get_attachment_link( $id = 0, $size = 'thumbnail', $permalink = fals
if ( $permalink )
$url = get_attachment_link( $_post->ID );
- $post_title = esc_attr( $_post->post_title );
-
- if ( $text )
+ if ( $text ) {
$link_text = $text;
- elseif ( $size && 'none' != $size )
- $link_text = wp_get_attachment_image( $id, $size, $icon );
- else
+ } elseif ( $size && 'none' != $size ) {
+ $link_text = wp_get_attachment_image( $id, $size, $icon, $attr );
+ } else {
$link_text = '';
+ }
if ( trim( $link_text ) == '' )
$link_text = $_post->post_title;
- return apply_filters( 'wp_get_attachment_link', "$link_text", $id, $size, $permalink, $icon, $text );
+ /**
+ * Filter a retrieved attachment page link.
+ *
+ * @since 2.7.0
+ *
+ * @param string $link_html The page link HTML output.
+ * @param int $id Post ID.
+ * @param string $size Image size. Default 'thumbnail'.
+ * @param bool $permalink Whether to add permalink to image. Default false.
+ * @param bool $icon Whether to include an icon. Default false.
+ * @param string|bool $text If string, will be link text. Default false.
+ */
+ return apply_filters( 'wp_get_attachment_link', "$link_text", $id, $size, $permalink, $icon, $text );
}
/**
- * Wrap attachment in <
> element before content.
+ * Wrap attachment in paragraph tag before content.
*
* @since 2.0.0
- * @uses apply_filters() Calls 'prepend_attachment' hook on HTML content.
*
* @param string $content
* @return string
@@ -1198,11 +1614,36 @@ function prepend_attachment($content) {
if ( empty($post->post_type) || $post->post_type != 'attachment' )
return $content;
- $p = '
';
- // show the medium sized image representation of the attachment if available, and link to the raw file
- $p .= wp_get_attachment_link(0, 'medium', false);
- $p .= '
';
+ // show the medium sized image representation of the attachment if available, and link to the raw file
+ $p .= wp_get_attachment_link(0, 'medium', false);
+ $p .= '
';
+ }
+
+ /**
+ * Filter the attachment markup to be prepended to the post content.
+ *
+ * @since 2.0.0
+ *
+ * @see prepend_attachment()
+ *
+ * @param string $p The attachment HTML output.
+ */
+ $p = apply_filters( 'prepend_attachment', $p );
return "$p\n$content";
}
@@ -1215,33 +1656,44 @@ function prepend_attachment($content) {
* Retrieve protected post password form content.
*
* @since 1.0.0
- * @uses apply_filters() Calls 'the_password_form' filter on output.
*
+ * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
* @return string HTML content for password form for password protected post.
*/
-function get_the_password_form() {
- $post = get_post();
+function get_the_password_form( $post = 0 ) {
+ $post = get_post( $post );
$label = 'pwbox-' . ( empty($post->ID) ? rand() : $post->ID );
- $output = '
+ $output = '
';
- return apply_filters('the_password_form', $output);
+
+ /**
+ * Filter the HTML output for the protected post password form.
+ *
+ * If modifying the password field, please note that the core database schema
+ * limits the password field to 20 characters regardless of the value of the
+ * size attribute in the form input.
+ *
+ * @since 2.7.0
+ *
+ * @param string $output The password form HTML output.
+ */
+ return apply_filters( 'the_password_form', $output );
}
/**
* Whether currently in a page template.
*
* This template tag allows you to determine if you are in a page template.
- * You can optionally provide a template name and then the check will be
- * specific to that template.
+ * You can optionally provide a template name or array of template names
+ * and then the check will be specific to that template.
*
* @since 2.5.0
- * @uses $wp_query
+ * @since 4.2.0 The `$template` parameter was changed to also accept an array of page templates.
*
- * @param string $template The specific template name if specific matching is required.
- * @return bool False on failure, true if success.
+ * @param string|array $template The specific template name or array of templates to match.
+ * @return bool True on success, false on failure.
*/
function is_page_template( $template = '' ) {
if ( ! is_page() )
@@ -1255,10 +1707,15 @@ function is_page_template( $template = '' ) {
if ( $template == $page_template )
return true;
- if ( 'default' == $template && ! $page_template )
- return true;
+ if ( is_array( $template ) ) {
+ if ( ( in_array( 'default', $template, true ) && ! $page_template )
+ || in_array( $page_template, $template, true )
+ ) {
+ return true;
+ }
+ }
- return false;
+ return ( 'default' === $template && ! $page_template );
}
/**
@@ -1266,13 +1723,13 @@ function is_page_template( $template = '' ) {
*
* @since 3.4.0
*
- * @param int $post_id The page ID to check. Defaults to the current post, when used in the loop.
- * @return string|bool Page template filename. Returns an empty string when the default page template
+ * @param int $post_id Optional. The page ID to check. Defaults to the current post, when used in the loop.
+ * @return string|false Page template filename. Returns an empty string when the default page template
* is in use. Returns false if the post is not a page.
*/
function get_page_template_slug( $post_id = null ) {
$post = get_post( $post_id );
- if ( 'page' != $post->post_type )
+ if ( ! $post || 'page' != $post->post_type )
return false;
$template = get_post_meta( $post->ID, '_wp_page_template', true );
if ( ! $template || 'default' == $template )
@@ -1283,15 +1740,11 @@ function get_page_template_slug( $post_id = null ) {
/**
* Retrieve formatted date timestamp of a revision (linked to that revisions's page).
*
- * @package WordPress
- * @subpackage Post_Revisions
* @since 2.6.0
*
- * @uses date_i18n()
- *
* @param int|object $revision Revision ID or revision object.
- * @param bool $link Optional, default is true. Link to revisions's page?
- * @return string i18n formatted datetimestamp or localized 'Current Revision'.
+ * @param bool $link Optional, default is true. Link to revisions's page?
+ * @return string|false i18n formatted datetimestamp or localized 'Current Revision'.
*/
function wp_post_revision_title( $revision, $link = true ) {
if ( !$revision = get_post( $revision ) )
@@ -1301,11 +1754,11 @@ function wp_post_revision_title( $revision, $link = true ) {
return false;
/* translators: revision date format, see http://php.net/date */
- $datef = _x( 'j F, Y @ G:i', 'revision date format');
+ $datef = _x( 'F j, Y @ H:i:s', 'revision date format' );
/* translators: 1: date */
- $autosavef = __( '%1$s [Autosave]' );
+ $autosavef = _x( '%1$s [Autosave]', 'post revision title extra' );
/* translators: 1: date */
- $currentf = __( '%1$s [Current Revision]' );
+ $currentf = _x( '%1$s [Current Revision]', 'post revision title extra' );
$date = date_i18n( $datef, strtotime( $revision->post_modified ) );
if ( $link && current_user_can( 'edit_post', $revision->ID ) && $link = get_edit_post_link( $revision->ID ) )
@@ -1319,145 +1772,91 @@ function wp_post_revision_title( $revision, $link = true ) {
return $date;
}
+/**
+ * Retrieve formatted date timestamp of a revision (linked to that revisions's page).
+ *
+ * @since 3.6.0
+ *
+ * @param int|object $revision Revision ID or revision object.
+ * @param bool $link Optional, default is true. Link to revisions's page?
+ * @return string|false gravatar, user, i18n formatted datetimestamp or localized 'Current Revision'.
+ */
+function wp_post_revision_title_expanded( $revision, $link = true ) {
+ if ( !$revision = get_post( $revision ) )
+ return $revision;
+
+ if ( !in_array( $revision->post_type, array( 'post', 'page', 'revision' ) ) )
+ return false;
+
+ $author = get_the_author_meta( 'display_name', $revision->post_author );
+ /* translators: revision date format, see http://php.net/date */
+ $datef = _x( 'F j, Y @ H:i:s', 'revision date format' );
+
+ $gravatar = get_avatar( $revision->post_author, 24 );
+
+ $date = date_i18n( $datef, strtotime( $revision->post_modified ) );
+ if ( $link && current_user_can( 'edit_post', $revision->ID ) && $link = get_edit_post_link( $revision->ID ) )
+ $date = "$date";
+
+ $revision_date_author = sprintf(
+ /* translators: post revision title: 1: author avatar, 2: author name, 3: time ago, 4: date */
+ _x( '%1$s %2$s, %3$s ago (%4$s)', 'post revision title' ),
+ $gravatar,
+ $author,
+ human_time_diff( strtotime( $revision->post_modified ), current_time( 'timestamp' ) ),
+ $date
+ );
+
+ $autosavef = __( '%1$s [Autosave]' );
+ $currentf = __( '%1$s [Current Revision]' );
+
+ if ( !wp_is_post_revision( $revision ) )
+ $revision_date_author = sprintf( $currentf, $revision_date_author );
+ elseif ( wp_is_post_autosave( $revision ) )
+ $revision_date_author = sprintf( $autosavef, $revision_date_author );
+
+ return $revision_date_author;
+}
+
/**
* Display list of a post's revisions.
*
* Can output either a UL with edit links or a TABLE with diff interface, and
* restore action links.
*
- * Second argument controls parameters:
- * (bool) parent : include the parent (the "Current Revision") in the list.
- * (string) format : 'list' or 'form-table'. 'list' outputs UL, 'form-table'
- * outputs TABLE with UI.
- * (int) right : what revision is currently being viewed - used in
- * form-table format.
- * (int) left : what revision is currently being diffed against right -
- * used in form-table format.
- *
- * @package WordPress
- * @subpackage Post_Revisions
* @since 2.6.0
*
- * @uses wp_get_post_revisions()
- * @uses wp_post_revision_title()
- * @uses get_edit_post_link()
- * @uses get_the_author_meta()
- *
- * @todo split into two functions (list, form-table) ?
- *
- * @param int|object $post_id Post ID or post object.
- * @param string|array $args See description {@link wp_parse_args()}.
- * @return null
+ * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default is global $post.
+ * @param string $type 'all' (default), 'revision' or 'autosave'
*/
-function wp_list_post_revisions( $post_id = 0, $args = null ) {
- if ( !$post = get_post( $post_id ) )
+function wp_list_post_revisions( $post_id = 0, $type = 'all' ) {
+ if ( ! $post = get_post( $post_id ) )
return;
- $defaults = array( 'parent' => false, 'right' => false, 'left' => false, 'format' => 'list', 'type' => 'all' );
- extract( wp_parse_args( $args, $defaults ), EXTR_SKIP );
-
- switch ( $type ) {
- case 'autosave' :
- if ( !$autosave = wp_get_post_autosave( $post->ID ) )
- return;
- $revisions = array( $autosave );
- break;
- case 'revision' : // just revisions - remove autosave later
- case 'all' :
- default :
- if ( !$revisions = wp_get_post_revisions( $post->ID ) )
- return;
- break;
+ // $args array with (parent, format, right, left, type) deprecated since 3.6
+ if ( is_array( $type ) ) {
+ $type = ! empty( $type['type'] ) ? $type['type'] : $type;
+ _deprecated_argument( __FUNCTION__, '3.6' );
}
- /* translators: post revision: 1: when, 2: author name */
- $titlef = _x( '%1$s by %2$s', 'post revision' );
-
- if ( $parent )
- array_unshift( $revisions, $post );
+ if ( ! $revisions = wp_get_post_revisions( $post->ID ) )
+ return;
- $rows = $right_checked = '';
- $class = false;
- $can_edit_post = current_user_can( 'edit_post', $post->ID );
+ $rows = '';
foreach ( $revisions as $revision ) {
- if ( !current_user_can( 'read_post', $revision->ID ) )
+ if ( ! current_user_can( 'read_post', $revision->ID ) )
continue;
- if ( 'revision' === $type && wp_is_post_autosave( $revision ) )
+
+ $is_autosave = wp_is_post_autosave( $revision );
+ if ( ( 'revision' === $type && $is_autosave ) || ( 'autosave' === $type && ! $is_autosave ) )
continue;
- $date = wp_post_revision_title( $revision );
- $name = get_the_author_meta( 'display_name', $revision->post_author );
-
- if ( 'form-table' == $format ) {
- if ( $left )
- $left_checked = $left == $revision->ID ? ' checked="checked"' : '';
- else
- $left_checked = $right_checked ? ' checked="checked"' : ''; // [sic] (the next one)
- $right_checked = $right == $revision->ID ? ' checked="checked"' : '';
-
- $class = $class ? '' : " class='alternate'";
-
- if ( $post->ID != $revision->ID && $can_edit_post )
- $actions = 'ID|$revision->ID" ) . '">' . __( 'Restore' ) . '';
- else
- $actions = '';
-
- $rows .= "