WordPreciousss’ loop templates is a special feature with WordPreciousss, and you can look on them as mini-templates that you may include in normal template files for your theme or skin.

The feature is a legacy from WordPreciousss as a theme and was kept to make it easier to create a basic theme and to create normal template files for a theme.

And just like other template files the default loop templates (located in /templates/precious/loops/) can be overridden in a theme or a skin, but in themes they need to be located in a subdirectory called /loops

Basic usage

The loop templates should be used together with WordPress Loop when creating normal template files. And it’s important that include theme between the codes <?php if (have_posts()) : ?> and <?php endif; ?>

<?php if (have_posts()) : ?>
... include precious loop templates here ..
<?php endif; ?>

So a single.php may look like this:

<?php precious_get_file('header'); ?>

<?php if (have_posts()) /*start loop*/ : ?>
     <?php precious_single_post() /*include single-post.php loop template*/; ?>

     <?php comments_template() /*include comments.php template*/; ?>

<?php else /*if no posts */: ?>

     <?php precious_404_info() /*include 404info.php loop template*/;?>

<?php endif; /*end loop*/?> 

<?php precious_get_file('footer'); ?>

Example usage

A good example for usage of this feature is when you create a custom page template. Usually when we do this in normal WordPress themes, we copy either the entire content of page.php or index.php and add the extra code we want to show up on the custom page template.

This is totally okay when you have only one custom page template, but when you have several you suddenly have a lot of code and files to deal with, and if you decide to change the basic setup (HTML etc.) of a Page, you have lot of files to go through.

But by using the loop template feature you can set up a custom page template for links like this:

<?php
/*
Template Name: Links
*/
?>

<?php precious_get_file('header'); ?>

<?php if (have_posts()) {
	precious_page_loop(); //call page-loop.php template file
}
?>

<div class="pagetemplate">
	<ul class="bookmarks">
	<?php wp_list_bookmarks('title_li='); ?>
	</ul>
</div>

<?php precious_get_file('footer');  ?>

If you have several page templates and all includes the page-loop.php template file, you only need to edit or create a new page-loop.php file to change the setup of all your Pages.

Template tag: precious_loop()

The template tag precious_loop() calls all loop templates, and should be placed in your theme’s index.php file when creating a new theme for WordPreciousss.

precious_loop() works by using conditional tags to tell WordPress which loop template to show in which view.

This allows you to set up the content views of your theme using only loop templates.

The template tag also includes header.php, footer.php and comments.php by default, so you don’t have to worry about adding extra template codes to include them (note: sidebar.php is included in the file /includes/contentfooter.php, which is included in the default footer.php).

Loop template: blog-loop.php

blog-loop.php is created with the front of your blog in mind and can be used in index.php (if you don’t use precious_loop()) or in blog.php*. The template is included with the template tag precious_blog_loop();

Additional usage of this loop template is to include it in some kind of archive template (archives.php, category.php etc.) or search template to show full posts instead of just the excerpt.

*blog.php is a special home template file in WordPreciousss

Loop templates: archive-loop.php

archive-loop.php is made for usage in any kind of archive template - archive.php, category.php, tag.php etc.

The loop template can be included with the template tag precious_archive_loop();

Loop templates: search-loop.php

search-loop.php is made for the search template (search.php). search-loop.php can be included with the template tag precious_search_loop();

This loop template was created purely to make it easy for you to set up search view different from the archive (archive-loop.php) or blog view (blog-loop.php). Additional usage can be to include it in tag template, if you use tags as a search feature on your site.

Loop template: page-loop.php

The page-loop.php is for usage on any kind of page template (as shown in Example Usage). page-loop.php are called by the template tag precious_page_loop();.

The page-loop.php does not include the comments.php template, which gives you a choice if you want to include the comments template on a page or not.

If you want to include the comments template on a page, you need to add comments_template(); after precious_page_loop();

Loop template: single-post.php

This works like page-loop.php, but are made for any kind single post templates.

single-post.php is included with the template tag precious_single_post();

Loop template: 404info.php

404info.php is for usage in 404.php templates, and can also be included in normal template files to show some info when no posts are found (see basic usage for example).

The 404info.php loop template can be included with the template tag precious_404_info();

Afterwords

The loop template feature is not really necessary to use when you just create a normal theme, but it’s an option you have.

However; I’ve found it better to use this feature when creating global template sets for a site, as the loop templates won’t mess up any themes that don’t have them included.