The Tuts Guide to Template Tags: Second Batch

In the second part of the series, we went through the first batch of WordPress template tags. In this third part, we're going to go through the second batch of the almost 200 template tags. Throughout the tutorial, we'll see template tags about taxonomies and terms.

Getting the Description of a Category: category_description()

This template tag returns the description of a category.

Parameters

This template tag accepts only one parameter:

• 
  $category_ID (optional—integer):
  The ID of the category.
  (Default: The queried category)
  

Usage

<?php

$cat_desc = get_category_description( 15 );

?>

Getting the Description of a Tag: tag_description()

This template tag returns the description of a tag.

Parameters

This template tag accepts only one parameter:

• 
  $tag_ID (optional—integer):
  The ID of the tag.
  (Default: Current tag)
  

Usage

<?php

// Display the description of current tag.
echo tag_description();

// Get the description of a specific tag.
$special_tag_desc = tag_description( 42 );

?>

Getting the Description of a Term: term_description()

This template tag simply returns the description of a term.

Parameters

This template tag accepts two parameters:

• 
  $term_ID (optional—integer):
  The ID of the term.
  (Default: Current term)
  


• 
  $taxonomy (optional—string):
  The taxonomy of the term.
  (Default: 'post_tag')
  

Usage

<?php

// Display the description of current term.
echo term_description();

// Get the description of a specific term from a specific taxonomy.
$special_term_desc = term_description( 14, 'laptop_inches' );

?>

Getting & Displaying a Page Title for Category Archives: single_cat_title()

This template tag returns and displays the category's title 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 category title with a prefix.
single_cat_title( 'Category: ' );

// Get the category title.
$cat_title = single_cat_title( '', false );

?>

Getting & Displaying a Page Title for Tag Archives: single_tag_title()

This template tag returns and displays the tag's title 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 tag title with a prefix.
single_tag_title( 'Tag Archive: ' );

// Get the tag title.
$tag_title = single_tag_title( '', false );

?>

Getting & Displaying a Page Title for Term Archives: single_term_title()

This template tag returns and displays the term's title 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 term title with a prefix.
single_term_title( 'Term Archive: ' );

// Get the term title.
$term_title = single_term_title( '', false );

?>

Getting & Displaying the Categories of the Post: get_the_category_list() & the_category()

These template tags fetch and output the categories that are assigned to the post.

Parameters

Both template tags accept three parameters:

• 
  $separator (optional—string):
  Separator text.
  (Default: Empty—if this parameter is empty, the functions will return and display an unordered list of categories)
  


• 
  $parents (optional—string):
  How to display parent categories ('multiple', 'single' or empty).
  (Default: Empty)
  


• 
  $post_ID (optional—integer):
  The ID of the post.
  (Default: Current post)
  

Usage

<?php

// Get an unordered list of current post's categories.
get_the_category_list();

// Display current post's categories separated by commas and with their parents (if there are any).
the_category( ', ', 'multiple' );

?>

Getting & Displaying the Categories of the Post for Feeds: get_the_category_rss() & the_category_rss()

These template tags make the categories that are assigned to the post ready for feeds and return or display it.

Parameters

Both template tags accept only one parameter:

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

Usage

<?php

// Get feed items of categories for the default feed type.
get_the_category_rss();

// Display feed items of categories for atom feeds.
the_category_rss( 'atom' );

?>

Getting & Displaying the Tags of a Post: get_the_tag_list() & the_tags()

These template tags return or display the tags of your posts.

Parameters

Both template tags accept three parameters:

• 
  $before (optional—string):
  The text or HTML code to display before the output.
  (Default: Empty for get_the_tag_list() and 'Tags: ' for the_tags())
  


• 
  $sep (optional—string):
  The text to be used as a separator.
  (Default: Empty for get_the_tag_list() and ', ' for the_tags())
  


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

Usage

<?php

// Get a plain list of tag links.
get_the_tag_list();

// Display the tags with custom parameters.
the_tags( '<div class="mytheme-tags">' . __( 'Tags: ', 'translation-domain' ) , ' &middot; ', '</div>' );

?>

Getting & Displaying the Terms of a Post: get_the_term_list() & the_terms()

These template tags get and echo a list of terms assigned for the post.

Parameters

Both template tags accept five parameters:

• 
  $post_ID (optional—integer):
  The ID of the post.
  (Default: Current post)
  


• 
  $taxonomy (required—string):
  Taxonomy to display its terms.
  (Default: Empty)
  


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


