August 13, 2015

The Tuts+ Guide to Template Tags: Seventh Batch

In the seventh part of the series, we went through the sixth batch of WordPress template tags. In this eighth part, we’re going to go through the seventh batch of the almost 200 template tags. Throughout the tutorial, we’ll see template tags about archives, search and login/logout/register actions.

Getting the Archive Link: get_archives_link()

This template tag returns an archive link with various formats.

Parameters

This template tag accepts five parameters:

  • $url (required—string):
    URL of the archive.
    (Default: NULL)
  • $text (required—string):
    Description of the archive if $format is set to ‘link’.
    (Default: NULL)
  • $format (optional—string):
    Format of the link. Accepts the following styles:

    • ‘link’ creates a <link /> tag.
    • ‘option’ creates an <option> tag so you can use it in an HTML dropdown menu.
    • ‘html’ creates an <a> tag inside a <li> tag so you can use it in an ordered or unordered list.
    • ‘custom’ or any other text creates an <a> tag.

    (Default: ‘html’)

  • $before (optional—string):
    The text or HTML code to display before the output.
    (Default: Empty)
  • $after (optional—string):
    The text or HTML code to display after the output.
    (Default: Empty)

Usage

<?php

// Getting and echoing an archive link as a <link> tag.
echo get_archives_link( 'http://mywebsite.com/archives/something/', __( 'My not-so-secret archives', 'translation-domain' ), 'link' );

// Getting and echoing an archive link with a custom format.
echo get_archives_link( 'http://mywebsite.com/archives/something/', '', 'custom', '<div class="not-so-secret-archives-link">', '</div>' );

?>

Getting & Displaying the Archive Links: wp_get_archives()

This template tag returns or displays a list of archive links in various formats.

Parameters

This template tag accepts only one parameter:

  • $args (optional—array):
    An array of the following arguments:

    • 'type' (string): Type of the archives. Accepts ‘yearly’, ‘monthly’, ‘weekly’, ‘daily’, ‘postbypost’ (ordered by post date) or ‘alpha’ (ordered by post title).
      (Default: ‘monthly’)
    • 'limit' (string): Number of items to retrieve.
      (Default: Empty which means no limit)
    • 'format' (string): One of the following output formats:

      • ‘html’ creates <a> tags inside <li> tags so you can use it in an ordered or unordered list.
      • ‘option’ creates <option> tags so you can use it in an HTML dropdown menu.
      • ‘link’ creates <link /> tags.
      • ‘custom’ creates only <a> tags.

      (Default: ‘html’)

    • 'before' (string): HTML code to add before the output.
      (Default: Empty)
    • 'after' (string): HTML code to add after the output.
      (Default: Empty)
    • 'show_post_count' (boolean): Whether to show post count or not.
      (Default: FALSE)
    • 'echo' (integer): Whether to echo the output (1) or return it (0).
      (Default: 1)
    • 'order' (string): Whether to order items in ascending (‘ASC’) or descending (‘DESC’) order.
      (Default: ‘DESC’)

Usage

<?php

$args = array(
    
    // Get yearly archives.
    'type' => 'yearly',
    
    // No gibberish, we just need plain <a> tags, because...
    'format' => 'custom',
    
    // ...we're going to use the links in a <nav> element
    'before' => '<nav class="yearly-archives">',
    'after' => '</nav>',
    
    // Show post count while we're at it.
    'show_post_count' => true
    
);

wp_get_archives( $args );

?>

Getting & Displaying Title for a Post Type Archive: post_type_archive_title()

This template tag gets and echoes the post type for using as post type archive titles.

Parameters

This template tag accepts two parameters:

  • $prefix (optional—string):
    Prefix to the title.
    (Default: Empty)
  • $echo (optional—boolean):
    Whether echo (TRUE) or return (FALSE) the tag.
    (Default: TRUE)

Usage

<?php

// Getting post type archive title.
$archive_title = post_type_archive_title( '', false );

// Display post type archive title.
post_type_archive_title( '<i class="icon-archive"></i>' );

?>

Getting & Displaying a Page Title for Monthly Archives: single_month_title()

This template tag returns and displays the month’s name for using in page titles.

Parameters

This template tag accepts two parameters:

  • $prefix (optional—string):
    Prefix to the title.
    (Default: Empty)
  • $echo (optional—boolean):
    Whether echo (TRUE) or return (FALSE) the tag.
    (Default: TRUE)

Usage

<?php

// Display the monthly archive title with a prefix.
single_month_title( __( 'Monthly Archives', 'translation-domain' ) . ': ' );

