The Tuts+ Guide to Template Tags: Eighth Batch

In the eighth part of the series, we went through the seventh batch of WordPress template tags. In this ninth part, we're going to go through the last batch of the almost 200 template tags. Throughout the tutorial, we'll see template tags about bookmarks, and other, "miscellaneous" template tags.

Warning about bookmarks: As of WordPress 3.5, "bookmarks" are hidden from the admin panel by default. To work with bookmarks, you need to install the Link Manager plugin.

Getting & Displaying a List of Bookmarks: wp_list_bookmarks()

This template tag returns or echoes a list of bookmarks, an old feature of WordPress.

Parameters

This template tag accepts only one parameter:

• $args (optional—array):
  An array of the following arguments:
  • 'orderby' (string): How to order the bookmarks. Accepts 'name', 'link_id', 'url', 'target', 'description', 'owner' (the user who added the bookmark), 'rating', 'updated' (update dates), 'rel' (XFN bookmark relationship), 'notes', 'rss', 'length' (length of bookmark's name), 'rand' (random).
    (Default: 'name')
  • 'order' (string): Whether to order items in ascending ('ASC') or descending ('DESC') order.
    (Default: 'ASC')
  • 'limit' (integer): Number of items to display.
    (Default: -1 which means all bookmarks)
  • 'category' (string): Comma-separated category IDs to get items from.
    (Default: ' ' which means all categories)
  • 'exclude_category' (string): Bookmark categories' IDs to exclude.
    (Default: ' ')
  • 'category_name' (string): A category name to show bookmarks from (overrides 'category').
    (Default: ' ')
  • 'hide_invisible' (integer): Whether to hide invisible links or show them.
    (Default: 1)
  • 'show_updated' (integer): Whether the last updated timestamp should be displayed or not.
    (Default: 0)
  • 'echo' (integer): Whether to echo the output (1) or return it (0).
    (Default: 1)
  • 'categorize' (integer): Whether to group bookmarks by their categories (1) or not (0).
    (Default: 1)
  • 'title_li' (string): Wraps the output with a <li> tag and displays a title before the bookmark list. You would probably want to set this to an empty string and disable wrapping.
    (Default: 'Bookmarks')
  • 'title_before' (string): HTML code to add before each title.
    (Default: '<h2>')
  • 'title_after' (string): HTML code to add after each title.
    (Default: '</h2>')
  • 'class' (string): CSS class names to add to each category.
    (Default: 'linkcat')
  • 'category_before' (string): HTML code to add before each category.
    (Default: '<li id=%id class=%class>')
  • 'category_after' (string): HTML code to add after each category.
    (Default: '</li>')
  • 'category_orderby' (string): How to order the categories. Accepts 'name', 'id', 'slug', and 'count'.
    (Default: 'name')
  • 'category_order' (string): Whether to order categories in ascending ('ASC') or descending ('DESC') order.
    (Default: 'ASC')

Usage

<?php

$args = array(
    
    // Random order.
    'orderby' => 'rand',
    
    // Take just 5 bookmarks.
    'limit' => 5,
    
    // Take bookmarks from a specific category.
    'category_name' => 'Friends',
    
    // Don't echo.
    'echo' => 0,
    
    // Custom class.
    'class' => 'friends-bookmark-list'
    
);

$bookmarks_list = wp_list_bookmarks( $args );

?>

Getting an Array of All Bookmarks: get_bookmarks()

This template tag returns an array of your WordPress bookmarks.

Parameters

This template tag accepts only one parameter:

• $args (optional—array):
  An array of the following arguments:
  • 'orderby' (string): How to order the links. Accepts post fields like 'name', 'ID', 'title', 'date' etc.
    (Default: 'name')
  • 'order' (string): Whether to order items in ascending ('ASC') or descending ('DESC') order.
    (Default: 'ASC')
  • 'limit' (integer): Number of items to display.
    (Default: -1 which means all)
  • 'category' (string): Comma-separated category IDs to get items from.
    (Default: Empty)
  • 'category_name' (string): Category name to get items from.
    (Default: Empty)
  • 'hide_invisible' (integer or boolean): Whether to show or hide linked marked as "invisible".
    (Default: 1|TRUE)
  • 'show_updated' (integer or boolean): Whether to display the time the bookmark was last updated.
    (Default: 0|FALSE)
  • 'include' (string): Comma-separated list of IDs to include.
    (Default: Empty)
  • 'exclude' (string): Comma-separated list of IDs to exclude.
    (Default: Empty)

Usage

<?php

$args = array(
    'orderby' => 'title',
    'order' => 'ASC',
    'limit' => 15,
    'hide_invisible' => false,
    'exclude' => '12,16,23'
);

$bookmarks_array =  get_bookmarks( $args );

?>

Getting Bookmark Data: get_bookmark()

This template tag returns all the data of a given bookmark.

Parameters

This template tag accepts three parameters:

• $bookmark (required—mixed):
  The bookmark ID or object.
  (Default: NULL)
• $output (optional—string):
  Either OBJECT, ARRAY_N, or ARRAY_A constant.
  (Default: OBJECT)
• $filter (optional—string):
  Whether to escape the output or not. If you want to filter the output, set this to 'display'.
  (Default: 'raw')

Usage

<?php

// Getting a specific bookmark's fields with escaping the output.
$bookmark_data( 19, OBJECT, 'display' );

?>

Getting a Single Bookmark Field's Data: get_bookmark_field()

This template tag lets you fetch the data of a single bookmark's field.

Parameters

This template tag accepts three parameters:

• $field (required—string):
  The name of the field.
  (Default: NULL)
• $bookmark (required—integer):
  The bookmark ID.
  (Default: NULL)
• $context (optional—string):
  How to filter the field value—either 'raw', 'edit', 'attribute', 'js', 'db', or 'display'.
  (Default: 'display')

Usage

<?php

// Get the bookmark with the id 16 and escape & echo its title.
echo get_bookmark_field( 'title', 16, 'display' );

?>

Getting & Displaying the "Edit Bookmark" Link: get_edit_bookmark_link() & edit_bookmark_link()

These template tags let you get or echo an "edit this bookmark" link to use in your templates.

Parameters

get_edit_bookmark_link() accepts only one parameter:

• $bookmark_id (required—integer):
  The ID of the bookmark.
  (Default: 0)

And edit_bookmark_link() accepts four parameters:

• $text (optional—string):
  Text to display the link.
  (Default: 'Edit This')
• $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)
• $bookmark_id (required—integer):
  The ID of the bookmark.
  (Default: NULL)

