mirror of
https://github.com/WordPress/WordPress.git
synced 2024-06-22 21:04:57 +02:00
Inline Documentation for general-template.php, props jacobsantos, fixes #5640
git-svn-id: http://svn.automattic.com/wordpress/trunk@8874 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
azaozz
parent
3893ebc14e
commit
b61c13ccaf
|
|
@ -282,15 +282,26 @@ function get_bloginfo($show = '', $filter = 'raw') {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Display or retrieve page title for all areas of blog.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* By default, the page title will display the separator before the page title,
|
||||
* so that the blog title will be before the page title. This is not good for
|
||||
* title display, since the blog title shows up on most tabs and not what is
|
||||
* important, which is the page that the user is looking at.
|
||||
*
|
||||
* There are also SEO benefits to having the blog title after or to the 'right'
|
||||
* or the page title. However, it is mostly common sense to have the blog title
|
||||
* to the right with most browsers supporting tabs. You can achieve this by
|
||||
* using the seplocation parameter and setting the value to 'right'. This change
|
||||
* was introduced around 2.5.0, in case backwards compatibility of themes is
|
||||
* important.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*
|
||||
* @param unknown_type $sep
|
||||
* @param unknown_type $display
|
||||
* @return unknown
|
||||
* @param string $sep Optional, default is '»'. How to separate the various items within the page title.
|
||||
* @param bool $display Optional, default is true. Whether to display or retrieve title.
|
||||
* @param string $seplocation Optional. Direction to display title, 'right'.
|
||||
* @return string|null String on retrieve, null when displaying.
|
||||
*/
|
||||
function wp_title($sep = '»', $display = true, $seplocation = '') {
|
||||
global $wpdb, $wp_locale, $wp_query;
|
||||
|
|
@ -398,16 +409,22 @@ function wp_title($sep = '»', $display = true, $seplocation = '') {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Display or retrieve page title for post.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* This is optimized for single.php template file for displaying the post title.
|
||||
* Only useful for posts, does not support pages for example.
|
||||
*
|
||||
* It does not support placing the separator after the title, but by leaving the
|
||||
* prefix parameter empty, you can set the title separator manually. The prefix
|
||||
* does not automatically place a space between the prefix, so if there should
|
||||
* be a space, the parameter value will need to have it at the end.
|
||||
*
|
||||
* @since 0.71
|
||||
* @uses $wpdb
|
||||
*
|
||||
* @param unknown_type $prefix
|
||||
* @param unknown_type $display
|
||||
* @return unknown
|
||||
* @param string $prefix Optional. What to display before the title.
|
||||
* @param bool $display Optional, default is true. Whether to display or retrieve title.
|
||||
* @return string|null Title when retrieving, null when displaying or failure.
|
||||
*/
|
||||
function single_post_title($prefix = '', $display = true) {
|
||||
global $wpdb;
|
||||
|
|
@ -428,15 +445,21 @@ function single_post_title($prefix = '', $display = true) {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Display or retrieve page title for category archive.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* This is useful for category template file or files, because it is optimized
|
||||
* for category page title and with less overhead than {@link wp_title()}.
|
||||
*
|
||||
* It does not support placing the separator after the title, but by leaving the
|
||||
* prefix parameter empty, you can set the title separator manually. The prefix
|
||||
* does not automatically place a space between the prefix, so if there should
|
||||
* be a space, the parameter value will need to have it at the end.
|
||||
*
|
||||
* @since 0.71
|
||||
*
|
||||
* @param unknown_type $prefix
|
||||
* @param unknown_type $display
|
||||
* @return unknown
|
||||
* @param string $prefix Optional. What to display before the title.
|
||||
* @param bool $display Optional, default is true. Whether to display or retrieve title.
|
||||
* @return string|null Title when retrieving, null when displaying or failure.
|
||||
*/
|
||||
function single_cat_title($prefix = '', $display = true ) {
|
||||
$cat = intval( get_query_var('cat') );
|
||||
|
|
@ -454,15 +477,21 @@ function single_cat_title($prefix = '', $display = true ) {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Display or retrieve page title for tag post archive.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* Useful for tag template files for displaying the tag page title. It has less
|
||||
* overhead than {@link wp_title()}, because of its limited implementation.
|
||||
*
|
||||
* It does not support placing the separator after the title, but by leaving the
|
||||
* prefix parameter empty, you can set the title separator manually. The prefix
|
||||
* does not automatically place a space between the prefix, so if there should
|
||||
* be a space, the parameter value will need to have it at the end.
|
||||
*
|
||||
* @since 2.3.0
|
||||
*
|
||||
* @param unknown_type $prefix
|
||||
* @param unknown_type $display
|
||||
* @return unknown
|
||||
* @param string $prefix Optional. What to display before the title.
|
||||
* @param bool $display Optional, default is true. Whether to display or retrieve title.
|
||||
* @return string|null Title when retrieving, null when displaying or failure.
|
||||
*/
|
||||
function single_tag_title($prefix = '', $display = true ) {
|
||||
if ( !is_tag() )
|
||||
|
|
@ -485,15 +514,22 @@ function single_tag_title($prefix = '', $display = true ) {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Display or retrieve page title for post archive based on date.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* Useful for when the template only needs to display the month and year, if
|
||||
* either are available. Optimized for just this purpose, so if it is all that
|
||||
* is needed, should be better than {@link wp_title()}.
|
||||
*
|
||||
* It does not support placing the separator after the title, but by leaving the
|
||||
* prefix parameter empty, you can set the title separator manually. The prefix
|
||||
* does not automatically place a space between the prefix, so if there should
|
||||
* be a space, the parameter value will need to have it at the end.
|
||||
*
|
||||
* @since 0.71
|
||||
*
|
||||
* @param unknown_type $prefix
|
||||
* @param unknown_type $display
|
||||
* @return unknown
|
||||
* @param string $prefix Optional. What to display before the title.
|
||||
* @param bool $display Optional, default is true. Whether to display or retrieve title.
|
||||
* @return string|null Title when retrieving, null when displaying or failure.
|
||||
*/
|
||||
function single_month_title($prefix = '', $display = true ) {
|
||||
global $wp_locale;
|
||||
|
|
@ -521,20 +557,39 @@ function single_month_title($prefix = '', $display = true ) {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Retrieve archive link content based on predefined or custom code.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* The format can be one of four styles. The 'link' for head element, 'option'
|
||||
* for use in the select element, 'html' for use in list (either ol or ul HTML
|
||||
* elements). Custom content is also supported using the before and after
|
||||
* parameters.
|
||||
*
|
||||
* The 'link' format uses the link HTML element with the <em>archives</em>
|
||||
* relationship. The before and after parameters are not used. The text
|
||||
* parameter is used to describe the link.
|
||||
*
|
||||
* The 'option' format uses the option HTML element for use in select element.
|
||||
* The value is the url parameter and the before and after parameters are used
|
||||
* between the text description.
|
||||
*
|
||||
* The 'html' format, which is the default, uses the li HTML element for use in
|
||||
* the list HTML elements. The before parameter is before the link and the after
|
||||
* parameter is after the closing link.
|
||||
*
|
||||
* The custom format uses the before parameter before the link ('a' HTML
|
||||
* element) and the after parameter after the closing link tag. If the above
|
||||
* three values for the format are not used, then custom format is assumed.
|
||||
*
|
||||
* @since 1.0.0
|
||||
* @author Orien
|
||||
* @link http://icecode.com/ link navigation hack by Orien
|
||||
*
|
||||
* @param unknown_type $url
|
||||
* @param unknown_type $text
|
||||
* @param unknown_type $format
|
||||
* @param unknown_type $before
|
||||
* @param unknown_type $after
|
||||
* @return unknown
|
||||
* @param string $url URL to archive.
|
||||
* @param string $text Archive text description.
|
||||
* @param string $format Optional, default is 'html'. Can be 'link', 'option', 'html', or custom.
|
||||
* @param string $before Optional.
|
||||
* @param string $after Optional.
|
||||
* @return string HTML link content for archive.
|
||||
*/
|
||||
function get_archives_link($url, $text, $format = 'html', $before = '', $after = '') {
|
||||
$text = wptexturize($text);
|
||||
|
|
@ -556,13 +611,30 @@ function get_archives_link($url, $text, $format = 'html', $before = '', $after =
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Display archive links based on type and format.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* The 'type' argument offers a few choices and by default will display monthly
|
||||
* archive links. The other options for values are 'daily', 'weekly', 'monthly',
|
||||
* 'yearly', 'postbypost' or 'alpha'. Both 'postbypost' and 'alpha' display the
|
||||
* same archive link list, the difference between the two is that 'alpha'
|
||||
* will order by post title and 'postbypost' will order by post date.
|
||||
*
|
||||
* The date archives will logically display dates with links to the archive post
|
||||
* page. The 'postbypost' and 'alpha' values for 'type' argument will display
|
||||
* the post titles.
|
||||
*
|
||||
* The 'limit' argument will only display a limited amount of links, specified
|
||||
* by the 'limit' integer value. By default, there is no limit. The
|
||||
* 'show_post_count' argument will show how many posts are within the archive.
|
||||
* By default, the 'show_post_count' argument is set to false.
|
||||
*
|
||||
* For the 'format', 'before', and 'after' arguments, see {@link
|
||||
* get_archives_link()}. The values of these arguments have to do with that
|
||||
* function.
|
||||
*
|
||||
* @since 1.2.0
|
||||
*
|
||||
* @param unknown_type $args
|
||||
* @param string|array $args Optional. Override defaults.
|
||||
*/
|
||||
function wp_get_archives($args = '') {
|
||||
global $wpdb, $wp_locale;
|
||||
|
|
@ -621,7 +693,7 @@ function wp_get_archives($args = '') {
|
|||
if ( $arcresults ) {
|
||||
$afterafter = $after;
|
||||
foreach ( (array) $arcresults as $arcresult ) {
|
||||
$url = get_month_link($arcresult->year, $arcresult->month);
|
||||
$url = get_month_link( $arcresult->year, $arcresult->month );
|
||||
$text = sprintf(__('%1$s %2$d'), $wp_locale->get_month($arcresult->month), $arcresult->year);
|
||||
if ( $show_post_count )
|
||||
$after = ' ('.$arcresult->posts.')' . $afterafter;
|
||||
|
|
@ -730,15 +802,13 @@ function wp_get_archives($args = '') {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* Get number of days since the start of the week.
|
||||
*
|
||||
* @since 1.5.0
|
||||
* @usedby get_calendar()
|
||||
*
|
||||
* @param int $num Number of day.
|
||||
* @return int
|
||||
* @return int Days since the start of the week.
|
||||
*/
|
||||
function calendar_week_mod($num) {
|
||||
$base = 7;
|
||||
|
|
@ -746,13 +816,14 @@ function calendar_week_mod($num) {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Display calendar with days that have posts as links.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* The calendar is cached, which will be retrieved, if it exists. If there are
|
||||
* no posts for the month, then it will not be displayed.
|
||||
*
|
||||
* @since 1.0.0
|
||||
*
|
||||
* @param unknown_type $initial
|
||||
* @param bool $initial Optional, default is true. Use initial calendar names.
|
||||
*/
|
||||
function get_calendar($initial = true) {
|
||||
global $wpdb, $m, $monthnum, $year, $wp_locale, $posts;
|
||||
|
|
@ -962,14 +1033,15 @@ add_action( 'update_option_gmt_offset', 'delete_get_calendar_cache' );
|
|||
add_action( 'update_option_start_of_week', 'delete_get_calendar_cache' );
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Display all of the allowed tags in HTML format with attributes.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* This is useful for displaying in the comment area, which elements and
|
||||
* attributes are supported. As well as any plugins which want to display it.
|
||||
*
|
||||
* @since 1.0.1
|
||||
* @uses $allowedtags
|
||||
*
|
||||
* @return unknown
|
||||
* @return string HTML allowed tags entity encoded.
|
||||
*/
|
||||
function allowed_tags() {
|
||||
global $allowedtags;
|
||||
|
|
@ -1310,15 +1382,22 @@ function wp_default_editor() {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Display visual editor forms: TinyMCE, or HTML, or both.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* The amount of rows the text area will have for the content has to be between
|
||||
* 3 and 100 or will default at 12. There is only one option used for all users,
|
||||
* named 'default_post_edit_rows'.
|
||||
*
|
||||
* If the user can not use the rich editor (TinyMCE), then the switch button
|
||||
* will not be displayed.
|
||||
*
|
||||
* @since 2.1.0
|
||||
*
|
||||
* @param unknown_type $content
|
||||
* @param unknown_type $id
|
||||
* @param unknown_type $prev_id
|
||||
* @param string $content Textarea content.
|
||||
* @param string $id HTML ID attribute value.
|
||||
* @param string $prev_id HTML ID name for switching back and forth between visual editors.
|
||||
* @param bool $media_buttons Optional, default is true. Whether to display media buttons.
|
||||
* @param int $tab_index Optional, default is 2. Tabindex for textarea element.
|
||||
*/
|
||||
function the_editor($content, $id = 'content', $prev_id = 'title', $media_buttons = true, $tab_index = 2) {
|
||||
$rows = get_option('default_post_edit_rows');
|
||||
|
|
@ -1441,14 +1520,49 @@ function language_attributes($doctype = 'html') {
|
|||
}
|
||||
|
||||
/**
|
||||
* {@internal Missing Short Description}}
|
||||
* Retrieve paginated link for archive post pages.
|
||||
*
|
||||
* {@internal Missing Long Description}}
|
||||
* Technically, the function can be used to create paginated link list for any
|
||||
* area. The 'base' argument is used to reference the url, which will be used to
|
||||
* create the paginated links. The 'format' argument is then used for replacing
|
||||
* the page number. It is however, most likely and by default, to be used on the
|
||||
* archive post pages.
|
||||
*
|
||||
* The 'type' argument controls format of the returned value. The default is
|
||||
* 'plain', which is just a string with the links separated by a newline
|
||||
* character. The other possible values are either 'array' or 'list'. The
|
||||
* 'array' value will return an array of the paginated link list to offer full
|
||||
* control of display. The 'list' value will place all of the paginated links in
|
||||
* an unordered HTML list.
|
||||
*
|
||||
* The 'total' argument is the total amount of pages and is an integer. The
|
||||
* 'current' argument is the current page number and is also an integer.
|
||||
*
|
||||
* An example of the 'base' argument is "http://example.com/all_posts.php%_%"
|
||||
* and the '%_%' is required. The '%_%' will be replaced by the contents of in
|
||||
* the 'format' argument. An example for the 'format' argument is "?page=%#%"
|
||||
* and the '%#%' is also required. The '%#%' will be replaced with the page
|
||||
* number.
|
||||
*
|
||||
* You can include the previous and next links in the list by setting the
|
||||
* 'prev_next' argument to true, which it is by default. You can set the
|
||||
* previous text, by using the 'prev_text' argument. You can set the next text
|
||||
* by setting the 'next_text' argument.
|
||||
*
|
||||
* If the 'show_all' argument is set to true, then it will show all of the pages
|
||||
* instead of a short list of the pages near the current page. By default, the
|
||||
* 'show_all' is set to false and controlled by the 'end_size' and 'mid_size'
|
||||
* arguments. The 'end_size' argument is how many numbers on either the start
|
||||
* and the end list edges, by default is 1. The 'mid_size' argument is how many
|
||||
* numbers to either side of current page, but not including current page.
|
||||
*
|
||||
* It is possible to add query vars to the link by using the 'add_args' argument
|
||||
* and see {@link add_query_arg()} for more information.
|
||||
*
|
||||
* @since 2.1.0
|
||||
*
|
||||
* @param unknown_type $args
|
||||
* @return unknown
|
||||
* @param string|array $args Optional. Override defaults.
|
||||
* @return array|string String of page links or array of page links.
|
||||
*/
|
||||
function paginate_links( $args = '' ) {
|
||||
$defaults = array(
|
||||
|
|
@ -1460,17 +1574,17 @@ function paginate_links( $args = '' ) {
|
|||
'prev_next' => true,
|
||||
'prev_text' => __('« Previous'),
|
||||
'next_text' => __('Next »'),
|
||||
'end_size' => 1, // How many numbers on either end including the end
|
||||
'mid_size' => 2, // How many numbers to either side of current not including current
|
||||
'end_size' => 1,
|
||||
'mid_size' => 2,
|
||||
'type' => 'plain',
|
||||
'add_args' => false // array of query args to aadd
|
||||
'add_args' => false // array of query args to add
|
||||
);
|
||||
|
||||
$args = wp_parse_args( $args, $defaults );
|
||||
extract($args, EXTR_SKIP);
|
||||
|
||||
// Who knows what else people pass in $args
|
||||
$total = (int) $total;
|
||||
$total = (int) $total;
|
||||
if ( $total < 2 )
|
||||
return;
|
||||
$current = (int) $current;
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user