root/trunk/wp-includes/general-template.php

<?php
/**
 * General template tags that can go anywhere in a template.
 *
 * @package WordPress
 * @subpackage Template
 */

/**
 * Load header template.
 *
 * Includes the header template for a theme or if a name is specified then a
 * specialised header will be included. If the theme contains no header.php file
 * then the header from the default theme will be included.
 *
 * For the parameter, if the file is called "header-special.php" then specify
 * "special".
 *
 * @uses locate_template()
 * @since 1.5.0
 * @uses do_action() Calls 'get_header' action.
 *
 * @param string $name The name of the specialised header.
 */
function get_header( $name = null ) {
    do_action( 'get_header' );

    $templates = array();
    if ( isset($name) )
        $templates[] = "header-{$name}.php";

    $templates[] = "header.php";

    if ('' == locate_template($templates, true))
        load_template( get_theme_root() . '/default/header.php');
}

/**
 * Load footer template.
 *
 * Includes the footer template for a theme or if a name is specified then a
 * specialised footer will be included. If the theme contains no footer.php file
 * then the footer from the default theme will be included.
 *
 * For the parameter, if the file is called "footer-special.php" then specify
 * "special".
 *
 * @uses locate_template()
 * @since 1.5.0
 * @uses do_action() Calls 'get_footer' action.
 *
 * @param string $name The name of the specialised footer.
 */
function get_footer( $name = null ) {
    do_action( 'get_footer' );

    $templates = array();
    if ( isset($name) )
        $templates[] = "footer-{$name}.php";

    $templates[] = "footer.php";

    if ('' == locate_template($templates, true))
        load_template( get_theme_root() . '/default/footer.php');
}

/**
 * Load sidebar template.
 *
 * Includes the sidebar template for a theme or if a name is specified then a
 * specialised sidebar will be included. If the theme contains no sidebar.php
 * file then the sidebar from the default theme will be included.
 *
 * For the parameter, if the file is called "sidebar-special.php" then specify
 * "special".
 *
 * @uses locate_template()
 * @since 1.5.0
 * @uses do_action() Calls 'get_sidebar' action.
 *
 * @param string $name The name of the specialised sidebar.
 */
function get_sidebar( $name = null ) {
    do_action( 'get_sidebar' );

    $templates = array();
    if ( isset($name) )
        $templates[] = "sidebar-{$name}.php";

    $templates[] = "sidebar.php";

    if ('' == locate_template($templates, true))
        load_template( get_theme_root() . '/default/sidebar.php');
}

/**
 * Display search form.
 *
 * Will first attempt to locate the searchform.php file in either the child or
 * the parent, then load it. If it doesn't exist, then the default search form
 * will be displayed.
 *
 * @since 2.7.0
 */
function get_search_form() {
    do_action( 'get_search_form' );

    if ( '' != locate_template(array('searchform.php'), true) )
        return;

    $form = '<form method="get" id="searchform" action="' . get_option('siteurl') . '/" >
    <label class="hidden" for="s">' . __('Search for:') . '</label>
    <div><input type="text" value="' . the_search_query() . '" name="s" id="s" />
    <input type="submit" id="searchsubmit" value="Search" />
    </div>
    </form>';

    echo apply_filters('get_search_form', $form);
}

/**
 * Display the Log In/Out link.
 *
 * Displays a link, which allows the user to navigate to the Log In page to log in
 * or log out depending on whether or not they are currently logged in.
 *
 * @since 1.5.0
 * @uses apply_filters() Calls 'loginout' hook on HTML link content.
 */
function wp_loginout() {
    if ( ! is_user_logged_in() )
        $link = '<a href="' . wp_login_url() . '">' . __('Log in') . '</a>';
    else
        $link = '<a href="' . wp_logout_url() . '">' . __('Log out') . '</a>';

    echo apply_filters('loginout', $link);
}