Usage

<?php

// Retrieve the current bookmark's "edit bookmark" link.
$edit_bookmark_link = get_edit_bookmark_link();

// Retrieve a specific bookmark's "edit bookmark" link.
$edit_bookmark_link = get_edit_bookmark_link( 98 );

// Display the current bookmark's "edit bookmark" link.
edit_bookmark_link( __( 'Edit', 'translation-domain' ), '<strong>', '</strong>' );

// Display a specific bookmark's "edit bookmark" link.
edit_bookmark_link( __( 'Edit', 'translation-domain' ), '', '', 98 );

?>

Getting & Displaying Your Site's Information: get_bloginfo() & bloginfo()

These extremely popular template tags return and display your site's general information.

Parameters

get_ bloginfo() accepts two parameters:

• $show (optional—string):
  The bit of information to fetch. One of the following values:
  • 'url' (string): The home URL.
  • 'wpurl' (string): The URL where WordPress is installed.
  • 'description' (string): Site description.
  • 'rdf_url' (string): The RDF/RSS 1.0 feed URL.
  • 'rss_url' (string): The RSS 0.92 feed URL.
  • 'rss2_url' (string): The RSS 2.0 feed URL.
  • 'atom_url' (string): The Atom feed URL.
  • 'comments_rss2_url' (string): The RSS 2.0 feed URL for comments.
  • 'comments_atom_url' (string): The Atom feed URL for comments.
  • 'pingback_url' (string): The URL of the pingback XML-RPC file.
  • 'stylesheet_url' (string): The URL of the theme's main CSS file.
  • 'stylesheet_directory' (string): The URL of the theme's main CSS file's directory.
  • 'template_directory' or 'template_url' (string): The URL of the active theme's directory.
  • 'admin_email' (string): The email address entered when WordPress was installed.
  • 'charset' (string): Site's character set.
  • 'html_type' (string): The Content-Type of WordPress HTML pages.
  • 'version' (string): WordPress version.
  • 'language' (string): Language of the WordPress installation.
  • 'text_direction' (string): Text direction of the language.
  • 'name' (string): Site name.
  (Default: 'name')
• $filter (optional—string):
  Set it to 'filter' to filter the URL returned from this template tag.
  (Default: 'raw')

And bloginfo() accepts only one parameter:

• $show (optional—string):
  Same details as above.
  (Default: 'blogname')

Usage

<?php

// Display the name of the site.
bloginfo();

// Get the stylesheet url.
$stylesheet = get_bloginfo( 'stylesheet_url' );

// Display the WordPress version.
bloginfo( 'version' );

?>

Getting & Displaying Automatic <body> Classes: get_body_class() & body_class()

These very popular template tags generate semantic classes and lets us echo or return them. They also let us add additional class names.

