WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
09/24/2008 05:24:33 AM (16 years ago)
Author:
ryan
Message:

phpdoc for themes.php. Props jacobsantos. see #7657

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/theme.php

    r8791 r8965  
    88
    99/**
    10  * Get current theme name.
    11  *
    12  * The theme name that the administrator has currently set the frontend theme
     10 * Retrieve name of the current stylesheet.
     11 *
     12 * The theme name that the administrator has currently set the front end theme
    1313 * as.
    1414 *
    15  * @since 1.5.0
    16  * @uses apply_filters() Calls 'stylesheet' filter
    17  *
    18  * @return string
     15 * For all extensive purposes, the template name and the stylesheet name are
     16 * going to be the same for most cases.
     17 *
     18 * @since 1.5.0
     19 * @uses apply_filters() Calls 'stylesheet' filter on stylesheet name.
     20 *
     21 * @return string Stylesheet name.
    1922 */
    2023function get_stylesheet() {
    … …  
    2326
    2427/**
    25  * get_stylesheet_directory() - {@internal Missing Short Description}}
    26  *
    27  * {@internal Missing Long Description}}
    28  *
    29  * @since 1.5.0
    30  *
    31  * @return unknown
     28 * Retrieve stylesheet directory path for current theme.
     29 *
     30 * @since 1.5.0
     31 * @uses apply_filters() Calls 'stylesheet_directory' filter on stylesheet directory and theme name.
     32 *
     33 * @return string Path to current theme directory.
    3234 */
    3335function get_stylesheet_directory() {
    … …  
    3840
    3941/**
    40  * get_stylesheet_directory_uri() - {@internal Missing Short Description}}
    41  *
    42  * {@internal Missing Long Description}}
    43  *
    44  * @since 1.5.0
    45  *
    46  * @return unknown
     42 * Retrieve stylesheet directory URI.
     43 *
     44 * @since 1.5.0
     45 *
     46 * @return string
    4747 */
    4848function get_stylesheet_directory_uri() {
    … …  
    5353
    5454/**
    55  * get_stylesheet_uri() - {@internal Missing Short Description}}
    56  *
    57  * {@internal Missing Long Description}}
    58  *
    59  * @since 1.5.0
    60  *
    61  * @return unknown
     55 * Retrieve URI of current theme stylesheet.
     56 *
     57 * The stylesheet file name is 'style.css' which is appended to {@link
     58 * get_stylesheet_directory_uri() stylesheet directory URI} path.
     59 *
     60 * @since 1.5.0
     61 * @uses apply_filters() Calls 'stylesheet_uri' filter on stylesheet URI path and stylesheet directory URI.
     62 *
     63 * @return string
    6264 */
    6365function get_stylesheet_uri() {
    … …  
    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
    75  *
    76  * @return unknown
     77 * @uses apply_filters() Calls 'locale_stylesheet_uri' filter on stylesheet URI path and stylesheet directory URI.
     78 *
     79 * @return string
    7780 */
    7881function get_locale_stylesheet_uri() {
    … …  
    9194
    9295/**
    93  * get_template() - {@internal Missing Short Description}}
    94  *
    95  * {@internal Missing Long Description}}
    96  *
    97  * @since 1.5.0
    98  *
    99  * @return unknown
     96 * Retrieve name of the current theme.
     97 *
     98 * @since 1.5.0
     99 * @uses apply_filters() Calls 'template' filter on template option.
     100 *
     101 * @return string Template name.
    100102 */
    101103function get_template() {
    … …  
    104106
    105107/**
    106  * get_template_directory() - {@internal Missing Short Description}}
    107  *
    108  * {@internal Missing Long Description}}
    109  *
    110  * @since 1.5.0
    111  *
    112  * @return unknown
     108 * Retrieve current theme directory.
     109 *
     110 * @since 1.5.0
     111 * @uses apply_filters() Calls 'template_directory' filter on template directory path and template name.
     112 *
     113 * @return string Template directory path.
    113114 */
    114115function get_template_directory() {
    … …  
    119120
    120121/**
    121  * get_template_directory_uri() - {@internal Missing Short Description}}
    122  *
    123  * {@internal Missing Long Description}}
    124  *
    125  * @since 1.5.0
    126  *
    127  * @return unknown
     122 * Retrieve theme directory URI.
     123 *
     124 * @since 1.5.0
     125 * @uses apply_filters() Calls 'template_directory_uri' filter on template directory URI path and template name.
     126 *
     127 * @return string Template directory URI.
    128128 */
    129129function get_template_directory_uri() {
    … …  
    134134
    135135/**
    136  * get_theme_data() - {@internal Missing Short Description}}
     136 * Retrieve theme data from parsed theme file.
    137137 *
    138138 * {@internal Missing Long Description}}
    … …  
    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 ) {
    … …  
    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}}
    … …  
    214214 * @since 1.5.0
    215215 *
    216  * @return unknown
     216 * @return array Theme list with theme data.
    217217 */
    218218function get_themes() {
    … …  
    401401
    402402/**
    403  * get_theme() - {@internal Missing Short Description}}
    404  *
    405  * {@internal Missing Long Description}}
    406  *
    407  * @since 1.5.0
    408  *
    409  * @param unknown_type $theme
    410  * @return unknown
     403 * Retrieve theme data.
     404 *
     405 * @since 1.5.0
     406 *
     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) {
    … …  
    416414        return $themes[$theme];
    417415
    418     return NULL;
    419 }
    420 
    421 /**
    422  * get_current_theme() - {@internal Missing Short Description}}
    423  *
    424  * {@internal Missing Long Description}}
    425  *
    426  * @since 1.5.0
    427  *
    428  * @return unknown
     416    return null;
     417}
     418
     419/**
     420 * Retrieve current theme display name.
     421 *
     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.
     425 *
     426 * @since 1.5.0
     427 *
     428 * @return string
    429429 */
    430430function get_current_theme() {
    … …  
    454454
    455455/**
    456  * get_theme_root() - {@internal Missing Short Description}}
    457  *
    458  * {@internal Missing Long Description}}
    459  *
    460  * @since 1.5.0
    461  *
    462  * @return unknown
     456 * Retrieve path to themes directory.
     457 *
     458 * Does not have trailing slash.
     459 *
     460 * @since 1.5.0
     461 * @uses apply_filters() Calls 'theme_root' filter on path.
     462 *
     463 * @return string Theme path.
    463464 */
    464465function get_theme_root() {
    … …  
    467468
    468469/**
    469  * get_theme_root_uri() - {@internal Missing Short Description}}
    470  *
    471  * {@internal Missing Long Description}}
    472  *
    473  * @since 1.5.0
    474  *
    475  * @return unknown
     470 * Retrieve URI for themes directory.
     471 *
     472 * Does not have trailing slash.
     473 *
     474 * @since 1.5.0
     475 *
     476 * @return string Themes URI.
    476477 */
    477478function get_theme_root_uri() {
    … …  
    480481
    481482/**
    482  * get_query_template() - {@internal Missing Short Description}}
    483  *
    484  * {@internal Missing Long Description}}
    485  *
    486  * @since 1.5.0
    487  *
    488  * @param unknown_type $type
    489  * @return unknown
     483 * Retrieve path to file without the use of extension.
     484 *
     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.
     489 *
     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 *
     501 * @since 1.5.0
     502 *
     503 * @param string $type Filename without extension.
     504 * @return string Full path to file.
    490505 */
    491506function get_query_template($type) {
    … …  
    495510
    496511/**
    497  * get_404_template() - {@internal Missing Short Description}}
    498  *
    499  * {@internal Missing Long Description}}
    500  *
    501  * @since 1.5.0
    502  *
    503  * @return unknown
     512 * Retrieve path of 404 template in current or parent template.
     513 *
     514 * @since 1.5.0
     515 *
     516 * @return string
    504517 */
    505518function get_404_template() {
    … …  
    508521
    509522/**
    510  * get_archive_template() - {@internal Missing Short Description}}
    511  *
    512  * {@internal Missing Long Description}}
    513  *
    514  * @since 1.5.0
    515  *
    516  * @return unknown
     523 * Retrieve path of archive template in current or parent template.
     524 *
     525 * @since 1.5.0
     526 *
     527 * @return string
    517528 */
    518529function get_archive_template() {
    … …  
    521532
    522533/**
    523  * get_author_template() - {@internal Missing Short Description}}
    524  *
    525  * {@internal Missing Long Description}}
    526  *
    527  * @since 1.5.0
    528  *
    529  * @return unknown
     534 * Retrieve path of author template in current or parent template.
     535 *
     536 * @since 1.5.0
     537 *
     538 * @return string
    530539 */
    531540function get_author_template() {
    … …  
    534543
    535544/**
    536  * get_category_template() - {@internal Missing Short Description}}
    537  *
    538  * {@internal Missing Long Description}}
    539  *
    540  * @since 1.5.0
    541  *
    542  * @return unknown
     545 * Retrieve path of category template in current or parent template.
     546 *
     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.
     550 *
     551 * @since 1.5.0
     552 * @uses apply_filters() Calls 'category_template' on file path of category template.
     553 *
     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}}
    551  *
    552  * {@internal Missing Long Description}}
     562 * Retrieve path of tag template in current or parent template.
     563 *
     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
    555  *
    556  * @return unknown
     568 * @uses apply_filters() Calls 'tag_template' on file path of tag template.
     569 *
     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');
    … …  
    579584    if ( $taxonomy )
    580585        $templates[] = "taxonomy-$taxonomy.php";
    581    
     586
    582587    $templates[] = "taxonomy.php";
    583588
    … …  
    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');
    … …  
    591603
    592604/**
    593  * get_home_template() - {@internal Missing Short Description}}
    594  *
    595  * {@internal Missing Long Description}}
    596  *
    597  * @since 1.5.0
    598  *
    599  * @return unknown
     605 * Retrieve path of home template in current or parent template.
     606 *
     607 * Attempts to locate 'home.php' first before falling back to 'index.php'.
     608 *
     609 * @since 1.5.0
     610 * @uses apply_filters() Calls 'home_template' on file path of home template.
     611 *
     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}}
    608  *
    609  * {@internal Missing Long Description}}
    610  *
    611  * @since 1.5.0
    612  *
    613  * @return unknown
     620 * Retrieve path of page template in current or parent template.
     621 *
     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'.
     625 *
     626 * @since 1.5.0
     627 *
     628 * @return string
    614629 */
    615630function get_page_template() {
    … …  
    625640    if ( !empty($template) && !validate_file($template) )
    626641        $templates[] = $template;
    627    
     642
    628643    $templates[] = "page.php";
    629644
    … …  
    632647
    633648/**
    634  * get_paged_template() - {@internal Missing Short Description}}
    635  *
    636  * {@internal Missing Long Description}}
    637  *
    638  * @since 1.5.0
    639  *
    640  * @return unknown
     649 * Retrieve path of paged template in current or parent template.
     650 *
     651 * @since 1.5.0
     652 *
     653 * @return string
    641654 */
    642655function get_paged_template() {
    … …  
    645658
    646659/**
    647  * get_search_template() - {@internal Missing Short Description}}
    648  *
    649  * {@internal Missing Long Description}}
    650  *
    651  * @since 1.5.0
    652  *
    653  * @return unknown
     660 * Retrieve path of search template in current or parent template.
     661 *
     662 * @since 1.5.0
     663 *
     664 * @return string
    654665 */
    655666function get_search_template() {
    … …  
    658669
    659670/**
    660  * get_single_template() - {@internal Missing Short Description}}
    661  *
    662  * {@internal Missing Long Description}}
     671 * Retrieve path of single template in current or parent template.
    663672 *
    664673 * @since 1.5.0
    … …  
    671680
    672681/**
    673  * get_attachment_template() - {@internal Missing Short Description}}
    674  *
    675  * {@internal Missing Long Description}}
     682 * Retrieve path of attachment template in current or parent template.
     683 *
     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.
     688 *
     689 * Some examples for the 'text/plain' mime type are 'text.php', 'plain.php', and
     690 * finally 'text_plain.php'.
    676691 *
    677692 * @since 2.0.0
    678693 *
    679  * @return unknown
     694 * @return string
    680695 */
    681696function get_attachment_template() {
    … …  
    693708
    694709/**
    695  * get_comments_popup_template() - {@internal Missing Short Description}}
    696  *
    697  * {@internal Missing Long Description}}
    698  *
    699  * @since 1.5.0
    700  *
    701  * @return unknown
     710 * Retrieve path of comment popup template in current or parent template.
     711 *
     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.
     716 *
     717 * @since 1.5.0
     718 * @uses apply_filters() Calls 'comments_popup_template' filter on path.
     719 *
     720 * @return string
    702721 */
    703722function get_comments_popup_template() {
    … …  
    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
    717  *
    718  * @param array $template_names Array of template files to search for in priority order
     735 *
     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.
    … …  
    723743    if (!is_array($template_names))
    724744        return '';
    725    
     745
    726746    $located = '';
    727747    foreach($template_names as $template_name) {
    … …  
    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}}
    745  *
    746  * {@internal Missing Long Description}}
    747  *
    748  * @since 1.5.0
    749  *
    750  * @param unknown_type $_template_file
     764 * Require once the template file with WordPress environment.
     765 *
     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.
     769 *
     770 * @since 1.5.0
     771 *
     772 * @param string $_template_file Path to template file.
    751773 */
    752774function load_template($_template_file) {
    … …  
    760782
    761783/**
    762  * locale_stylesheet() - {@internal Missing Short Description}}
    763  *
    764  * {@internal Missing Long Description}}
     784 * Display localized stylesheet link element.
    765785 *
    766786 * @since 2.1.0
    … …  
    774794
    775795/**
    776  * switch_theme() - {@internal Missing Short Description}}
     796 * {@internal Missing Short Description}}
    777797 *
    778798 * {@internal Missing Long Description}}
    … …  
    839859
    840860/**
    841  * validate_current_theme() - {@internal Missing Short Description}}
    842  *
    843  * {@internal Missing Long Description}}
    844  *
    845  * @since 1.5.0
    846  *
    847  * @return unknown
     861 * Checks that current theme files 'index.php' and 'style.css' exists.
     862 *
     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.
     866 *
     867 * @since 1.5.0
     868 *
     869 * @return bool
    848870 */
    849871function validate_current_theme() {
    … …  
    866888
    867889/**
    868  * get_theme_mod() - {@internal Missing Short Description}}
    869  *
    870  * {@internal Missing Long Description}}
     890 * Retrieve theme modification value for the current theme.
     891 *
     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
    873  *
    874  * @param unknown_type $name
    875  * @param unknown_type $default
    876  * @return unknown
     898 * @uses apply_filters() Calls 'theme_mod_$name' filter on the value.
     899 *
     900 * @param string $name Theme modification name.
     901 * @param bool|string $default
     902 * @return string
    877903 */
    878904function get_theme_mod($name, $default = false) {
    … …  
    888914
    889915/**
    890  * set_theme_mod() - {@internal Missing Short Description}}
    891  *
    892  * {@internal Missing Long Description}}
     916 * Update theme modification value for the current theme.
    893917 *
    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) {
    … …  
    909933
    910934/**
    911  * remove_theme_mod() - {@internal Missing Short Description}}
    912  *
    913  * {@internal Missing Long Description}}
     935 * Remove theme modification name from current theme list.
     936 *
     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 ) {
    … …  
    936961
    937962/**
    938  * remove_theme_mods() - {@internal Missing Short Description}}
    939  *
    940  * {@internal Missing Long Description}}
     963 * Remove theme modifications option for current theme.
    941964 *
    942965 * @since 2.1.0
    … …  
    949972
    950973/**
    951  * get_header_textcolor() - {@internal Missing Short Description}}
    952  *
    953  * {@internal Missing Long Description}}
     974 * Retrieve text color for custom header.
    954975 *
    955976 * @since 2.1.0
    956  *
    957  * @return unknown
     977 * @uses HEADER_TEXTCOLOR
     978 *
     979 * @return string
    958980 */
    959981function get_header_textcolor() {
    … …  
    962984
    963985/**
    964  * header_textcolor() - {@internal Missing Short Description}}
    965  *
    966  * {@internal Missing Long Description}}
     986 * Display text color for custom header.
    967987 *
    968988 * @since 2.1.0
    969  *
    970989 */
    971990function header_textcolor() {
    … …  
    974993
    975994/**
    976  * get_header_image() - {@internal Missing Short Description}}
    977  *
    978  * {@internal Missing Long Description}}
     995 * Retrieve header image for custom header.
    979996 *
    980997 * @since 2.1.0
    981  *
    982  * @return unknown
     998 * @uses HEADER_IMAGE
     999 *
     1000 * @return string
    9831001 */
    9841002function get_header_image() {
    … …  
    9871005
    9881006/**
    989  * header_image() - {@internal Missing Short Description}}
    990  *
    991  * {@internal Missing Long Description}}
     1007 * Display header image path.
    9921008 *
    9931009 * @since 2.1.0
    … …  
    9981014
    9991015/**
    1000  * add_custom_image_header() - {@internal Missing Short Description}}
    1001  *
    1002  * {@internal Missing Long Description}}
     1016 * Add callbacks for image header display.
     1017 *
     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
    1005  *
    1006  * @param unknown_type $header_callback
    1007  * @param unknown_type $admin_header_callback
     1024 * @uses Custom_Image_Header Sets up for $admin_header_callback for administration panel display.
     1025 *
     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) {
Note: See TracChangeset for help on using the changeset viewer.