// Get the monthly archive title.
$month_title = single_month_title( '', false );

?>

Getting & Displaying the Link for the "Next Posts" Page: get_next_posts_link() & next_posts_link()

These template tags return or display a "next posts" link for post lists (like blog indexes or archive pages).

Parameters

Both template tags accept two parameters:

  • $label (optional—string):
    Text to display for the link.
    (Default: ‘Next Page &raquo;’)
  • $max_page (optional—integer):
    Maximum page number.
    (Default: 0)

Usage

<?php

// Get the "next posts" link with default values.
$next_comments_link = get_next_posts_link();

// Display the "next posts" link with a different label, using a right arrow.
next_posts_link( '&#8594;' );

?>

Getting & Displaying the Link for the "Previous Posts" Page: get_previous_posts_link() & previous_posts_link()

These template tags return or display a "previous posts" link for post lists (like blog indexes or archive pages).

Parameters

Both template tags accept only one parameter:

  • $label (optional—string):
    Text to display for the link.
    (Default: ‘&laquo; Previous Page’)

Usage

<?php

// Get the "previous posts" link with default values.
$previous_comments_link = get_previous_posts_link();

// Display the "previous posts" link with a different label, using a left arrow.
previous_posts_link( '&#8592;' );

?>

Getting & Displaying Links for the "Next & Previous Posts" Pages: get_posts_nav_link() & posts_nav_link()

These template tags let you use navigational "next & previous posts" links.

Parameters