• 
  $sep (optional—string):
  Separator text.
  (Default: ', ')
  


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

Usage

<?php

// Getting current post's terms from the "Available Brands" taxonomy.
get_the_term_list( $post->ID, 'available-brands' );

// Display current post's terms from the "Available Brands" taxonomy with some customization.
the_terms( $post->ID, 'available-brands', __( 'Available Brands: ', 'translation-domain' ), ' - ' );

?>

Displaying the Taxonomies of a Post: the_taxonomies()

This template tag displays the taxonomies and the terms associated with those taxonomies.

Parameters

This template tag accepts only one parameter:

• 
  $args (optional—array):
  An array of the following arguments:
  
  
  
  • 
    'post' (integer): Post ID.
    (Default: 0)
    
  
  
  • 
    'before' (string): HTML code to add before the output.
    (Default: Empty)
    
  
  
  • 
    'sep' (string): Separator text.
    (Default: ' ')
    
  
  
  • 
    'after' (string): HTML code to add after the output.
    (Default: Empty)
    
  
  
  • 
    'template' (string): The template to use for displaying the taxonomy terms.
    (Default: '%s: %l.' where %s is the taxonomy label and %t is the list of term links)
    
  
  
  
  

Usage

<?php

$args = array(
    'before' => '<div class="taxonomies">',
'sep'    => ', ',
'after'  => '</div>'
);

the_taxonomies( $args );

?>

Getting & Displaying the "Edit Tag" Link: get_edit_tag_link() & edit_tag_link()

These template tags return or echo a "edit this tag" link for you to use in your templates.

Parameters

get_edit_tag_link() accepts two parameters:

• 
  $tag_ID (required—integer):
  The ID of the tag.
  (Default: NULL)
  


• 
  $taxonomy (optional—string):
  The type of taxonomy.
  (Default: 'post_tag')
  

And edit_tag_link() accepts four parameters:

• 
  $link (optional—string):
  Text to display for 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)
  


• 
  $tag (required—object):
  Tag object.
  (Default: NULL)
  

Usage

<?php

// Retrieving the current tag's "edit tag" link.
$edit_tag_link = get_edit_tag_link();

// Retrieving a specific term's "edit term" link.
$edit_tag_link = get_edit_tag_link( 4, 'keyboard-brand' );

// Displaying the current tag's "edit tag" link.
edit_tag_link( __( 'Edit', 'translation-domain' ), '<strong>', '</strong>' );

// Displaying a specific tag's "edit tag" link.
edit_tag_link( __( 'Edit', 'translation-domain' ), '', '', 11 );

?>

Getting & Displaying the List of Categories: wp_list_categories()

This template tag returns or displays a list of categories or terms from any kind of taxonomy.

Parameters

This template tag accepts only one parameter:

• 
  $args (optional—array):
  An array of the following arguments:
  
  
  
  • 
    'show_option_all' (string): Shows a link to home (or the "Posts" page set in Settings > Reading) if you set it to a non-blank value. The value will be the anchor text of the link.
    (Default: Empty)
    
  
  
  • 
    'show_option_none' (string): Text to show if there aren't any categories.
    (Default: 'No categories')
    
  
  
  • 
    'orderby' (string): How to order the links by. Accepts 'name', 'ID', 'slug', 'count' and 'term_group'.
    (Default: 'name')
    
  
  
  • 
    'order' (string): Whether to order items in ascending ('ASC') or descending ('DESC') order.
    (Default: 'ASC')
    
  
  
  • 
    'style' (string): Style to display categories—'list' to generate an unordered list or 'none' to generate a list of links separated with <br />s.
    (Default: 'list')
    
  
  
  • 
    'show_count' (integer): Show post count next to each category link.
    (Default: 0)
    
  
  
  • 
    'hide_empty' (integer): Hide empty categories or not.
    (Default: 1)
    
  
  
  • 
    'use_desc_for_title' (integer): Use descriptions as "title" attributes of the links.
    (Default: 1)
    
  
  
  • 
    'child_of' (integer): Displays only children of a given ID of a category.
    (Default: 0)
    
  
  
  • 
    'feed' (string): If set to any non-blank value, category feed links will appear next to category links. The value will be the anchor text of the links.
    (Default: Empty)
    
  
  
  • 
    'feed_type' (string): Type of feed ('rss', 'rss2', 'atom' or 'rdf').
    (Default: Empty)
    
  
  
  • 
    'feed_image' (string): Image path to override anchor text and show an image instead.
    (Default: Empty)
    
  
  
  • 
    'exclude' (string): Comma-separated list of category IDs to exclude.
    (Default: Empty)
    
  
  
  • 
    'exclude_tree' (string): Same as "exclude", but you must use this one if the "hierarchical" argument is set to 1
    (Default: Empty)
    
  
  
  • 
    'current_category' (integer): Adds a "current-cat" class when suitable.
    (Default: 0)
    
  
  
  • 
    'hierarchical' (integer): Display items with a hierarchical order or not.
    (Default: 1)
    
  
  
  • 
    'title_li' (string): Wraps the output with a <li> tag and displays a title before the category list. You would probably want to set this to an empty string and disable wrapping.
    (Default: 'Categories')
    
  
  
  • 
    'echo' (integer): Whether to echo the output (1) or return it (0).
    (Default: 1)
    
  
  
  • 
    'depth' (integer): Maximum depth.
    (Default: 0)
    
  
  
  • 
    'taxonomy' (string): Taxonomy to list.
    (Default: 'category')
    
  
  
  
  