/**
 * Returns the Log Out URL.
 *
 * Returns the URL that allows the user to log out of the site
 *
 * @since 2.7
 * @uses wp_nonce_url() To protect against CSRF
 * @uses site_url() To generate the log in URL
 * 
 * @param string $redirect Path to redirect to on logout.
 */
function wp_logout_url($redirect = '') {
    if ( strlen($redirect) )
        $redirect = "&redirect_to=$redirect";
    
    return wp_nonce_url( site_url("wp-login.php?action=logout$redirect", 'login'), 'log-out' );
}

/**
 * Returns the Log In URL.
 *
 * Returns the URL that allows the user to log in to the site
 *
 * @since 2.7
 * @uses site_url() To generate the log in URL
 * 
 * @param string $redirect Path to redirect to on login.
 */
function wp_login_url($redirect = '') {
    if ( strlen($redirect) )
        $redirect = "?redirect_to=$redirect";
    
    return site_url("wp-login.php$redirect", 'login');
}

/**
 * Display the Registration or Admin link.
 *
 * Display a link which allows the user to navigate to the registration page if
 * not logged in and registration is enabled or to the dashboard if logged in.
 * 
 * @since 1.5.0
 * @uses apply_filters() Calls 'register' hook on register / admin link content.
 *
 * @param string $before Text to output before the link (defaults to <li>).
 * @param string $after Text to output after the link (defaults to </li>).
 */
function wp_register( $before = '<li>', $after = '</li>' ) {

    if ( ! is_user_logged_in() ) {
        if ( get_option('users_can_register') )
            $link = $before . '<a href="' . site_url('wp-login.php?action=register', 'login') . '">' . __('Register') . '</a>' . $after;
        else
            $link = '';
    } else {
        $link = $before . '<a href="' . admin_url() . '">' . __('Site Admin') . '</a>' . $after;
    }

    echo apply_filters('register', $link);
}

/**
 * Theme container function for the 'wp_meta' action.
 *
 * The 'wp_meta' action can have several purposes, depending on how you use it,
 * but one purpose might have been to allow for theme switching.
 *
 * @since 1.5.0
 * @link http://trac.wordpress.org/ticket/1458 Explanation of 'wp_meta' action.
 * @uses do_action() Calls 'wp_meta' hook.
 */
function wp_meta() {
    do_action('wp_meta');
}

/**
 * Display information about the blog.
 *
 * @see get_bloginfo() For possible values for the parameter.
 * @since 0.71
 *
 * @param string $show What to display.
 */
function bloginfo($show='') {
    echo get_bloginfo($show, 'display');
}

/**
 * Retrieve information about the blog.
 *
 * Some show parameter values are deprecated and will be removed in future
 * versions. Care should be taken to check the function contents and know what
 * the deprecated blog info options are. Options without "// DEPRECATED" are
 * the preferred and recommended ways to get the information.
 *
 * The possible values for the 'show' parameter are listed below.
 * <ol>
 * <li><strong>url<strong> - Blog URI to homepage.</li>
 * <li><strong>wpurl</strong> - Blog URI path to WordPress.</li>
 * <li><strong>description</strong> - Secondary title</li>
 * </ol>
 *
 * The feed URL options can be retrieved from 'rdf_url' (RSS 0.91),
 * 'rss_url' (RSS 1.0), 'rss2_url' (RSS 2.0), or 'atom_url' (Atom feed). The
 * comment feeds can be retrieved from the 'comments_atom_url' (Atom comment
 * feed) or 'comments_rss2_url' (RSS 2.0 comment feed).
 *
 * There are many other options and you should check the function contents:
 * {@source 32 37}
 *
 * @since 0.71
 *
 * @param string $show Blog info to retrieve.
 * @param string $filter How to filter what is retrieved.
 * @return string Mostly string values, might be empty.
 */