Parameters

Both template tags accept only one parameter:

• $class (optional—string or array):
  Extra CSS class names to add.
  (Default: Empty)

Usage

<?php

// Display the body class.
body_class();

// Retrieve the body class with an extra class.
$body_class = get_body_class( 'mytheme-body' );

?>

Getting & Displaying a Navigation Menu: wp_nav_menu()

This template tag returns or displays navigational menus, a core feature of WordPress. You can see this template tag in—probably—all new WordPress themes released in 2013 or later.

Parameters

This template tag accepts only one parameter:

• $args (optional—array):
  An array of the following arguments:
  • 'menu' (string): The ID, slug or name of the menu.
    (Default: Empty)
  • 'menu_class' (string): CSS class of the UL element of the menu.
    (Default: 'menu')
  • 'menu_id' (string): The ID of the UL element of the menu.
    (Default: menu slug, incremented)
  • 'container' (string): Whether to wrap the UL, and what to wrap it with.
    (Default: DIV)
  • 'container_class' (string): CSS class of the wrapper element.
    (Default: 'menu-{menu slug}-container')
  • 'container_id' (string): The ID of the wrapper element.
    (Default: Empty)
  • 'fallback_cb' (callback or boolean): Name of a fallback function to run if the menu doesn't exist. Set to false for no fallback.
    (Default: 'wp_page_menu')
  • 'before' (string): Text before the link text.
    (Default: Empty)
  • 'after' (string): Text after the link text.
    (Default: Empty)
  • 'link_before' (string): Text before the link.
    (Default: Empty)
  • 'link_after' (string): Text after the link.
    (Default: Empty)
  • 'echo' (boolean): Whether to echo the template tag or not.
    (Default: TRUE)
  • 'depth' (integer): How many levels of the hierarchy are to be included.
    (Default: 0, which means all levels)
  • 'walker' (object): Instance of a custom walker class.
    (Default: Empty)
  • 'theme_location' (string): Theme location to be used. Must be registered with register_nav_menu() in order to be selectable by the user.
    (Default: Empty)
  • 'items_wrap' (string): How the list items should be wrapped.
    (Default: <ul id="%1$s" class="%2$s">%3$s</ul>)

Usage

<?php

$args = array(
    'container_id' => 'primary-nav',
    'link_before' => '<i class="icon-link"></i>',
    'theme_location' => 'primary'
);

wp_nav_menu( $args );

?>

Getting & Displaying Page Titles: wp_title()

This template tag returns or echoes the page title of your pages.

Parameters

This template tag accepts three parameters:

• $sep (optional—string):
  The text to be used as a separator.
  (Default: '&raquo;')
• $echo (optional—boolean):
  Whether to echo (TRUE) or return (FALSE) the tag.
  (Default: TRUE)
• $seplocation (optional—string):
  Position of the separator and direction of the breadcrumb. Set it to 'right' to reverse the breadcrumb.
  (Default: Empty)

Usage

<?php

wp_title( ' - ', true );

// Reverse the separator location to use left-hand indicators.
$page_title = wp_title( ' &laquo ', false, 'right' );

?>

Getting & Displaying the Home URL: get_home_url() & home_url()

These template tags simply return the home URL.

Parameters

get_home_url() accepts three parameters:

• $blog_id (optional—integer):
  The ID of the blog.
  (Default: NULL)
• $path (optional—string):
  Optional path to append to the URL.
  (Default: Empty)
• $scheme (optional—string):
  Scheme to give the home url context ('http', 'https', or 'relative').
  (Default: NULL)

And home_url() accepts two parameters:

• $path (optional—string):
  Optional path to append to the URL.
  (Default: Empty)
• $scheme (optional—string):
  Scheme to give the home url context ('http', 'https', or 'relative').
  (Default: NULL)

Don't mistake these two functions as "one returns the output and the other displays it"—I know I did. The difference is a little weird: While the get_home_url() function returns a specific blog's home URL, the home_url() function returns the home URL of the current site. Remember: Neither of them echoes anything!

Usage

<?php

// Getting a specific blog's home url with https.
$home_url_of_petes_blog = get_home_url( 2, '', 'https' );

// Echoes the current home url with a little addition.
echo home_url( '?rel=navlink' );

?>

Getting & Displaying the Site URL: get_site_url() & site_url()

These template tags get and echo the "site URL", the address where WordPress is installed.

Parameters

get_site_url() accepts three parameters:

• $blog_id (optional—integer):
  The ID of the blog.
  (Default: Current site)
• $path (optional—string):
  Optional path to append to the URL.
  (Default: Empty)
