Create WordPress theme from scratch : Part 6 – The Loop

Welcome to Part 6 of the series Create WordPress theme from scratch. In this tutorial, we will explore the Loop. We will also look at the essential template tags needed to develop a WordPress theme.

If you missed the Part 5 of this series, then check it out at the link below.

Create WordPress theme from scratch – Part 5 – Common Templates

The Loop

Take a bow – it’s the Loop! Let’s hear what the authors have to say about their beautiful creation

The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHPcode in the Loop will be processed on each post.

I believe that it’s safe to say that the Loop is the is the backbone of WordPress. The Loop works on simple methodology:

1. Check if we have posts.
2. Setup the post data.
3. Display post data using functions called template tags.

You can use any HTML or PHP code in the Loop. You are not limited to template tags only. Based on the URL, all post data will be automatically retrieved from the database.

You can, of course, create your own query and overwrite the original query. This way you can display any sort of data you want.

The code below demonstrates the usage of the Loop

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
    <!-- Post content here -->
<?php endwhile; else : ?>
    <p><?php _e( 'Sorry, no posts found!' ); ?></p>
<?php endif; ?>

have_posts()

We start with have_posts – a boolean function that checks if we have posts to display. At the end of the loop, have_posts resets the loop by calling rewind_posts.

the_post()

This function retrieves the next post and sets up the post data. Many of the template tags rely on the data set up by this function.

In the example above, we are ending the Loop with a fallback condition that is printing a translatable text when there are no posts to display.

Essential WordPress Template Tags

The complete list of template tags is available at codex.wordpress.org/Template_Tags. Listed below are some essential template tags. Please note that I am not going to show any usage examples. Instead, I am linking the original documentation which has detailed usage examples.

the_id()

Displays the unique numeric ID of the current post. Use get_the_id if you want to retrieve the ID of the current post for use in PHP.

post_class()

Outputs a list of additional CSS class names that can be used to add custom CSS styles. Other plugins may use the filter post_class to add their own CSS class names.

is_sticky()

A boolean tag that returns true if the current post is sticky. In WordPress, a sticky post always appears on the front page.

It is worth noting that WordPress ignores sticky posts when taking into account the number of posts to display (set in Dashboard > Settings > Reading). Sticky posts always appear on the front page.

the_title( $before, $after, $echo )

Displays or returns the title of the current post. Accepts three arguments

• $before – Text to display before the title
• $after – Text to display after the title
• $echo – Boolean value representing whether to display the title or return it for use in PHP. Defaults to true and displays the title. If set to false then returns the title.

Displays the permalink to the current post. If you want to retrieve the permalink of another post you must use get_permalink instead and specify a post or post ID. The template tag get_permalink returns the permalink for use in PHP.

the_content ( $more_link_text, $strip_teaser )

Displays the content of the current post. When on a non-single page, this tag will only display the content before the first <!–more–> quick tag. When there is more text to display, argument $more_link_text is used as a label for the more link.

According to the codex, the argument $strip_teaser is a boolean . There is no documentation on this one and I am not sure about exactly what it does.

the_excerpt()

Displays the current post excerpt after applying several filters. When an excerpt is unavailable, this function returns the first 55 words of the post as an excerpt.

You can hook the excerpt_length filter to change the excerpt length.

the_content vs the_excerpt

When you use the More tag, you create a teaser which is used by the template tag the_content. On a non-single post page, the_content template tag will display the teaser only. This tag does not care about manual excerpts.

When a manual excerpt has not been specified, the_excerpt template tag will display the first 55 words from the post. If a teaser is present and is smaller than 55 words then it will display the teaser only. When a manual excerpt has been added, it will display the manual excerpt and ignore the teaser.

the_post_thumbnail( $size, $attr )

Displays the featured image of the current post. The current theme must add support for post thumbnails before this template tag can be used.

• $size – Specifies the size of the featured image. Defaults to post-thumbnail.
• $attr – Accepts an array and can be used to set image attributes like class, title etc.

the_time( $d )