function get_bloginfo($show = '', $filter = 'raw') {

    switch($show) {
        case 'url' :
        case 'home' : // DEPRECATED
        case 'siteurl' : // DEPRECATED
            $output = get_option('home');
            break;
        case 'wpurl' :
            $output = get_option('siteurl');
            break;
        case 'description':
            $output = get_option('blogdescription');
            break;
        case 'rdf_url':
            $output = get_feed_link('rdf');
            break;
        case 'rss_url':
            $output = get_feed_link('rss');
            break;
        case 'rss2_url':
            $output = get_feed_link('rss2');
            break;
        case 'atom_url':
            $output = get_feed_link('atom');
            break;
        case 'comments_atom_url':
            $output = get_feed_link('comments_atom');
            break;
        case 'comments_rss2_url':
            $output = get_feed_link('comments_rss2');
            break;
        case 'pingback_url':
            $output = get_option('siteurl') .'/xmlrpc.php';
            break;
        case 'stylesheet_url':
            $output = get_stylesheet_uri();
            break;
        case 'stylesheet_directory':
            $output = get_stylesheet_directory_uri();
            break;
        case 'template_directory':
        case 'template_url':
            $output = get_template_directory_uri();
            break;
        case 'admin_email':
            $output = get_option('admin_email');
            break;
        case 'charset':
            $output = get_option('blog_charset');
            if ('' == $output) $output = 'UTF-8';
            break;
        case 'html_type' :
            $output = get_option('html_type');
            break;
        case 'version':
            global $wp_version;
            $output = $wp_version;
            break;
        case 'language':
            $output = get_locale();
            $output = str_replace('_', '-', $output);
            break;
        case 'text_direction':
            global $wp_locale;
            $output = $wp_locale->text_direction;
            break;
        case 'name':
        default:
            $output = get_option('blogname');
            break;
    }

    $url = true;
    if (strpos($show, 'url') === false &&
        strpos($show, 'directory') === false &&
        strpos($show, 'home') === false)
        $url = false;

    if ( 'display' == $filter ) {
        if ( $url )
            $output = apply_filters('bloginfo_url', $output, $show);
        else
            $output = apply_filters('bloginfo', $output, $show);
    }

    return $output;
}