• $scheme (optional—string):
  Scheme to give the home url context ('http', 'https', or 'relative').
  (Default: Normal or secure connection, depending on is_ssl())

And site_url() accepts two parameters:

• $path (optional—string):
  Optional path to append to the URL.
  (Default: Empty)
• $scheme (optional—string):
  Scheme to give the home url context ('http', 'https', or 'relative').
  (Default: Normal or secure connection, depending on is_ssl())

As with home_url() and get_home_url(), don't mistake these two functions as "one returns the output and the other displays it". While the get_site_url() function returns a specific blog's site URL, the site_url() function returns the site URL of the current site. Remember: Neither of them echoes anything!

Usage

<?php

// Getting a specific blog's site url with https.
$site_url_of_janes_blog = get_site_url( 3, '', 'https' );

// Echoes the current site url.
echo site_url();

?>

Getting Current Site's ID: get_current_blog_id()

This template tag simply returns the current site's ID in a Multisite network.

Parameters

This template tag doesn't accept any parameters.

Usage

<?php

get_current_blog_id();

?>

Getting & Displaying the URL of the Admin Panel: get_admin_url() & admin_url()

These template tags return and display a URL of the Dashboard of your website.

Parameters

get_admin_url() accepts three parameters:

• $blog_ID (optional—integer):
  The ID of the blog.
  (Default: Current site)
• $path (optional—string):
  Optional path to append to the URL.
  (Default: Empty)
• $scheme (optional—string):
  The scheme to use. 'admin' respects the defined scheme (with the is_ssl() function) but you can override it by setting this parameter. Accepts 'http', 'https', 'admin', 'rpc', 'login' and 'login_post'.
  (Default: 'admin')

And admin_url() accepts two parameters:

• $path (optional—string):
  Optional path to append to the URL.
  (Default: Empty)
• $scheme (optional—string):
  The scheme to use. 'admin' respects the defined scheme (with the is_ssl() function) but you can override it by setting this parameter to 'http' or 'https'.
  (Default: 'admin')

Usage

<?php

// Get the dashboard url of the current blog.
$admin_url = get_admin_url();

// Display the admin url and force a secure connection.
admin_url( '', 'https' );

?>

Getting & Displaying the Permalink of a Feed Type: get_feed_link() & the_feed_link()

These template tags return and output the permalink of a feed.

Parameters

get_feed_link() accepts only one parameter:

• $feed_type (optional—string):
  Type of the feed.
  (Default: Default feed type)

And the_feed_link() accepts two parameters:

• $anchor (required—string):
  Text to display for the link.
  (Default: NULL)
• $feed_type (optional—string):
  Type of the feed.
  (Default: Default feed type)

Usage

<?php

// Get default feed type's link.
get_feed_link();

// Display a link for the "atom" feed.
the_feed_link( __( 'Atom Feed', 'translation-domain' ), 'atom' );

?>

Making the String End With or Without a Trailing Slash: user_trailingslashit()

This template tag checks your permalink structure, and adds a trailing slash or removes the existing trailing slash at the end of the given URL.

Parameters

This template tag accepts two parameters:

• $string (required—string):
  The URL with or without a trailing slash.
  (Default: NULL)
• $type_of_url (deprecated—string):
  This isn't technically deprecated, but it's not used in the function, so it has no effect whatsoever.

Usage

<?php

$url_to_fix = user_trailingslashit( get_home_url() . 'some-special-page' );

?>

Getting Number of Days Since the Start of the Week: calendar_week_mod()

This weird template tag gets number of days since the start of the week. It's basically a "modulo operation".

I honestly don't know how to use this or why to use this. If you know why this template tag exists, shoot a comment to inform me and our readers!

Parameters

This template tag accepts only one parameter:

• $number (required—integer):
  Days since the start of the week.
  (Default: 0)

Usage

<?php

// Umm...
echo calendar_week_mod( 199 );

// Right? (it echoes "3" by the way).

?>

Getting & Displaying the Calendar: get_calendar()

Remember those calendars we used to place in the sidebars of our blogs? This template tag does exactly that: It returns or displays the calendar.

Parameters

This template tag accepts two parameters:

• $initial (optional—boolean):
  Use initial calendar names (TRUE) or not (FALSE).
  (Default: TRUE)
• $echo (optional—boolean):
  Whether to echo (TRUE) or return (FALSE) the output.
  (Default: TRUE)

Usage

<?php

// Return the calendar.
$my_calendar = get_calendar( true, false );

// Display the calendar. 
get_calendar();

?>

Conclusion

Hope you liked this last batch of template tags. In the next part, the series finale, we're going to review what we learned and end the series.

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!

by Barış Ünver via Tuts+ Code