Make WordPress Core

Ticket #7657: 7657.r8961.diff

File 7657.r8961.diff, 21.2 KB (added by jacobsantos, 15 years ago)

Almost complete inline documentation based off of r8961

  • theme.php

     
    77 */
    88
    99/**
    10  * Get current theme name.
     10 * Retrieve name of the current stylesheet.
    1111 *
    12  * The theme name that the administrator has currently set the frontend theme
     12 * The theme name that the administrator has currently set the front end theme
    1313 * as.
    1414 *
     15 * For all extensive purposes, the template name and the stylesheet name are
     16 * going to be the same for most cases.
     17 *
    1518 * @since 1.5.0
    16  * @uses apply_filters() Calls 'stylesheet' filter
     19 * @uses apply_filters() Calls 'stylesheet' filter on stylesheet name.
    1720 *
    18  * @return string
     21 * @return string Stylesheet name.
    1922 */
    2023function get_stylesheet() {
    2124        return apply_filters('stylesheet', get_option('stylesheet'));
    2225}
    2326
    2427/**
    25  * get_stylesheet_directory() - {@internal Missing Short Description}}
     28 * Retrieve stylesheet directory path for current theme.
    2629 *
    27  * {@internal Missing Long Description}}
    28  *
    2930 * @since 1.5.0
     31 * @uses apply_filters() Calls 'stylesheet_directory' filter on stylesheet directory and theme name.
    3032 *
    31  * @return unknown
     33 * @return string Path to current theme directory.
    3234 */
    3335function get_stylesheet_directory() {
    3436        $stylesheet = get_stylesheet();
     
    3739}
    3840
    3941/**
    40  * get_stylesheet_directory_uri() - {@internal Missing Short Description}}
     42 * Retrieve stylesheet directory URI.
    4143 *
    42  * {@internal Missing Long Description}}
    43  *
    4444 * @since 1.5.0
    4545 *
    46  * @return unknown
     46 * @return string
    4747 */
    4848function get_stylesheet_directory_uri() {
    4949        $stylesheet = get_stylesheet();
     
    5252}
    5353
    5454/**
    55  * get_stylesheet_uri() - {@internal Missing Short Description}}
     55 * Retrieve URI of current theme stylesheet.
    5656 *
    57  * {@internal Missing Long Description}}
     57 * The stylesheet file name is 'style.css' which is appended to {@link
     58 * get_stylesheet_directory_uri() stylesheet directory URI} path.
    5859 *
    5960 * @since 1.5.0
     61 * @uses apply_filters() Calls 'stylesheet_uri' filter on stylesheet URI path and stylesheet directory URI.
    6062 *
    61  * @return unknown
     63 * @return string
    6264 */
    6365function get_stylesheet_uri() {
    6466        $stylesheet_dir_uri = get_stylesheet_directory_uri();
     
    6769}
    6870
    6971/**
    70  * get_locale_stylesheet_uri() - {@internal Missing Short Description}}
     72 * Retrieve localized stylesheet URI.
    7173 *
    7274 * {@internal Missing Long Description}}
    7375 *
    7476 * @since 2.1.0
     77 * @uses apply_filters() Calls 'locale_stylesheet_uri' filter on stylesheet URI path and stylesheet directory URI.
    7578 *
    76  * @return unknown
     79 * @return string
    7780 */
    7881function get_locale_stylesheet_uri() {
    7982        global $wp_locale;
     
    9093}
    9194
    9295/**
    93  * get_template() - {@internal Missing Short Description}}
     96 * Retrieve name of the current theme.
    9497 *
    95  * {@internal Missing Long Description}}
    96  *
    9798 * @since 1.5.0
     99 * @uses apply_filters() Calls 'template' filter on template option.
    98100 *
    99  * @return unknown
     101 * @return string Template name.
    100102 */
    101103function get_template() {
    102104        return apply_filters('template', get_option('template'));
    103105}
    104106
    105107/**
    106  * get_template_directory() - {@internal Missing Short Description}}
     108 * Retrieve current theme directory.
    107109 *
    108  * {@internal Missing Long Description}}
    109  *
    110110 * @since 1.5.0
     111 * @uses apply_filters() Calls 'template_directory' filter on template directory path and template name.
    111112 *
    112  * @return unknown
     113 * @return string Template directory path.
    113114 */
    114115function get_template_directory() {
    115116        $template = get_template();
     
    118119}
    119120
    120121/**
    121  * get_template_directory_uri() - {@internal Missing Short Description}}
     122 * Retrieve theme directory URI.
    122123 *
    123  * {@internal Missing Long Description}}
    124  *
    125124 * @since 1.5.0
     125 * @uses apply_filters() Calls 'template_directory_uri' filter on template directory URI path and template name.
    126126 *
    127  * @return unknown
     127 * @return string Template directory URI.
    128128 */
    129129function get_template_directory_uri() {
    130130        $template = get_template();
     
    133133}
    134134
    135135/**
    136  * get_theme_data() - {@internal Missing Short Description}}
     136 * Retrieve theme data from parsed theme file.
    137137 *
    138138 * {@internal Missing Long Description}}
    139139 *
    140140 * @since 1.5.0
    141141 *
    142  * @param unknown_type $theme_file
    143  * @return unknown
     142 * @param string $theme_file Theme file path.
     143 * @return array Theme data.
    144144 */
    145145function get_theme_data( $theme_file ) {
    146146        $themes_allowed_tags = array(
     
    207207}
    208208
    209209/**
    210  * get_themes() - {@internal Missing Short Description}}
     210 * Retrieve list of themes with theme data in theme directory.
    211211 *
    212212 * {@internal Missing Long Description}}
    213213 *
    214214 * @since 1.5.0
    215215 *
    216  * @return unknown
     216 * @return array Theme list with theme data.
    217217 */
    218218function get_themes() {
    219219        global $wp_themes, $wp_broken_themes;
     
    400400}
    401401
    402402/**
    403  * get_theme() - {@internal Missing Short Description}}
     403 * Retrieve theme data.
    404404 *
    405  * {@internal Missing Long Description}}
    406  *
    407405 * @since 1.5.0
    408406 *
    409  * @param unknown_type $theme
    410  * @return unknown
     407 * @param string $theme Theme name.
     408 * @return array|null Null, if theme name does not exist. Theme data, if exists.
    411409 */
    412410function get_theme($theme) {
    413411        $themes = get_themes();
     
    415413        if ( array_key_exists($theme, $themes) )
    416414                return $themes[$theme];
    417415
    418         return NULL;
     416        return null;
    419417}
    420418
    421419/**
    422  * get_current_theme() - {@internal Missing Short Description}}
     420 * Retrieve current theme display name.
    423421 *
    424  * {@internal Missing Long Description}}
     422 * If the 'current_theme' option has already been set, then it will be returned
     423 * instead. If it is not set, then each theme will be iterated over until both
     424 * the current stylesheet and current template name.
    425425 *
    426426 * @since 1.5.0
    427427 *
    428  * @return unknown
     428 * @return string
    429429 */
    430430function get_current_theme() {
    431431        if ( $theme = get_option('current_theme') )
     
    453453}
    454454
    455455/**
    456  * get_theme_root() - {@internal Missing Short Description}}
     456 * Retrieve path to themes directory.
    457457 *
    458  * {@internal Missing Long Description}}
     458 * Does not have trailing slash.
    459459 *
    460460 * @since 1.5.0
     461 * @uses apply_filters() Calls 'theme_root' filter on path.
    461462 *
    462  * @return unknown
     463 * @return string Theme path.
    463464 */
    464465function get_theme_root() {
    465466        return apply_filters('theme_root', WP_CONTENT_DIR . "/themes");
    466467}
    467468
    468469/**
    469  * get_theme_root_uri() - {@internal Missing Short Description}}
     470 * Retrieve URI for themes directory.
    470471 *
    471  * {@internal Missing Long Description}}
     472 * Does not have trailing slash.
    472473 *
    473474 * @since 1.5.0
    474475 *
    475  * @return unknown
     476 * @return string Themes URI.
    476477 */
    477478function get_theme_root_uri() {
    478479        return apply_filters('theme_root_uri', content_url('themes'), get_option('siteurl'));
    479480}
    480481
    481482/**
    482  * get_query_template() - {@internal Missing Short Description}}
     483 * Retrieve path to file without the use of extension.
    483484 *
    484  * {@internal Missing Long Description}}
     485 * Used to quickly retrieve the path of file without including the file
     486 * extension. It will also check the parent template, if the file exists, with
     487 * the use of {@link locate_template()}. Allows for more generic file location
     488 * without the use of the other get_*_template() functions.
    485489 *
     490 * Can be used with include() or require() to retrieve path.
     491 * <code>
     492 * if( '' != get_query_template( '404' ) )
     493 *     include( get_query_template( '404' ) );
     494 * </code>
     495 * or the same can be accomplished with
     496 * <code>
     497 * if( '' != get_404_template() )
     498 *     include( get_404_template() );
     499 * </code>
     500 *
    486501 * @since 1.5.0
    487502 *
    488  * @param unknown_type $type
    489  * @return unknown
     503 * @param string $type Filename without extension.
     504 * @return string Full path to file.
    490505 */
    491506function get_query_template($type) {
    492507        $type = preg_replace( '|[^a-z0-9-]+|', '', $type );
     
    494509}
    495510
    496511/**
    497  * get_404_template() - {@internal Missing Short Description}}
     512 * Retrieve path of 404 template in current or parent template.
    498513 *
    499  * {@internal Missing Long Description}}
    500  *
    501514 * @since 1.5.0
    502515 *
    503  * @return unknown
     516 * @return string
    504517 */
    505518function get_404_template() {
    506519        return get_query_template('404');
    507520}
    508521
    509522/**
    510  * get_archive_template() - {@internal Missing Short Description}}
     523 * Retrieve path of archive template in current or parent template.
    511524 *
    512  * {@internal Missing Long Description}}
    513  *
    514525 * @since 1.5.0
    515526 *
    516  * @return unknown
     527 * @return string
    517528 */
    518529function get_archive_template() {
    519530        return get_query_template('archive');
    520531}
    521532
    522533/**
    523  * get_author_template() - {@internal Missing Short Description}}
     534 * Retrieve path of author template in current or parent template.
    524535 *
    525  * {@internal Missing Long Description}}
    526  *
    527536 * @since 1.5.0
    528537 *
    529  * @return unknown
     538 * @return string
    530539 */
    531540function get_author_template() {
    532541        return get_query_template('author');
    533542}
    534543
    535544/**
    536  * get_category_template() - {@internal Missing Short Description}}
     545 * Retrieve path of category template in current or parent template.
    537546 *
    538  * {@internal Missing Long Description}}
     547 * Works by retrieving the current category ID, for example 'category-1.php' and
     548 * will fallback to category.php template, if the ID category file doesn't
     549 * exist.
    539550 *
    540551 * @since 1.5.0
     552 * @uses apply_filters() Calls 'category_template' on file path of category template.
    541553 *
    542  * @return unknown
     554 * @return string
    543555 */
    544556function get_category_template() {
    545         $template =locate_template(array("category-" . absint( get_query_var('cat') ) . '.php',"category.php"));
     557        $template = locate_template(array("category-" . absint( get_query_var('cat') ) . '.php', 'category.php'));
    546558        return apply_filters('category_template', $template);
    547559}
    548560
    549561/**
    550  * get_tag_template() - {@internal Missing Short Description}}
     562 * Retrieve path of tag template in current or parent template.
    551563 *
    552  * {@internal Missing Long Description}}
     564 * Works by retrieving the current tag ID, for example 'tag-1.php' and will
     565 * fallback to tag.php template, if the ID tag file doesn't exist.
    553566 *
    554567 * @since 2.3.0
     568 * @uses apply_filters() Calls 'tag_template' on file path of tag template.
    555569 *
    556  * @return unknown
     570 * @return string
    557571 */
    558572function get_tag_template() {
    559         $template = locate_template(array("tag-" . absint( get_query_var('tag') ) . '.php',"tag.php"));
     573        $template = locate_template(array("tag-" . absint( get_query_var('tag') ) . '.php', 'tag.php'));
    560574        return apply_filters('tag_template', $template);
    561575}
    562576
    563 /**
    564  * get_date_template() - {@internal Missing Short Description}}
    565  *
    566  * {@internal Missing Long Description}}
    567  *
    568  * @since 1.5.0
    569  *
    570  * @return unknown
    571  */
    572577function get_taxonomy_template() {
    573578        $taxonomy = get_query_var('taxonomy');
    574579        $term = get_query_var('term');
     
    578583                $templates[] = "taxonomy-$taxonomy-$term.php";
    579584        if ( $taxonomy )
    580585                $templates[] = "taxonomy-$taxonomy.php";
    581        
     586
    582587        $templates[] = "taxonomy.php";
    583588
    584589        $template = locate_template($templates);
    585590        return apply_filters('taxonomy_template', $template);
    586591}
    587592
     593/**
     594 * Retrieve path of date template in current or parent template.
     595 *
     596 * @since 1.5.0
     597 *
     598 * @return string
     599 */
    588600function get_date_template() {
    589601        return get_query_template('date');
    590602}
    591603
    592604/**
    593  * get_home_template() - {@internal Missing Short Description}}
     605 * Retrieve path of home template in current or parent template.
    594606 *
    595  * {@internal Missing Long Description}}
     607 * Attempts to locate 'home.php' first before falling back to 'index.php'.
    596608 *
    597609 * @since 1.5.0
     610 * @uses apply_filters() Calls 'home_template' on file path of home template.
    598611 *
    599  * @return unknown
     612 * @return string
    600613 */
    601614function get_home_template() {
    602         $template = locate_template(array('home.php','index.php'));
     615        $template = locate_template(array('home.php', 'index.php'));
    603616        return apply_filters('home_template', $template);
    604617}
    605618
    606619/**
    607  * get_page_template() - {@internal Missing Short Description}}
     620 * Retrieve path of page template in current or parent template.
    608621 *
    609  * {@internal Missing Long Description}}
     622 * First attempt is to look for the file in the '_wp_page_template' page meta
     623 * data. The second attempt, if the first has a file and is not empty, is to
     624 * look for 'page.php'.
    610625 *
    611626 * @since 1.5.0
    612627 *
    613  * @return unknown
     628 * @return string
    614629 */
    615630function get_page_template() {
    616631        global $wp_query;
     
    624639        $templates = array();
    625640        if ( !empty($template) && !validate_file($template) )
    626641                $templates[] = $template;
    627        
     642
    628643        $templates[] = "page.php";
    629644
    630645        return apply_filters('page_template', locate_template($templates));
    631646}
    632647
    633648/**
    634  * get_paged_template() - {@internal Missing Short Description}}
     649 * Retrieve path of paged template in current or parent template.
    635650 *
    636  * {@internal Missing Long Description}}
    637  *
    638651 * @since 1.5.0
    639652 *
    640  * @return unknown
     653 * @return string
    641654 */
    642655function get_paged_template() {
    643656        return get_query_template('paged');
    644657}
    645658
    646659/**
    647  * get_search_template() - {@internal Missing Short Description}}
     660 * Retrieve path of search template in current or parent template.
    648661 *
    649  * {@internal Missing Long Description}}
    650  *
    651662 * @since 1.5.0
    652663 *
    653  * @return unknown
     664 * @return string
    654665 */
    655666function get_search_template() {
    656667        return get_query_template('search');
    657668}
    658669
    659670/**
    660  * get_single_template() - {@internal Missing Short Description}}
     671 * Retrieve path of single template in current or parent template.
    661672 *
    662  * {@internal Missing Long Description}}
    663  *
    664673 * @since 1.5.0
    665674 *
    666675 * @return unknown
     
    670679}
    671680
    672681/**
    673  * get_attachment_template() - {@internal Missing Short Description}}
     682 * Retrieve path of attachment template in current or parent template.
    674683 *
    675  * {@internal Missing Long Description}}
     684 * The attachment path first checks if the first part of the mime type exists.
     685 * The second check is for the second part of the mime type. The last check is
     686 * for both types separated by an underscore. If neither are found then the file
     687 * 'attachment.php' is checked and returned.
    676688 *
     689 * Some examples for the 'text/plain' mime type are 'text.php', 'plain.php', and
     690 * finally 'text_plain.php'.
     691 *
    677692 * @since 2.0.0
    678693 *
    679  * @return unknown
     694 * @return string
    680695 */
    681696function get_attachment_template() {
    682697        global $posts;
     
    692707}
    693708
    694709/**
    695  * get_comments_popup_template() - {@internal Missing Short Description}}
     710 * Retrieve path of comment popup template in current or parent template.
    696711 *
    697  * {@internal Missing Long Description}}
     712 * Checks for comment popup template in current template, if it exists or in the
     713 * parent template. If it doesn't exist, then it retrieves the comment-popup.php
     714 * file from the default theme. The default theme must then exist for it to
     715 * work.
    698716 *
    699717 * @since 1.5.0
     718 * @uses apply_filters() Calls 'comments_popup_template' filter on path.
    700719 *
    701  * @return unknown
     720 * @return string
    702721 */
    703722function get_comments_popup_template() {
    704723        $template = locate_template(array("comments-popup.php"));
     
    709728}
    710729
    711730/**
    712  * Returns the name of the highest priority template file that exists
     731 * Retrieve the name of the highest priority template file that exists.
    713732 *
    714733 * Searches in the STYLESHEETPATH before TEMPLATEPATH so that themes which
    715734 * inherit from a parent theme can just overload one file.
    716  * @since 2.7
    717735 *
    718  * @param array $template_names Array of template files to search for in priority order
     736 * @since 2.7.0
     737 *
     738 * @param array $template_names Array of template files to search for in priority order.
    719739 * @param bool $load If true the template file will be loaded if it is found.
    720740 * @return string The template filename if one is located.
    721741 */
    722742function locate_template($template_names, $load = false) {
    723743        if (!is_array($template_names))
    724744                return '';
    725        
     745
    726746        $located = '';
    727747        foreach($template_names as $template_name) {
    728748                if ( file_exists(STYLESHEETPATH . '/' . $template_name)) {
     
    733753                        break;
    734754                }
    735755        }
    736        
     756
    737757        if ($load && '' != $located)
    738758                load_template($located);
    739        
     759
    740760        return $located;
    741761}
    742762
    743763/**
    744  * load_template() - {@internal Missing Short Description}}
     764 * Require once the template file with WordPress environment.
    745765 *
    746  * {@internal Missing Long Description}}
     766 * The globals are set up for the template file to ensure that the WordPress
     767 * environment is available from within the function. The query variables are
     768 * also available.
    747769 *
    748770 * @since 1.5.0
    749771 *
    750  * @param unknown_type $_template_file
     772 * @param string $_template_file Path to template file.
    751773 */
    752774function load_template($_template_file) {
    753775        global $posts, $post, $wp_did_header, $wp_did_template_redirect, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;
     
    759781}
    760782
    761783/**
    762  * locale_stylesheet() - {@internal Missing Short Description}}
     784 * Display localized stylesheet link element.
    763785 *
    764  * {@internal Missing Long Description}}
    765  *
    766786 * @since 2.1.0
    767787 */
    768788function locale_stylesheet() {
     
    773793}
    774794
    775795/**
    776  * switch_theme() - {@internal Missing Short Description}}
     796 * {@internal Missing Short Description}}
    777797 *
    778798 * {@internal Missing Long Description}}
    779799 *
     
    838858}
    839859
    840860/**
    841  * validate_current_theme() - {@internal Missing Short Description}}
     861 * Checks that current theme files 'index.php' and 'style.css' exists.
    842862 *
    843  * {@internal Missing Long Description}}
     863 * Does not check the 'default' theme. The 'default' theme should always exist
     864 * or should have another theme renamed to that template name and directory
     865 * path. Will switch theme to default if current theme does not validate.
    844866 *
    845867 * @since 1.5.0
    846868 *
    847  * @return unknown
     869 * @return bool
    848870 */
    849871function validate_current_theme() {
    850872        // Don't validate during an install/upgrade.
     
    865887}
    866888
    867889/**
    868  * get_theme_mod() - {@internal Missing Short Description}}
     890 * Retrieve theme modification value for the current theme.
    869891 *
    870  * {@internal Missing Long Description}}
     892 * If the modification name does not exist, then the $default will be passed
     893 * through {@link http://php.net/sprintf sprintf()} PHP function with the first
     894 * string the template directory URI and the second string the stylesheet
     895 * directory URI.
    871896 *
    872897 * @since 2.1.0
     898 * @uses apply_filters() Calls 'theme_mod_$name' filter on the value.
    873899 *
    874  * @param unknown_type $name
    875  * @param unknown_type $default
    876  * @return unknown
     900 * @param string $name Theme modification name.
     901 * @param bool|string $default
     902 * @return string
    877903 */
    878904function get_theme_mod($name, $default = false) {
    879905        $theme = get_current_theme();
     
    887913}
    888914
    889915/**
    890  * set_theme_mod() - {@internal Missing Short Description}}
     916 * Update theme modification value for the current theme.
    891917 *
    892  * {@internal Missing Long Description}}
    893  *
    894918 * @since 2.1.0
    895919 *
    896  * @param unknown_type $name
    897  * @param unknown_type $value
     920 * @param string $name Theme modification name.
     921 * @param string $value theme modification value.
    898922 */
    899923function set_theme_mod($name, $value) {
    900924        $theme = get_current_theme();
     
    908932}
    909933
    910934/**
    911  * remove_theme_mod() - {@internal Missing Short Description}}
     935 * Remove theme modification name from current theme list.
    912936 *
    913  * {@internal Missing Long Description}}
     937 * If removing the name also removes all elements, then the entire option will
     938 * be removed.
    914939 *
    915940 * @since 2.1.0
    916941 *
    917  * @param unknown_type $name
    918  * @return unknown
     942 * @param string $name Theme modification name.
     943 * @return null
    919944 */
    920945function remove_theme_mod( $name ) {
    921946        $theme = get_current_theme();
     
    935960}
    936961
    937962/**
    938  * remove_theme_mods() - {@internal Missing Short Description}}
     963 * Remove theme modifications option for current theme.
    939964 *
    940  * {@internal Missing Long Description}}
    941  *
    942965 * @since 2.1.0
    943966 */
    944967function remove_theme_mods() {
     
    948971}
    949972
    950973/**
    951  * get_header_textcolor() - {@internal Missing Short Description}}
     974 * Retrieve text color for custom header.
    952975 *
    953  * {@internal Missing Long Description}}
    954  *
    955976 * @since 2.1.0
     977 * @uses HEADER_TEXTCOLOR
    956978 *
    957  * @return unknown
     979 * @return string
    958980 */
    959981function get_header_textcolor() {
    960982        return get_theme_mod('header_textcolor', HEADER_TEXTCOLOR);
    961983}
    962984
    963985/**
    964  * header_textcolor() - {@internal Missing Short Description}}
     986 * Display text color for custom header.
    965987 *
    966  * {@internal Missing Long Description}}
    967  *
    968988 * @since 2.1.0
    969  *
    970989 */
    971990function header_textcolor() {
    972991        echo get_header_textcolor();
    973992}
    974993
    975994/**
    976  * get_header_image() - {@internal Missing Short Description}}
     995 * Retrieve header image for custom header.
    977996 *
    978  * {@internal Missing Long Description}}
    979  *
    980997 * @since 2.1.0
     998 * @uses HEADER_IMAGE
    981999 *
    982  * @return unknown
     1000 * @return string
    9831001 */
    9841002function get_header_image() {
    9851003        return get_theme_mod('header_image', HEADER_IMAGE);
    9861004}
    9871005
    9881006/**
    989  * header_image() - {@internal Missing Short Description}}
     1007 * Display header image path.
    9901008 *
    991  * {@internal Missing Long Description}}
    992  *
    9931009 * @since 2.1.0
    9941010 */
    9951011function header_image() {
     
    9971013}
    9981014
    9991015/**
    1000  * add_custom_image_header() - {@internal Missing Short Description}}
     1016 * Add callbacks for image header display.
    10011017 *
    1002  * {@internal Missing Long Description}}
     1018 * The parameter $header_callback callback will be required to display the
     1019 * content for the 'wp_head' action. The parameter $admin_header_callback
     1020 * callback will be added to Custom_Image_Header class and that will be added
     1021 * to the 'admin_menu' action.
    10031022 *
    10041023 * @since 2.1.0
     1024 * @uses Custom_Image_Header Sets up for $admin_header_callback for administration panel display.
    10051025 *
    1006  * @param unknown_type $header_callback
    1007  * @param unknown_type $admin_header_callback
     1026 * @param callback $header_callback Call on 'wp_head' action.
     1027 * @param callback $admin_header_callback Call on administration panels.
    10081028 */
    10091029function add_custom_image_header($header_callback, $admin_header_callback) {
    10101030        if ( ! empty($header_callback) )