get_posts_nav_link() accepts only one parameter:

  • $args (optional—array):
    An array of the following arguments:

    • 'sep' (string): Separator text
      (Default: ‘ &#8212; ‘)
    • 'prelabel' (string): Label for the "previous page" link.
      (Default: ‘&laquo; Previous Page’)
    • 'nxtlabel' (string): Label for the "next page" link.
      (Default: ‘Next Page &raquo;’)

And posts_nav_link() accepts three parameters:

  • $sep (optional—string):
    Separator text.
    (Default: Emtpy)
  • $prelabel (optional—string):
    Label for the link of the previous page.
    (Default: "&laquo; Previous Page")
  • $nxtlabel (optional—string):
    Label for the link of the next page.
    (Default: "Next Page &raquo;")

Usage

<?php

// Get posts navigation.
$args = array(
    'sep' => ' &middot; ',
    'prelabel' => '&laquo;',
    'nxtlabel' => '&raquo;'
);

$posts_nav = get_posts_nav_link( $args );

// Display posts navigation.
posts_nav_link( ' - ', __( 'Previous', 'translation-domain' ), __( 'Next', 'translation-domain' ) );

?>

Getting & Displaying the Search Form: get_search_form()

This template tag returns or displays the classic search form.

Parameters

This template tag accepts only one parameter:

  • $echo (optional—boolean):
    Whether to echo (TRUE) or return (FALSE) the output.
    (Default: TRUE)

Usage

<?php

// Returns the search form.
$search_form = get_search_form( false );

// Echoes the search form.
get_search_form();

?>

Getting & Displaying Current Search Query: get_search_query() & the_search_query()

These template tags return or display the queried search terms.

Parameters

the_search_query() doesn’t accept any parameters, but get_search_query() accepts one parameter:

  • $escaped (optional—boolean):
    Whether the result is escaped or not. It should stay TRUE unless you’re going to escape the query later.
    (Default: TRUE)

Usage

<?php

// These guys don't need explanations, so why am I still writing?
get_search_query();
the_search_query();

?>

Getting a Permalink for a Search Query: get_search_link()

This template tag generates a search URL with the given search terms.

Parameters

This template tag accepts only one parameter:

  • $query (optional—string):
    Search terms to build the query.
    (Default: Current search query)

Usage

<?php

echo '<a href="' . get_search_link( __( 'the meaning of life', 'translation-domain' ) ) . '">' . __( 'Find the meaning of life on this website!', 'translation-domain' ) . '</a>';

?>

Getting & Displaying a "Register" or a "Dashboard" Link: wp_register()

This template tag returns or echoes a "Register" link to visitors and a "Dashboard" link for users.

Parameters

This template tag accepts three parameters:

  • $before (optional—string):
    The text or HTML code to display before the output.
    (Default: ‘<li>’)
  • $after (optional—string):
    The text or HTML code to display after the output.
    (Default: ‘</li>’)
  • $echo (optional—boolean):
    Whether echo (TRUE) or return (FALSE) the tag.
    (Default: TRUE)

Usage

<?php

// Custom before & after content.
wp_register( '<div class="register-dashboard">', '</div>' );

// Remove before & after content and return the output.
$register_or_dashboard_link = wp_register( '', '', false );

?>

Getting & Displaying the "Log In" Form: wp_login_form()

This template tag returns or echoes a login form. Might be useful for themes and plugins to let users log in from the front-end.

Parameters

This template tag accepts only one parameter:

  • $args (optional—array):
    An array of the following arguments:

    • 'echo' (boolean): Whether to echo the template tag or not.
      (Default: TRUE)
    • 'redirect' (string): Where to redirect after a successful login.
      (Default: Back to the current page)
    • 'form_id' (string): ID of the login form’s <form> tag.
      (Default: ‘loginform’)
    • 'label_username' (string): Label of the "username" input field.
      (Default: ‘Username’)
    • 'label_password' (string): Label of the "password" input field.
      (Default: ‘Password’)
    • 'label_remember' (string): Label of the "remember me" checkbox.
      (Default: ‘Remember Me’)
    • 'label_log_in' (string): Label of the submit button.
      (Default: ‘Log In’)
    • 'id_username' (string): ID of the "username" input field.
      (Default: ‘user_login’)
    • 'id_password' (string): ID of the "password" input field.
      (Default: user_pass’)
    • 'id_remember' (string): ID of the "remember me" checkbox.
      (Default: ‘rememberme’)
    • 'id_submit' (string): ID of the submit button.
      (Default: ‘wp-submit’)
    • 'remember' (boolean): Whether to show the "remember me" checkbox or not.
      (Default: TRUE)
    • 'value_username' (string): A default value for the "username" field.
      (Default: Empty)
    • 'value_remember' (boolean): Whether to check the "remember me" checkbox or not.
      (Default: FALSE)

Usage

<?php

$args = array(
    
    // Redirect to a "welcome" page after login.
    'redirect'    => get_permalink( 8 ),
    
    // Custom form & input ids.
    'form_id'     => 'mytheme-login-form',
    'id_username' => 'mytheme-login-form-username',
    'id_password' => 'mytheme-login-form-password',
    'id_remember' => 'mytheme-login-form-remember',
    'id_submit'   => 'mytheme-login-form-submit',
    
);

wp_login_form( $args );

?>

Getting & Displaying the "Log In/Out" Link: wp_loginout()

This template tag returns or displays a "log in" link for visitors and a "log out" link for logged in users.

Parameters

This template tag accepts two parameters:

  • $redirect (optional—string):
    URL to redirect user to on login or logout.
    (Default: Empty)
  • $echo (optional—boolean):
    Whether echo (TRUE) or return (FALSE) the tag.
    (Default: TRUE)

Usage

<?php

// Get the login / logout link.
$login_logout_link = wp_loginout( '', false );

?>

Getting the "Log In" URL: wp_login_url()

This template tag simply returns a "log in" link for users.

Parameters

This template tag accepts two parameters:

  • $redirect (optional—string):
    URL to redirect user to when logged in.
    (Default: Empty)
  • $force_reauth (optional—boolean):
    Force users to log in even if they have a cookie.
    (Default: FALSE)

Usage

<?php

// Redirect users to a "welcome" page after login.
echo wp_login_url( get_permalink( 8 ) );

?>

Getting the "Log Out" URL: wp_logout_url()

This template tag returns a "log out" link.

Parameters

This template tag accepts only one parameter:

  • $redirect (optional—string):
    URL to redirect user to when logged out.
    (Default: Empty)

Usage

<?php

// Redirect to a "goodbye" page.
echo wp_logout_url( get_permalink( 9 ) );

?>

Getting the "Lost Password" URL: wp_lostpassword_url()

This template tag returns a "lost password" link for users to, well, retrieve their lost passwords.

Parameters

This template tag accepts only one parameter:

  • $redirect (optional—string):
    URL to redirect user to.
    (Default: Empty)

Usage

<?php

// Redirect users to a "password tips" page after login.
echo wp_lostpassword_url( get_permalink( 10 ) );

?>

Conclusion

Hope you liked this seventh batch of template tags. There’s only one more batch to go, so stay tuned for more template tags!

If you have any questions, comments or corrections, you can share your thoughts with us in the Comments section. And if you liked the article, don’t forget to share it with your friends!

Pallavi Gupta

Wordpress | BuddyPress | WooCommerce Developer : I have developed a wide range of websites using Wordpress, PHP, HTML, CSS, jQuery and MySQL.