Usage

<?php

$args = array(
    
    // Show an "All Posts" link.
'show_option_all' => __( 'All Posts', 'translation-domain' ),

// Order by post count.
'orderby' => 'count',

// Show post count.
'show_count' => 1,

// Show feed links.
'feed' => 'Feed',

// Remove title_li.
'title_li' => ''
);

wp_list_categories( $args );

?>

Getting & Displaying an HTML Dropdown of Categories: wp_dropdown_categories()

This template tag returns or echoes a dropdown menu (<select>) of categories or terms from a taxonomy of your choice.

Parameters

This template tag accepts only one parameter:

• 
  $args (optional—array):
  An array of the following arguments:
  
  
  
  • 
    'show_option_all' (string): Text to display for showing all categories/taxonomies.
    (Default: Empty)
    
  
  
  • 
    'show_option_none' (string): Text to display for showing no categories/taxonomies.
    (Default: Empty)
    
  
  
  • 
    'option_none_value' (mixed): Value to use when no category/taxonomy is selected.
    (Default: -1)
    
  
  
  • 
    'orderby' (string): What column to use for ordering the categories/taxonomies.
    (Default: 'ID')
    
  
  
  • 
    'order' (string): What direction to order categories/taxonomies.
    (Default: 'ASC')
    
  
  
  • 
    'show_count' (boolean or integer): Whether to show how many posts are in the category/taxonomy.
    (Default: 0)
    
  
  
  • 
    'hide_empty' (boolean or integer): Whether to hide categories/taxonomies that don't have any posts attached to them.
    (Default: 1)
    
  
  
  • 
    'child_of' (integer): Display all categories that are descendants of the given ID.
    (Default: 0)
    
  
  
  • 
    'exclude' (string): Comma-separated list of category/taxonomy IDs to exclude from the list.
    (Default: Empty)
    
  
  
  • 
    'echo' (boolean or integer): Whether to display or retrieve content.
    (Default: 1)
    
  
  
  • 
    'depth' (integer): The max depth.
    (Default: 0)
    
  
  
  • 
    'tab_index' (integer): Tab index for the SELECT element.
    (Default: 0)
    
  
  
  • 
    'name' (string): The NAME attribute value for the SELECT element.
    (Default: 'cat')
    
  
  
  • 
    'id' (string): The ID for the SELECT element.
    (Default: Empty)
    
  
  
  • 
    'class' (string): CSS class for the SELECT element.
    (Default: 'postform')
    
  
  
  • 
    'selected' (integer): The category/taxonomy ID to be selected by default.
    (Default: 0)
    
  
  
  • 
    'taxonomy' (string): The name of the taxonomy to retrieve.
    (Default: 'category')
    
  
  
  
  

Usage

<?php

$args = array(
    'show_option_none' => __( 'Nothing!', 'translation-domain' ),
'orderby' => 'title',
'show_count' => 1,
'echo' => 0,
'name' => __( 'brands', 'translation-domain' ),
'taxonomy' => __( 'available-brands', 'translation-domain' )
);

$brands_dropdown = wp_categories_dropdown( $args );

?>

Getting & Displaying the Tag Cloud: wp_tag_cloud()

This template tag returns or displays a cloud of terms, generated from a taxonomy of your choice (tags by default).

Parameters

This template tag accepts only one parameter:

• 
  $args (optional—array):
  An array of the following arguments:
  
  
  
  • 
    'smallest' (integer): Smallest text size.
    (Default: 8)
    
  
  
  • 
    'largest' (integer): Largest text size.
    (Default: 22)
    
  
  
  • 
    'unit' (string): Text size unit.
    (Default: 'pt')
    
  
  
  • 
    'number' (string): How many tags to return
    (Default: 45)
    
  
  
  • 
    'format' (string): How to return the tags list—'flat' for a flat list separated with spaces, 'list' for an HTML unordered list, and 'array' for a PHP array.
    (Default: 'flat')
    
  
  
  • 
    'separator' (string): Separator text.
    (Default: "\n")
    
  
  
  • 
    'orderby' (string): How to order the tags by ('name' or 'count').
    (Default: 'name')
    
  
  
  • 
    'order' (string): Whether to order items in ascending ('ASC') or descending ('DESC') order.
    (Default: 'ASC')
    
  
  
  • 
    'include' (array): An array of IDs to include.
    (Default: Empty)
    
  
  
  • 
    'exclude' (array): An array of IDs to exclude.
    (Default: Empty)
    
  
  
  • 
    'taxonomy' (string): Taxonomy to get the terms from.
    (Default: 'post_tag')
    
  
  
  • 
    'link' (string): 'view' for front-end viewing, 'edit' for back-end editing links. Works with the 'post_type' argument.
    (Default: 'view')
    
  
  
  • 
    'post_type' (string): If the 'link' argument is set to 'edit', you must set 'post_type' to a post type to set which type of posts will the "edit links" list.
    (Default: Empty)
    
  
  
  • 
    'echo' (boolean): Whether to echo the template tag or not.
    (Default: TRUE)
    
  
  
  
  

Usage

<?php

$args = array(
    
// Smallest & largest font sizes.
'smallest' => 10,
'largest'  => 32,

// Get only 20 tags.
'number' => 20,

// Order by term popularity.
'orderby' => 'count',

// Custom taxonomy.
'taxonomy' => 'brands',

// Return output instead of echoing.
'echo' => 0
);

$tag_cloud = wp_tag_cloud( $args );

?>

Getting a Custom Generated Tag Cloud: wp_generate_tag_cloud()

This template tag returns a tag cloud but this time, you get to choose your own tags.

Parameters

This template tag accepts two parameters:

• 
  $tags (required—array):
  An array of a list of tags.
  (Default: NULL)
  


• 
  $args (optional—array):
  An array of the following arguments:
  
  
  
  • 
    'smallest' (integer): Smallest text size.
    (Default: 8)
    
  
  
  • 
    'largest' (integer): Largest text size.
    (Default: 22)
    
  
  
  • 
    'unit' (string): Text size unit.
    (Default: 'pt')
    
  
  
  • 
    'number' (string): How many tags to return
    (Default: 0)
    
  
  
  • 
    'format' (string): How to return the tags list—'flat' for a flat list separated with spaces, 'list' for an HTML unordered list, and 'array' for a PHP array.
    (Default: 'flat')
    
  
  
  • 
    'separator' (string): Separator text.
    (Default: "\n")
    
  
  
  • 
    'orderby' (string): How to order the tags by ('name' or 'count').
    (Default: 'name')
    
  
  
  • 
    'order' (string): Whether to order items in ascending ('ASC') or descending ('DESC') order.
    (Default: 'ASC')
    
  
  
  • 
    'topic_count_text' (string): This is a nooped plural from _n_noop() to generate the text for the tooltip of the tag link.
    (Default: NULL)
    
  
  
  • 
    'topic_count_text_callback' (string): This is the callback function, which gives the count of the posts with that tag returns a text for the tooltip of the tag link.
    (Default: NULL)
    
  
  
  • 
    'topic_count_scale_callback' (string): This is the callback function that works with the 'smallest' and 'largest' arguments to calculate the font sizes of generated tags.
    (Default: 'default_topic_count_scale')
    
  
  
  • 
    'filter' (integer): If this is set to 0, the function won't pass the filter with the same name.
    (Default: 1)
    
  
  
  
  

Usage

<?php

// Get an array of the tags from current post.
$tags = get_the_tags( '', ', ', '' );

// Set arguments.
$args = array(
    'smallest' => 10,
'largest'  => 36,
'orderby'  => 'count'
);

wp_generate_tag_cloud( $tags, $args );

?>

Conclusion

Hope you liked this second batch of template tags. There are six more batches 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!