/**
 * Display or retrieve page title for all areas of blog.
 *
 * 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 string $sep Optional, default is '&raquo;'. 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 = '&raquo;', $display = true, $seplocation = '') {
    global $wpdb, $wp_locale, $wp_query;

    $cat = get_query_var('cat');
    $tag = get_query_var('tag_id');
    $category_name = get_query_var('category_name');
    $author = get_query_var('author');
    $author_name = get_query_var('author_name');
    $m = get_query_var('m');
    $year = get_query_var('year');
    $monthnum = get_query_var('monthnum');
    $day = get_query_var('day');
    $title = '';

    $t_sep = '%WP_TITILE_SEP%'; // Temporary separator, for accurate flipping, if necessary

    // If there's a category
    if ( !empty($cat) ) {
            // category exclusion
            if ( !stristr($cat,'-') )
                $title = apply_filters('single_cat_title', get_the_category_by_ID($cat));
    } elseif ( !empty($category_name) ) {
        if ( stristr($category_name,'/') ) {
                $category_name = explode('/',$category_name);
                if ( $category_name[count($category_name)-1] )
                    $category_name = $category_name[count($category_name)-1]; // no trailing slash
                else
                    $category_name = $category_name[count($category_name)-2]; // there was a trailling slash
        }
        $cat = get_term_by('slug', $category_name, 'category', OBJECT, 'display');
        if ( $cat )
            $title = apply_filters('single_cat_title', $cat->name);
    }

    if ( !empty($tag) ) {
        $tag = get_term($tag, 'post_tag', OBJECT, 'display');
        if ( is_wp_error( $tag ) )
            return $tag;
        if ( ! empty($tag->name) )
            $title = apply_filters('single_tag_title', $tag->name);
    }

    // If there's an author
    if ( !empty($author) ) {
        $title = get_userdata($author);
        $title = $title->display_name;
    }
    if ( !empty($author_name) ) {
        // We do a direct query here because we don't cache by nicename.
        $title = $wpdb->get_var($wpdb->prepare("SELECT display_name FROM $wpdb->users WHERE user_nicename = %s", $author_name));
    }

    // If there's a month
    if ( !empty($m) ) {
        $my_year = substr($m, 0, 4);
        $my_month = $wp_locale->get_month(substr($m, 4, 2));
        $my_day = intval(substr($m, 6, 2));
        $title = "$my_year" . ($my_month ? "$t_sep$my_month" : "") . ($my_day ? "$t_sep$my_day" : "");
    }

    if ( !empty($year) ) {
        $title = $year;
        if ( !empty($monthnum) )
            $title .= "$t_sep" . $wp_locale->get_month($monthnum);
        if ( !empty($day) )
            $title .= "$t_sep" . zeroise($day, 2);
    }

    // If there is a post
    if ( is_single() ||  ( is_page() && !is_front_page() ) ) {
        $post = $wp_query->get_queried_object();
        $title = strip_tags( apply_filters( 'single_post_title', $post->post_title ) );
    }

    // If there's a taxonomy
    if ( is_tax() ) {
        $taxonomy = get_query_var( 'taxonomy' );
        $tax = get_taxonomy( $taxonomy );
        $tax = $tax->label;
        $term = $wp_query->get_queried_object();
        $term = $term->name;
        $title = "$tax$t_sep$term";
    }

    if ( is_404() ) {
        $title = __('Page not found');    
    }
    
    $prefix = '';
    if ( !empty($title) )
        $prefix = " $sep ";

     // Determines position of the separator and direction of the breadcrumb
    if ( 'right' == $seplocation ) { // sep on right, so reverse the order
        $title_array = explode( $t_sep, $title );
        $title_array = array_reverse( $title_array );
        $title = implode( " $sep ", $title_array ) . $prefix;
    } else {
        $title_array = explode( $t_sep, $title );
        $title = $prefix . implode( " $sep ", $title_array );
    }

    $title = apply_filters('wp_title', $title, $sep, $seplocation);

    // Send it out
    if ( $display )
        echo $title;
    else
        return $title;

}

/**
 * Display or retrieve page title for post.
 *
 * 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 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;
    $p = get_query_var('p');
    $name = get_query_var('name');

    if ( intval($p) || '' != $name ) {
        if ( !$p )
            $p = $wpdb->get_var($wpdb->prepare("SELECT ID FROM $wpdb->posts WHERE post_name = %s", $name));
        $post = & get_post($p);
        $title = $post->post_title;
        $title = apply_filters('single_post_title', $title);
        if ( $display )
            echo $prefix.strip_tags($title);
        else
            return strip_tags($title);
    }
}

/**
 * Display or retrieve page title for category archive.
 *
 * 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 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') );
    if ( !empty($cat) && !(strtoupper($cat) == 'ALL') ) {
        $my_cat_name = apply_filters('single_cat_title', get_the_category_by_ID($cat));
        if ( !empty($my_cat_name) ) {
            if ( $display )
                echo $prefix.strip_tags($my_cat_name);
            else
                return strip_tags($my_cat_name);
        }
    } else if ( is_tag() ) {
        return single_tag_title($prefix, $display);
    }
}

/**
 * Display or retrieve page title for tag post archive.
 *
 * 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 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() )
        return;

    $tag_id = intval( get_query_var('tag_id') );

    if ( !empty($tag_id) ) {
        $my_tag = &get_term($tag_id, 'post_tag', OBJECT, 'display');
        if ( is_wp_error( $my_tag ) )
            return false;
        $my_tag_name = apply_filters('single_tag_title', $my_tag->name);
        if ( !empty($my_tag_name) ) {
            if ( $display )
                echo $prefix . $my_tag_name;
            else
                return $my_tag_name;
        }
    }
}

/**
 * Display or retrieve page title for post archive based on date.
 *
 * 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 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;

    $m = get_query_var('m');
    $year = get_query_var('year');
<