Hi,
The wrapper concept totally does your head in at first. It took me weeks to work out what was happening, but now I really love it. It means much cleaner code and funnily enough is easier to work with. However I totally feel your pain.
The problem for me was that I hadn’t got to grips with the standard WordPress template hierarchy which made getting my head round how Roots worked harder.
I don’t know whether this will help you or anyone else, but here are some notes (quite a bit taken from the WP docs as well) that I made up whilst I tried to get my head round it all…
Standard WordPress set up
Normally WordPress has the following template files:
- List item
- style.css
- header.php
- index.php
- sidebar.php
- footer.php
- single.php
- page.php
- comments.php
- 404.php
- functions.php
- archive.php
- searchform.php
- search.php
WordPress uses the Query String (which it gets from the URL of the current page on the website) to work out what template file or template files to use to generate the page.
Firstly WordPress works out what type of page the current page is (i.e. is it a posts, archive, page, category or other page)
WordPress works out what template page or pages to use based on something called the Template Hierarchy.
WordPress firstly checks to see if it can find the most specific template file for its needs and if not it falls back to the default. For example it may check the category ID, slug, taxomony name or other criteria.
How WordPress checks depends on the type of page being requested. For example if the page being requested is a blog category page it will try the following:
- It checks to see if there is a category template file for the current category. For example if the current category has an ID of 4, it will check to see if category-4.php exists
- If not it will check to see if the generic category template file, category.php exists.
- If that doesn’t exist it will check to see if the archive template exists- archive.php
- If that doesn’t, WordPress will fall back and use the default index.php
Here are the queries depending on page type:
Front Page
-
front-page.php (if doesn’t exist, falls back to…)
- index.php
Home (Blog) Page
-
home.php (if doesn’t exist, falls back to…)
- index.php
Single Post
-
single-{post_type}.php. If you are using custom post types you enter the slug of the custom post type- for example if the custom post type is “events”, this would be single-events.php (if doesn’t exist, falls back to…)
- single.php
Page
- custom page type (The Page Template assigned to the Page. You can create your own page templates (page-templatename.php for example) and select these on the edit page section). At the top of the page template you should put the template name in comments: /* Template Name: Magazine */ (if doesn’t exist, falls back to…)
-
page-(slug).php* (if doesn’t exist, falls back to…)*
-
page-(id).php (if doesn’t exist, falls back to…)
-
page.php* (if doesn’t exist, falls back to…)*
- index.php
Category (“Category” is an example of a “taxonomy”)
-
category-(slug).php (if doesn’t exist, falls back to…)
-
category-(id).php (if doesn’t exist, falls back to…)
-
category.php (if doesn’t exist, falls back to…)
-
archive.php (if doesn’t exist, falls back to…)
- index.php
Tag (“Tag” is an example of a “taxonomy”)
-
tag-(slug).php (if doesn’t exist, falls back to…)
-
tag-(id).php (if doesn’t exist, falls back to…)
-
tag.php (if doesn’t exist, falls back to…)
-
archive.php (if doesn’t exist, falls back to…)
- index.php
Custom Taxonomies
-
taxonomy-(taxomony)-(term).php (if doesn’t exist, falls back to…)
-
taxonomy-(taxomony).php (if doesn’t exist, falls back to…)
-
taxonomy.php (if doesn’t exist, falls back to…)
-
archive.php (if doesn’t exist, falls back to…)
- index.php
Archive
- archive-(post_type).php (if doesn’t exist, falls back to…)
- archive.php (if doesn’t exist, falls back to…)
- index.php
Author
-
author-(nicename).php (if doesn’t exist, falls back to…)
-
author-(id).php (if doesn’t exist, falls back to…)
-
author.php (if doesn’t exist, falls back to…)
-
archive.php (if doesn’t exist, falls back to…)
- index.php
Search
-
search.php (if doesn’t exist, falls back to…)
-
index.php (if doesn’t exist, falls back to…)
404 (Page Not Found)
-
404.php (if doesn’t exist, falls back to…)
-
index.php (if doesn’t exist, falls back to…)
Here are the main template files that usually come with a theme excluding headers, sidebars and other sections of pages:
- 404.php
- author.php
- base-front-page.php
- base.php
- category.php
- front-page.php
- index.php
- page-custom.php
- page-sample-page.php
- page.php
- single.php
- search.php
As well as the above there are sections of pages that the above pages can use to put together the page:
- header.php
- footer.php
- sidebar.php
- searchform.php
Finally there are some special files that need to be included:
- style.css (this gives WordPress the name and details of the theme. It can also be used for CSS styles)
- functions.php (special functions for the theme to use)
As well as the above you can now put in special template files that the template hierarchy can use for specific pages. For example a template for a specific category “category-(slug).php”
ROOTS
WordPress usually puts all of the code and content into these template pages and fetches the header, sidebar and footer from the header.php, sidebar.php and footer.php files. Roots does away with all of that and uses base files to give the template structure. This means you can have different pages with different headers and footers. This changes the way the WP template hierarchy works slightly.
If the current page is the front page, WordPress would normally check for the front-page.php template. However, Roots runs some code that checks to see if there is a “base” file for that template. In this case it is looking for base-front-page.php. If that doesn’t exist it will look for base.php. The base file includes the header and footer and checks to see if the sidebar should be outputted, but actually you can get the base.php file to output whatever you like.
For example…
Front Page
-
base-front-page.php (if doesn’t exist, falls back to…)
- base.php
Home (Blog) Page
-
base-home.php (if doesn’t exist, falls back to…)
- base.php
Single Post
-
base-single-{post_type}.php. If you are using custom post types you enter the slug of the custom post type- for example if the custom post type is “events”, this would be single-events.php (if doesn’t exist, falls back to…)
- base-single.php
- base.php
I hope that makes it clearer. It helped me…
(edited to fix formatting)