A Quick Lesson in WordPress Semantics

As much as I love WordPress, there are quite a few elements and functions in the system that can be a bit confusing, and even ambiguous. In this article, I’m going to try to explain and unravel a few of these items.

What’s the difference between the “home” page and the “front page”?

To many users, the terms “home” page and “front page” might seem like the same thing. However, in WordPress, they’re treated as two different elements. The “home” page is the main page that shows blog posts. If you install WordPress and don’t change any of the settings, this will be your site’s front page. However, if you modify the “Settings -> Reading -> Front page displays” setting to select “A static page (see below)”, and you choose a page for the “Front page” and a page for the “Posts page”, the “home” page is no longer the first page on your site. Instead, the first page on your site is the “front page”, now.

Therefore, when using the is_front_page() and is_home() conditional functions, you need to know what the distinction is.

The is_front_page() function returns true only when the visitor is viewing the static page you’ve set as your site’s front page. If you don’t have a static page set as your site’s front page, that function will never return true.

The is_home() function will return true on your site’s main blog page (the page that shows your latest blog posts).

What’s a “site”, a “network” or a “blog”?

Back when WordPressMU was a separate project from WordPress, the term “blog” was used to describe a single site within a WordPressMU installation and the term “site” was used to describe the collection of “blogs” (generally the entire MU installation).

When WordPressMU was merged into the WordPress core and became WordPress Multisite, the term “site” started to refer to single instances within a Multisite installation, and the term “network” began to refer to the collection of “sites”.

In the documentation and in the administration area, the terms “site” and “network” are used to describe these items, but, mostly for backwards-compatibility reasons, the terms “blog” and “site” are still used in the code itself.

Therefore, if you want to retrieve an option from a specific site in the installation, you use the get_blog_option() function; and if you want to retrieve a setting that applies to the entire network, you use the get_site_option() function.

There are a few exceptions to this one, as well, though. To figure out whether you’re viewing the administration area for the entire network, you use is_network_admin(). To add an admin notice that displays only in the network administration area, you hook into the network_admin_notices action. To add a new menu or submenu in the network administration area, you hook into the network_admin_menu action.

Is You Is, or Is You Ain’t My Baby?

A fairly consistent naming convention in WordPress applies to the conditional functions that report which page is currently being viewed. Most of these functions start with “is_”, followed by the type of page for which you’re testing. If you want to know if you’re currently viewing an archive page, you use is_archive(); if you want to know if you’re viewing a page, you use is_page(); etc.

There is one notable gotcha in WordPress Multisite, though. The function is_super_admin() isn’t a conditional tag used to test which page is being viewed; instead it tells you whether or not the user with the ID you supply is a Super Admin user.

Template Function Naming Convention

For the most part, there are two different versions of each template function in WordPress. One of those functions will normally start with “the_” while the other will start with “get_the_”. The “the” function will output (echo) the information into the page directly where you call it, while the “get” function will return the information so you can store it in a variable.

Some examples include:

  • the_content() & get_the_content()
  • the_title() & get_the_title()
  • the_post_thumbnail() & get_the_post_thumbnail()
  • the_excerpt() & get_the_excerpt()
  • the_category() & get_the_category()
  • the_tags() & get_the_tags()
  • the_date() & get_the_date()
  • the_time() & get_the_time()

There are a few exceptions where things differ slightly from this convention, though. For instance, if you want to echo the URL to a page/post, you would use the_permalink(); but if you just want to retrieve it, you use get_permalink() instead of get_the_permalink().

If you want to retrieve information about the site, or you want to retrieve various URLs related to the site, most of those functions don’t include the word “the” in them. The retrieval functions still start with “get_”, though. For instance, you would use get_bloginfo() to retrieve information about the site, but you just use bloginfo() to echo it.

Templates, Themes and Stylesheets

In WordPress, the word “theme” generally refers to any package of files that governs the appearance of the site.

The word “template” is a little more ambiguous. In most of the documentation and in the administration area, the word “template” refers to a specific file that you can apply to specific pages.

The term “stylesheet” in WordPress refers to the location of the chosen theme, while the term “template” can refer to the chosen theme (in the case of an independent theme), or it can refer to the parent theme on which the chosen theme depends.

If you are using a child theme, using bloginfo( ‘stylesheet_directory’ ) will echo the URL to the directory in which your child theme resides, while bloginfo( ‘template_directory’ ) will echo the URL to the directory in which the parent theme resides. If you’re using an independent theme, both calls will echo the same URL.

To make things even more fun, you can define the WP_DEFAULT_THEME constant, but it can only be used to set independent or parent themes as your default active theme. If you try to set a child theme as your default, you’ll end up with some PHP errors and warnings.

Paths, Directories and URLs

As if the template/themes/stylesheets thing wasn’t confusing enough; this is where it starts to get really confusing. For the most part, the word “path” describes the absolute system path to something, directory refers to the URL to the base directory in which a file resides and url refers to the actual URL to a file.

However, there are a lot of exceptions in WordPress to this nomenclature. In the bloginfo() and get_bloginfo() functions, template_url and template_directory both return exactly the same information (the URL to the base directory for the chosen theme).

Some constants, such as WP_CONTENT_DIR, WP_PLUGIN_DIR, WPMU_PLUGIN_DIR, etc., refer to an absolute system path; while others that use “dir”, such as PLUGINDIR and MUPLUGINDIR (both left in the code strictly for backwards-compatibility) refer to relative paths.

Then, there are constants that include the word “path” that refer to absolute paths (as you’d expect), such as TEMPLATEPATH (which actually refers to a “theme” rather than a “template”) and STYLESHEETPATH; but the related functions that are actually used to populate those constants use the word “directory” (get_template_directory() and get_stylesheet_directory()).