diff options
author | donncha <donncha@7be80a69-a1ef-0310-a953-fb0f7c49ff36> | 2008-07-03 17:00:59 +0000 |
---|---|---|
committer | donncha <donncha@7be80a69-a1ef-0310-a953-fb0f7c49ff36> | 2008-07-03 17:00:59 +0000 |
commit | 2b6348978ec434e2fa4114085783cf9ada097b22 (patch) | |
tree | a3745bb9ace00b0a8f687bc8c1bfb74bb885077c /wp-includes/feed.php | |
parent | 102dc1d903d95fd7abdf2243d7e047b4b20099d3 (diff) | |
download | wordpress-mu-2b6348978ec434e2fa4114085783cf9ada097b22.tar.gz wordpress-mu-2b6348978ec434e2fa4114085783cf9ada097b22.tar.xz wordpress-mu-2b6348978ec434e2fa4114085783cf9ada097b22.zip |
WP Merge to rev 8249
git-svn-id: http://svn.automattic.com/wordpress-mu/trunk@1347 7be80a69-a1ef-0310-a953-fb0f7c49ff36
Diffstat (limited to 'wp-includes/feed.php')
-rw-r--r-- | wp-includes/feed.php | 275 |
1 files changed, 264 insertions, 11 deletions
diff --git a/wp-includes/feed.php b/wp-includes/feed.php index 4cf5e67..3ff5b9a 100644 --- a/wp-includes/feed.php +++ b/wp-includes/feed.php @@ -1,18 +1,83 @@ <?php +/** + * WordPress Feed API + * + * Many of the functions used in here belong in The Loop, or The Loop for the + * Feeds. + * + * @package WordPress + * @subpackage Feed + */ +/** + * RSS container for the bloginfo function. + * + * You can retrieve anything that you can using the get_bloginfo() function. + * Everything will be stripped of tags and characters converted, when the values + * are retrieved for use in the feeds. + * + * @package WordPress + * @subpackage Feed + * @since 1.5.1 + * @uses apply_filters() Calls 'get_bloginfo_rss' hook with two parameters. + * @see get_bloginfo() For the list of possible values to display. + * + * @param string $show See get_bloginfo() for possible values. + * @return string + */ function get_bloginfo_rss($show = '') { $info = strip_tags(get_bloginfo($show)); return apply_filters('get_bloginfo_rss', convert_chars($info), $show); } +/** + * Display RSS container for the bloginfo function. + * + * You can retrieve anything that you can using the get_bloginfo() function. + * Everything will be stripped of tags and characters converted, when the values + * are retrieved for use in the feeds. + * + * @package WordPress + * @subpackage Feed + * @since 0.71 + * @uses apply_filters() Calls 'bloginfo_rss' hook with two parameters. + * @see get_bloginfo() For the list of possible values to display. + * + * @param string $show See get_bloginfo() for possible values. + */ function bloginfo_rss($show = '') { echo apply_filters('bloginfo_rss', get_bloginfo_rss($show), $show); } +/** + * Retrieve the default feed. + * + * The default feed is 'rss2', unless a plugin changes it through the + * 'default_feed' filter. + * + * @package WordPress + * @subpackage Feed + * @since 2.5 + * @uses apply_filters() Calls 'default_feed' hook on the default feed string. + * + * @return string Default feed, or for example 'rss2', 'atom', etc. + */ function get_default_feed() { return apply_filters('default_feed', 'rss2'); } +/** + * Retrieve the blog title for the feed title. + * + * @package WordPress + * @subpackage Feed + * @since 2.2.0 + * @uses apply_filters() Calls 'get_wp_title_rss' hook on title. + * @uses wp_title() See function for $sep parameter usage. + * + * @param string $sep Optional.How to separate the title. See wp_title() for more info. + * @return string Error message on failure or blog title on success. + */ function get_wp_title_rss($sep = '»') { $title = wp_title($sep, false); if ( is_wp_error( $title ) ) @@ -21,22 +86,79 @@ function get_wp_title_rss($sep = '»') { return $title; } +/** + * Display the blog title for display of the feed title. + * + * @package WordPress + * @subpackage Feed + * @since 2.2.0 + * @uses apply_filters() Calls 'wp_title_rss' on the blog title. + * @see wp_title() $sep parameter usage. + * + * @param string $sep Optional. + */ function wp_title_rss($sep = '»') { echo apply_filters('wp_title_rss', get_wp_title_rss($sep)); } +/** + * Retrieve the current post title for the feed. + * + * @package WordPress + * @subpackage Feed + * @since 2.0.0 + * @uses apply_filters() Calls 'the_title_rss' on the post title. + * + * @return string Current post title. + */ function get_the_title_rss() { $title = get_the_title(); $title = apply_filters('the_title_rss', $title); return $title; } - +/** + * Display the post title in the feed. + * + * @package WordPress + * @subpackage Feed + * @since 0.71 + * @uses get_the_title_rss() Used to retrieve current post title. + */ function the_title_rss() { echo get_the_title_rss(); } - +/** + * Display the post content for the feed. + * + * For encoding the html or the $encode_html parameter, there are three possible + * values. '0' will make urls footnotes and use make_url_footnote(). '1' will + * encode special characters and automatically display all of the content. The + * value of '2' will strip all HTML tags from the content. + * + * Also note that you cannot set the amount of words and not set the html + * encoding. If that is the case, then the html encoding will default to 2, + * which will strip all HTML tags. + * + * To restrict the amount of words of the content, you can use the cut + * parameter. If the content is less than the amount, then there won't be any + * dots added to the end. If there is content left over, then dots will be added + * and the rest of the content will be removed. + * + * @package WordPress + * @subpackage Feed + * @since 0.71 + * @uses apply_filters() Calls 'the_content_rss' on the content before processing. + * @see get_the_content() For the $more_link_text, $stripteaser, and $more_file + * parameters. + * + * @param string $more_link_text Optional. Text to display when more content is available but not displayed. + * @param int|bool $stripteaser Optional. Default is 0. + * @param string $more_file Optional. + * @param int $cut Optional. Amount of words to keep for the content. + * @param int $encode_html Optional. How to encode the content. + */ function the_content_rss($more_link_text='(more...)', $stripteaser=0, $more_file='', $cut = 0, $encode_html = 0) { $content = get_the_content($more_link_text, $stripteaser, $more_file); $content = apply_filters('the_content_rss', $content); @@ -59,6 +181,8 @@ function the_content_rss($more_link_text='(more...)', $stripteaser=0, $more_file $k = count($blah); $use_dotdotdot = 0; } + + /** @todo Check performance, might be faster to use array slice instead. */ for ( $i=0; $i<$k; $i++ ) $excerpt .= $blah[$i].' '; $excerpt .= ($use_dotdotdot) ? '...' : ''; @@ -68,21 +192,51 @@ function the_content_rss($more_link_text='(more...)', $stripteaser=0, $more_file echo $content; } - +/** + * Display the post excerpt for the feed. + * + * @package WordPress + * @subpackage Feed + * @since 0.71 + * @uses apply_filters() Calls 'the_excerpt_rss' hook on the excerpt. + */ function the_excerpt_rss() { $output = get_the_excerpt(); echo apply_filters('the_excerpt_rss', $output); } +/** + * Display the permalink to the post for use in feeds. + * + * @package WordPress + * @subpackage Feed + * @since 2.3.0 + * @uses apply_filters() Call 'the_permalink_rss' on the post permalink + */ function the_permalink_rss() { echo apply_filters('the_permalink_rss', get_permalink()); - } +/** + * Display the feed GUID for the current comment. + * + * @package WordPress + * @subpackage Feed + * @since unknown + */ function comment_guid() { echo get_comment_guid(); } +/** + * Retrieve the feed GUID for the current comment. + * + * @package WordPress + * @subpackage Feed + * @since unknown + * + * @return bool|string false on failure or guid for comment on success. + */ function get_comment_guid() { global $comment; @@ -92,24 +246,71 @@ function get_comment_guid() { return get_the_guid($comment->comment_post_ID) . '#comment-' . $comment->comment_ID; } +/** + * Display the link to the comments. + * + * @since 1.5.0 + */ function comment_link() { echo get_comment_link(); } +/** + * Retrieve the current comment author for use in the feeds. + * + * @package WordPress + * @subpackage Feed + * @since 2.0.0 + * @uses apply_filters() Calls 'comment_author_rss' hook on comment author. + * @uses get_comment_author() + * + * @return string Comment Author + */ function get_comment_author_rss() { return apply_filters('comment_author_rss', get_comment_author() ); } +/** + * Display the current comment author in the feed. + * + * @package WordPress + * @subpackage Feed + * @since 1.0.0 + */ function comment_author_rss() { echo get_comment_author_rss(); } +/** + * Display the current comment content for use in the feeds. + * + * @package WordPress + * @subpackage Feed + * @since 1.0.0 + * @uses apply_filters() Calls 'comment_text_rss' filter on comment content. + * @uses get_comment_text() + */ function comment_text_rss() { $comment_text = get_comment_text(); $comment_text = apply_filters('comment_text_rss', $comment_text); echo $comment_text; } +/** + * Retrieve all of the post categories, formatted for use in feeds. + * + * All of the categories for the current post in the feed loop, will be + * retrieved and have feed markup added, so that they can easily be added to the + * RSS2, Atom, or RSS1 and RSS0.91 RDF feeds. + * + * @package WordPress + * @subpackage Feed + * @since 2.1.0 + * @uses apply_filters() + * + * @param string $type Optional, default is 'rss'. Either 'rss', 'atom', or 'rdf'. + * @return string All of the post categories for displaying in the feed. + */ function get_the_category_rss($type = 'rss') { $categories = get_the_category(); $tags = get_the_tags(); @@ -142,10 +343,29 @@ function get_the_category_rss($type = 'rss') { return apply_filters('the_category_rss', $the_list, $type); } +/** + * Display the post categories in the feed. + * + * @package WordPress + * @subpackage Feed + * @since 0.71 + * @see get_the_category_rss() For better explanation. + * + * @param string $type Optional, default is 'rss'. Either 'rss', 'atom', or 'rdf'. + */ function the_category_rss($type = 'rss') { echo get_the_category_rss($type); } +/** + * Display the HTML type based on the blog setting. + * + * The two possible values are either 'xhtml' or 'html'. + * + * @package WordPress + * @subpackage Feed + * @since 2.2.0 + */ function html_type_rss() { $type = get_bloginfo('html_type'); if (strpos($type, 'xhtml') !== false) @@ -155,7 +375,24 @@ function html_type_rss() { echo $type; } - +/** + * Display the rss enclosure for the current post. + * + * Uses the global $post to check whether the post requires a password and if + * the user has the password for the post. If not then it will return before + * displaying. + * + * Also uses the function get_post_custom() to get the post's 'enclosure' + * metadata field and parses the value to display the enclosure(s). The + * enclosure(s) consist of enclosure HTML tag(s) with a URI and other + * attributes. + * + * @package WordPress + * @subpackage Template + * @since 1.5.0 + * @uses apply_filters() Calls 'rss_enclosure' hook on rss enclosure. + * @uses get_post_custom() To get the current post enclosure metadata. + */ function rss_enclosure() { global $post; if ( !empty($post->post_password) && (!isset($_COOKIE['wp-postpass_'.COOKIEHASH]) || $_COOKIE['wp-postpass_'.COOKIEHASH] != $post->post_password) ) @@ -171,6 +408,23 @@ function rss_enclosure() { } } +/** + * Display the atom enclosure for the current post. + * + * Uses the global $post to check whether the post requires a password and if + * the user has the password for the post. If not then it will return before + * displaying. + * + * Also uses the function get_post_custom() to get the post's 'enclosure' + * metadata field and parses the value to display the enclosure(s). The + * enclosure(s) consist of link HTML tag(s) with a URI and other attributes. + * + * @package WordPress + * @subpackage Template + * @since 2.2.0 + * @uses apply_filters() Calls 'atom_enclosure' hook on atom enclosure. + * @uses get_post_custom() To get the current post enclosure metadata. + */ function atom_enclosure() { global $post; if ( !empty($post->post_password) && ($_COOKIE['wp-postpass_'.COOKIEHASH] != $post->post_password) ) @@ -187,7 +441,7 @@ function atom_enclosure() { } /** - * prep_atom_text_construct() - Determine the type of a given string of data + * Determine the type of a string of data with the data formatted. * * Tell whether the type is text, html, or xhtml, per RFC 4287 section 3.1. * @@ -202,8 +456,8 @@ function atom_enclosure() { * @subpackage Feed * @since 2.5 * - * @param string $data input string - * @return array $result array(type, value) + * @param string $data Input string + * @return array array(type, value) */ function prep_atom_text_construct($data) { if (strpos($data, '<') === false && strpos($data, '&') === false) { @@ -232,14 +486,13 @@ function prep_atom_text_construct($data) { } /** - * self_link() - Generate a correct link for the atom:self elemet + * Display the link for the currently displayed feed in a XSS safe way. * - * Echo the link for the currently displayed feed in a XSS safe way. + * Generate a correct link for the atom:self element. * * @package WordPress * @subpackage Feed * @since 2.5 - * */ function self_link() { echo 'http' |