WordPress 4.3

[autoinstalls/wordpress.git] / wp-includes / post-template.php

diff --git a/wp-includes/post-template.php b/wp-includes/post-template.php
index 2a6569f29812c4422acd518e9d9ee5fb0d8f7ab1..1b4901cc925e641e8d644be1136066e383a2e50b 100644 (file)
--- a/wp-includes/post-template.php
+++ b/wp-includes/post-template.php
@@ -22,7 +22,7 @@ function the_ID() {
  *
  * @since 2.1.0
  *
  *
  * @since 2.1.0
  *

- * @return int|bool The ID of the current item in the WordPress Loop. False if $post is not set.
+ * @return int|false The ID of the current item in the WordPress Loop. False if $post is not set.

  */
 function get_the_ID() {
        $post = get_post();
  */
 function get_the_ID() {
        $post = get_post();


@@ -35,11 +35,11 @@ function get_the_ID() {
  * @since 0.71
  *
  * @param string $before Optional. Content to prepend to the title.
  * @since 0.71
  *
  * @param string $before Optional. Content to prepend to the title.

- * @param string $after Optional. Content to append to the title.
- * @param bool $echo Optional, default to true.Whether to display or return.
- * @return null|string Null on no title. String if $echo parameter is false.
+ * @param string $after  Optional. Content to append to the title.
+ * @param bool   $echo   Optional, default to true.Whether to display or return.
+ * @return string|void String if $echo parameter is false.

  */
  */

-function the_title($before = '', $after = '', $echo = true) {
+function the_title( $before = '', $after = '', $echo = true ) {

        $title = get_the_title();
 
        if ( strlen($title) == 0 )
        $title = get_the_title();
 
        if ( strlen($title) == 0 )


@@ -73,7 +73,7 @@ function the_title($before = '', $after = '', $echo = true) {
  *     @type bool    $echo   Whether to echo or return the title. Default true for echo.
  *     @type WP_Post $post   Current post object to retrieve the title for.
  * }
  *     @type bool    $echo   Whether to echo or return the title. Default true for echo.
  *     @type WP_Post $post   Current post object to retrieve the title for.
  * }

- * @return string|null Null on failure or display. String when echo is false.
+ * @return string|void String when echo is false.

  */
 function the_title_attribute( $args = '' ) {
        $defaults = array( 'before' => '', 'after' =>  '', 'echo' => true, 'post' => get_post() );
  */
 function the_title_attribute( $args = '' ) {
        $defaults = array( 'before' => '', 'after' =>  '', 'echo' => true, 'post' => get_post() );


@@ -237,6 +237,12 @@ function the_content( $more_link_text = null, $strip_teaser = false) {
  *
  * @since 0.71
  *
  *
  * @since 0.71
  *

+ * @global int   $page
+ * @global int   $more
+ * @global bool  $preview
+ * @global array $pages
+ * @global int   $multipage
+ *

  * @param string $more_link_text Optional. Content for when there is more text.
  * @param bool $strip_teaser Optional. Strip teaser content before the more text. Default is false.
  * @return string
  * @param string $more_link_text Optional. Content for when there is more text.
  * @param bool $strip_teaser Optional. Strip teaser content before the more text. Default is false.
  * @return string


@@ -521,6 +527,9 @@ function body_class( $class = '' ) {
  *
  * @since 2.8.0
  *
  *
  * @since 2.8.0
  *

+ * @global WP_Query $wp_query
+ * @global wpdb     $wpdb
+ *

  * @param string|array $class One or more classes to add to the class list.
  * @return array Array of classes.
  */
  * @param string|array $class One or more classes to add to the class list.
  * @return array Array of classes.
  */


@@ -726,7 +735,7 @@ function get_body_class( $class = '' ) {
  *
  * @since 2.7.0
  *
  *
  * @since 2.7.0
  *

- * @param int|WP_Post $post An optional post. Global $post used if not provided.
+ * @param int|WP_Post|null $post An optional post. Global $post used if not provided.

  * @return bool false if a password is not required or the correct password cookie is present, true otherwise.
  */
 function post_password_required( $post = null ) {
  * @return bool false if a password is not required or the correct password cookie is present, true otherwise.
  */
 function post_password_required( $post = null ) {


@@ -760,6 +769,11 @@ function post_password_required( $post = null ) {
  *
  * @since 1.2.0
  *
  *
  * @since 1.2.0
  *

+ * @global int $page
+ * @global int $numpages
+ * @global int $multipage
+ * @global int $more
+ *

  * @param string|array $args {
  *     Optional. Array or string of default arguments.
  *
  * @param string|array $args {
  *     Optional. Array or string of default arguments.
  *


@@ -782,6 +796,8 @@ function post_password_required( $post = null ) {
  * @return string Formatted output in HTML.
  */
 function wp_link_pages( $args = '' ) {
  * @return string Formatted output in HTML.
  */
 function wp_link_pages( $args = '' ) {

+       global $page, $numpages, $multipage, $more;
+

        $defaults = array(
                'before'           => '<p>' . __( 'Pages:' ),
                'after'            => '</p>',
        $defaults = array(
                'before'           => '<p>' . __( 'Pages:' ),
                'after'            => '</p>',


@@ -806,8 +822,6 @@ function wp_link_pages( $args = '' ) {
         */
        $r = apply_filters( 'wp_link_pages_args', $params );
 
         */
        $r = apply_filters( 'wp_link_pages_args', $params );
 

-       global $page, $numpages, $multipage, $more;
-

        $output = '';
        if ( $multipage ) {
                if ( 'number' == $r['next_or_number'] ) {
        $output = '';
        if ( $multipage ) {
                if ( 'number' == $r['next_or_number'] ) {


@@ -877,6 +891,8 @@ function wp_link_pages( $args = '' ) {
  * @since 3.1.0
  * @access private
  *
  * @since 3.1.0
  * @access private
  *

+ * @global WP_Rewrite $wp_rewrite
+ *

  * @param int $i Page number.
  * @return string Link.
  */
  * @param int $i Page number.
  * @return string Link.
  */


@@ -921,7 +937,7 @@ function _wp_link_page( $i ) {
  * @since 1.5.0
  *
  * @param string $key Meta data key name.
  * @since 1.5.0
  *
  * @param string $key Meta data key name.

- * @return bool|string|array Array of values or single value, if only one element exists. False will be returned if key does not exist.
+ * @return false|string|array Array of values or single value, if only one element exists. False will be returned if key does not exist.

  */
 function post_custom( $key = '' ) {
        $custom = get_post_custom();
  */
 function post_custom( $key = '' ) {
        $custom = get_post_custom();


@@ -974,6 +990,7 @@ function the_meta() {
  *
  * @since 2.1.0
  * @since 4.2.0 The `$value_field` argument was added.
  *
  * @since 2.1.0
  * @since 4.2.0 The `$value_field` argument was added.

+ * @since 4.3.0 The `$class` argument was added.

  *
  * @param array|string $args {
  *     Optional. Array or string of arguments to generate a pages drop-down element.
  *
  * @param array|string $args {
  *     Optional. Array or string of arguments to generate a pages drop-down element.


@@ -986,6 +1003,7 @@ function the_meta() {
  *     @type string       $name                  Value for the 'name' attribute of the select element.
  *                                               Default 'page_id'.
  *     @type string       $id                    Value for the 'id' attribute of the select element.
  *     @type string       $name                  Value for the 'name' attribute of the select element.
  *                                               Default 'page_id'.
  *     @type string       $id                    Value for the 'id' attribute of the select element.

+ *     @type string       $class                 Value for the 'class' attribute of the select element. Default: none.

  *                                               Defaults to the value of `$name`.
  *     @type string       $show_option_none      Text to display for showing no pages. Default empty (does not display).
  *     @type string       $show_option_no_change Text to display for "no change" option. Default empty (does not display).
  *                                               Defaults to the value of `$name`.
  *     @type string       $show_option_none      Text to display for showing no pages. Default empty (does not display).
  *     @type string       $show_option_no_change Text to display for "no change" option. Default empty (does not display).


@@ -1000,6 +1018,7 @@ function wp_dropdown_pages( $args = '' ) {
                'depth' => 0, 'child_of' => 0,
                'selected' => 0, 'echo' => 1,
                'name' => 'page_id', 'id' => '',
                'depth' => 0, 'child_of' => 0,
                'selected' => 0, 'echo' => 1,
                'name' => 'page_id', 'id' => '',

+               'class' => '',

                'show_option_none' => '', 'show_option_no_change' => '',
                'option_none_value' => '',
                'value_field' => 'ID',
                'show_option_none' => '', 'show_option_no_change' => '',
                'option_none_value' => '',
                'value_field' => 'ID',


@@ -1015,7 +1034,12 @@ function wp_dropdown_pages( $args = '' ) {
        }
 
        if ( ! empty( $pages ) ) {
        }
 
        if ( ! empty( $pages ) ) {

-               $output = "<select name='" . esc_attr( $r['name'] ) . "' id='" . esc_attr( $r['id'] ) . "'>\n";
+               $class = '';
+               if ( ! empty( $r['class'] ) ) {
+                       $class = " class='" . esc_attr( $r['class'] ) . "'";
+               }
+
+               $output = "<select name='" . esc_attr( $r['name'] ) . "'" . $class . " id='" . esc_attr( $r['id'] ) . "'>\n";

                if ( $r['show_option_no_change'] ) {
                        $output .= "\t<option value=\"-1\">" . $r['show_option_no_change'] . "</option>\n";
                }
                if ( $r['show_option_no_change'] ) {
                        $output .= "\t<option value=\"-1\">" . $r['show_option_no_change'] . "</option>\n";
                }


@@ -1048,6 +1072,8 @@ function wp_dropdown_pages( $args = '' ) {
  *
  * @see get_pages()
  *
  *
  * @see get_pages()
  *

+ * @global WP_Query $wp_query
+ *

  * @param array|string $args {
  *     Array or string of arguments. Optional.
  *
  * @param array|string $args {
  *     Array or string of arguments. Optional.
  *


@@ -1074,7 +1100,7 @@ function wp_dropdown_pages( $args = '' ) {
  *                                will not be wrapped with unordered list `<ul>` tags. Default 'Pages'.
  *     @type Walker $walker       Walker instance to use for listing pages. Default empty (Walker_Page).
  * }
  *                                will not be wrapped with unordered list `<ul>` tags. Default 'Pages'.
  *     @type Walker $walker       Walker instance to use for listing pages. Default empty (Walker_Page).
  * }

- * @return string HTML list of pages.
+ * @return string|void HTML list of pages.

  */
 function wp_list_pages( $args = '' ) {
        $defaults = array(
  */
 function wp_list_pages( $args = '' ) {
        $defaults = array(


@@ -1172,7 +1198,7 @@ function wp_list_pages( $args = '' ) {
  *     @type int|bool|string $show_home   Whether to display the link to the home page. Can just enter the text
  *                                        you'd like shown for the home link. 1|true defaults to 'Home'.
  * }
  *     @type int|bool|string $show_home   Whether to display the link to the home page. Can just enter the text
  *                                        you'd like shown for the home link. 1|true defaults to 'Home'.
  * }

- * @return string html menu
+ * @return string|void HTML menu

  */
 function wp_page_menu( $args = array() ) {
        $defaults = array('sort_column' => 'menu_order, post_title', 'menu_class' => 'menu', 'echo' => true, 'link_before' => '', 'link_after' => '');
  */
 function wp_page_menu( $args = array() ) {
        $defaults = array('sort_column' => 'menu_order, post_title', 'menu_class' => 'menu', 'echo' => true, 'link_before' => '', 'link_after' => '');


@@ -1249,9 +1275,14 @@ function wp_page_menu( $args = array() ) {
  *
  * @uses Walker_Page to create HTML list content.
  * @since 2.1.0
  *
  * @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
        if ( empty($r['walker']) )
                $walker = new Walker_Page;
        else


@@ -1272,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.
  * @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();
  */
 function walk_page_dropdown_tree() {
        $args = func_get_args();


@@ -1310,8 +1343,8 @@ class Walker_Page extends Walker {
         * @since 2.1.0
         *
         * @param string $output Passed by reference. Used to append additional content.
         * @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

         */
        public function start_lvl( &$output, $depth = 0, $args = array() ) {
                $indent = str_repeat("\t", $depth);
         */
        public function start_lvl( &$output, $depth = 0, $args = array() ) {
                $indent = str_repeat("\t", $depth);


@@ -1323,8 +1356,8 @@ class Walker_Page extends Walker {
         * @since 2.1.0
         *
         * @param string $output Passed by reference. Used to append additional content.
         * @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

         */
        public function end_lvl( &$output, $depth = 0, $args = array() ) {
                $indent = str_repeat("\t", $depth);
         */
        public function end_lvl( &$output, $depth = 0, $args = array() ) {
                $indent = str_repeat("\t", $depth);


@@ -1335,11 +1368,11 @@ class Walker_Page extends Walker {
         * @see Walker::start_el()
         * @since 2.1.0
         *
         * @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

         */
        public function start_el( &$output, $page, $depth = 0, $args = array(), $current_page = 0 ) {
                if ( $depth ) {
         */
        public function start_el( &$output, $page, $depth = 0, $args = array(), $current_page = 0 ) {
                if ( $depth ) {


@@ -1385,6 +1418,7 @@ class Walker_Page extends Walker {
                $css_classes = implode( ' ', apply_filters( 'page_css_class', $css_class, $page, $depth, $args, $current_page ) );
 
                if ( '' === $page->post_title ) {
                $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 );
                }
 
                        $page->post_title = sprintf( __( '#%d (no title)' ), $page->ID );
                }
 


@@ -1419,8 +1453,8 @@ 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 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

         */
        public function end_el( &$output, $page, $depth = 0, $args = array() ) {
                $output .= "</li>\n";
         */
        public function end_el( &$output, $page, $depth = 0, $args = array() ) {
                $output .= "</li>\n";


@@ -1458,8 +1492,8 @@ class Walker_PageDropdown extends Walker {
         * @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
         * @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
+        *                       element. Uses 'value_field' argument to fill "value" attribute. See {@see wp_dropdown_pages()}.
+        * @param int    $id

         */
        public function start_el( &$output, $page, $depth = 0, $args = array(), $id = 0 ) {
                $pad = str_repeat('&nbsp;', $depth * 3);
         */
        public function start_el( &$output, $page, $depth = 0, $args = array(), $id = 0 ) {
                $pad = str_repeat('&nbsp;', $depth * 3);


@@ -1475,6 +1509,7 @@ class Walker_PageDropdown extends Walker {
 
                $title = $page->post_title;
                if ( '' === $title ) {
 
                $title = $page->post_title;
                if ( '' === $title ) {

+                       /* translators: %d: ID of a post */

                        $title = sprintf( __( '#%d (no title)' ), $page->ID );
                }
 
                        $title = sprintf( __( '#%d (no title)' ), $page->ID );
                }
 


@@ -1680,10 +1715,7 @@ function is_page_template( $template = '' ) {
                }
        }
 
                }
        }
 

-       if ( 'default' == $template && ! $page_template )
-               return true;
-
-       return false;
+       return ( 'default' === $template && ! $page_template );

 }
 
 /**
 }
 
 /**


@@ -1692,7 +1724,7 @@ function is_page_template( $template = '' ) {
  * @since 3.4.0
  *
  * @param int $post_id Optional. The page ID to check. Defaults to the current post, when used in the loop.
  * @since 3.4.0
  *
  * @param int $post_id Optional. 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
+ * @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 ) {
  *     is in use. Returns false if the post is not a page.
  */
 function get_page_template_slug( $post_id = null ) {


@@ -1711,8 +1743,8 @@ function get_page_template_slug( $post_id = null ) {
  * @since 2.6.0
  *
  * @param int|object $revision Revision ID or revision object.
  * @since 2.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 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 ) )
  */
 function wp_post_revision_title( $revision, $link = true ) {
        if ( !$revision = get_post( $revision ) )


@@ -1746,8 +1778,8 @@ function wp_post_revision_title( $revision, $link = true ) {
  * @since 3.6.0
  *
  * @param int|object $revision Revision ID or revision object.
  * @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 gravatar, user, i18n formatted datetimestamp or localized 'Current Revision'.
+ * @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 ) )
  */
 function wp_post_revision_title_expanded( $revision, $link = true ) {
        if ( !$revision = get_post( $revision ) )


@@ -1796,7 +1828,6 @@ function wp_post_revision_title_expanded( $revision, $link = true ) {
  *
  * @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'
  *
  * @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'

- * @return null

  */
 function wp_list_post_revisions( $post_id = 0, $type = 'all' ) {
        if ( ! $post = get_post( $post_id ) )
  */
 function wp_list_post_revisions( $post_id = 0, $type = 'all' ) {
        if ( ! $post = get_post( $post_id ) )