Displays the time when the current post was published. This function accepts a single argument, a string representing a date format. You can specify any valid PHP date format string. This argument defaults to the date format set in the WordPress admin panel – Dashboard > Settings > General.

the_modified_time( $d )

This tag is similar to the_time template tag but displays the time when the current post was modified. Everything else is same.

the_category( $separator, $parents, $post_id )

Displays the category or categories a post belongs to.

• $separator – Text to separate each category links.
• $parents – Determines how parent-child relationships are displayed.
• $post_id – Defaults to the current post id and represents the post for which to retrieve the categories.

the_tags( $before, $sep, $after )

Displays the links to the tags associated with the current post.

• $before – Text to display before the first tag.
• $sep – Defaults to a comma and appears between each tag link.
• $after – Text that appears after the last tag link.

the_author_posts_link()

Displays a link to all posts by the current post author. The link text is set to the user’s Display name publicly as field.

Other useful stuff

body_class()

This template tag adds different class names to the opening body tag. This provides additional styling possibilities. When a theme is using this tag, additional class names can be added to the body tag using the body_class filter.

is_home()

A conditional template tag that returns true when the current page being displayed is the the blog posts index page.

is_front_page()

A conditional template tag that returns true when the main blog page is set to display latest posts or the current static page being displayed is set as the front page in the Dashboard > Settings > Reading.

get_template_part ( $slug, $name )

Loads a partial template file. Partial template files usually contain code that appears in multiple templates. Partial template files can be easily reused and overloaded using a child theme.

The best practice is to place a custom or partial template files inside a directory named template-parts.

This function looks for a file matching {$slug}.php. If no such file is present or the $slug parameter is not present then nothing will be loaded. When the $name argument is also present, then it looks for a file {$slug}-{$name}.php and if it is not found then looks for a file {$slug}.php.

Note that this function fails silently. You won’t receive any error notification what so ever!

human_time_diff( $from, $to )

Returns the human time difference between two UNIX timestamps. The result is returned in a format like 14 hours, 2 days, 2 months etc.

the_posts_navigation( $args )

Display navigation to newer and older posts when applicable. It accepts an associative array as an argument. Here are the available options:

• prev_text – Previous posts anchor text.
• next_text – Next posts anchor text.
• screen_reader_text – Text meant for screen readers.

the_posts_pagination( $args )

WordPress comes with a built-in pagination. If you have a lot of posts then you can use this to replace the normal navigation. Here are the available options supported using an associative array:

• mid_size – Number of page links to display on either side of the current link.
• prev_text – Anchor text of the previous link.
• next_text – Anchor text of the next link.
• screen_reader_text – Text meant for screen readers.

the_post_navigation( $args )

Displays navigation to next and previous post when applicable. This template tag is used in single post pages to provide navigation to next and previous posts. It accepts an associate array as an argument:

• prev_text – Previous post link anchor text. By default, this is set to the title of the post.
• next_text – Next post link anchor text. By default, this is set to the title of the post.
• in_same_term – Accepts a Boolean value. When set to true, gets posts which belong to the same term.
• excluded_terms – An array or a comma separated list of term ID’s to exclude.
• taxonomy – Default to category when in_same_term is set to true.
• screen_reader_text – Text for screen readers.

wp_link_pages( $args )

Displays page links when the post is paginated using the <!–nextpage–> Quicktag. This template tag is used in single page template files. The following list of options are supported using an associative array

• before – Text that appears before all links.
• after – Text that appears after all links.
• link_before – Text that appears before the text of the link.
• link_after – Text that appears after the text of the link.
• next_or_number –  Whether to display the page navigation as numbers or next/previous links.
• separator – Text to display between page numbers. Defaults to a single whitespace character.
• nextpagelink – Anchor text for next page link.
• previouspagelink – Anchor text for previous page link.
• pagelink – Format string for page numbers. To get the page number, use % in the string.
• echo – Boolean value that decides whether to display or return the results.

Conclusion

This concludes the sixth part of the series Create WordPress theme from scratch. In the next part of the series, we will start assembling our theme.