WordPress Theme Handbook

How do you create a global page template?

- Insert the template file to it's relevant folder (page-templates) - Include an opening PHP comment that states the template's name. Example: <?php /* Template Name: Example Template */ ?>

What can you do with functions.php?

- Use WordPress hooks. For example, with the excerpt_length filter you can change your post excerpt length (from default of 55 words). - Enable WordPress features with add_theme_support(). For example, turn on post thumbnails, post formats, and navigation menus. - Define functions you wish to reuse in multiple theme template files.

What should you consider when creating a new page template?

- You should consider wether the page is meant for one specific page or for any pages - What type of user control you want for the template

CODE: Using The Loop for a Blog Archive

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); the_title( '<h2>', '</h2>' ); the_post_thumbnail(); the_excerpt(); endwhile; else: _e( 'Sorry, no posts matched your criteria.', 'textdomain' ); endif; ?>

Display default sidebar content

<div id="sidebar-primary" class="sidebar"> <?php if ( is_active_sidebar( 'primary' ) ) : ?> <?php dynamic_sidebar( 'primary' ); ?> <?php else : ?> <!-- Time to add some widgets! --> <?php endif; ?> </div>

What is a Post Format?

A Post Format is used by a theme for presenting posts in a certain format and style. In short, with a theme that supports Post Formats, a blogger can change how a post looks by choosing a Post Format. Themes need to use add_theme_support() in the functions.php file to tell WordPress which post formats to support by passing an array of formats like so: function themename_post_formats_setup() { add_theme_support( 'post-formats', array( 'aside', 'gallery' ) ); } add_action( 'after_setup_theme', 'themename_post_formats_setup' );

What can a page template be applied to?

A page template can be applied to a single page, a page section, or a class of pages. Page templates generally have a high level of specificity. For example, page-about.php is more specific than page.php

Template partials

A template partial is a part of a template, which is included in other template. For ex. site header. Common template partials are: header.php footer.php sidebar.php For custom theme files you can use the Template tag get_template_part()

What is a widget?

A widget adds content and features to a widget area (also called a sidebar). Widget areas provide a way for users to customize their site. A widget is a PHP object that outputs some HTML. The same kind of widget can be used multiple times on the same page (e.g. the Text Widget). Widgets can save data in the database (in the options table).

How to create page template for specific post types?

After adding the name of the template in the comments, add a new line for post types you'd like it to support. Example: <?php /* Template Name: Full-width layout Template Post Type: post, page, event */ // Page code here...

Template tags

Built in WordPress functions to use inside a template file, to retrieve or display data.

How to create a custom page template for one specific page?

By naming the template: page-{slug}.php or page-{id}.php

How to add a custom version of a header to a theme file?

By using the Template Tag get_header('custom_template_name') The file itself should be in the root folder of the theme, and named: header-{custom_template_name}.php

How to style sticky posts?

By using the post_class() -method like so: <div id="post-<?php the_ID(); ?>" <?php post_class(); ?>> And then altering the CSS for .sticky -class like so: .sticky { color:red; }

What are the default taxonomies of WordPress?

Categories Tags Post formats

How to display sticky posts?

Display just the first sticky post. At least one post must be designated as a "sticky post" or else the loop will display all posts: $sticky = get_option( 'sticky_posts' ); $query = new WP_Query( 'p=' . $sticky[0] ); Display just the first sticky post, if none return the last post published: $args = array( 'posts_per_page' => 1, 'post__in' => get_option( 'sticky_posts' ), 'ignore_sticky_posts' => 1 ); $query = new WP_Query( $args ); Display just the first sticky post, if none return nothing: $sticky = get_option( 'sticky_posts' ); $args = array( 'posts_per_page' => 1, 'post__in' => $sticky, 'ignore_sticky_posts' => 1 ); $query = new WP_Query( $args ); if ( isset( $sticky[0] ) ) { // insert here your stuff... }

Where are Post Types stored?

In the "wp_posts" database table, but are differentiated by column "post_type". Different Post Types are displayed by different template files.

Where should you keep your global page templates?

In the page-templates -folder. WordPress recognises that file automatically. It helps to keep your files organized. NOTE: Specialized page template file (only created for one time use) *cannot* be in a sub-folder

How to register menus?

In this example, two locations are added to the "Manage Locations" tab: "Header Menu" and "Extra Menu". function register_my_menus() { register_nav_menus( array( 'header-menu' => __( 'Header Menu' ), 'extra-menu' => __( 'Extra Menu' ) ) ); } add_action( 'init', 'register_my_menus' );

How to configure debugging on WordPress?

In wp-config.php make sure the code is: define( 'WP_DEBUG', true ); WP_DEBUG_LOG and WP_DEBUG_DISPLAY are additional PHP constants which extend WP_DEBUG. LOG - displays all errors in a debug.log file in /wp-content/ directory. To enable, use: define( 'WP_DEBUG_LOG', true ); DISPLAY - displays all errors in within the HTML of your theme pages. It is displayed in your browser.

Which are the main post template files?

Index.php Home.php Single.php Singular.php Archive.php Author.php and Date.php Category.php, Tag.php, and Taxonomy.php Search.php

What's the ideal way to use The Loop?

It should be placed in index.php and any other templates used to display post data. It should be inserted directly under get_header(); template call. Code example: <?php get_header(); if ( have_posts() ) : while ( have_posts() ) : the_post(); // Display post content endwhile; endif; ?>

What is a local server stack?

It's a server which runs on your local machine. For example MAMP (Mac, Apache, MySQL, PHP)

Template files

PHP files which contain a mixture of HTML, Template Tags and PHP code. Template files are used to affect the layout of the different parts of the website. Ex. Header.php is used to build the header. The template hierarchy describes which templates files to load on the type of request, and wether the template file exists in the theme.

Which are the default Post Types?

Post (Post Type: 'post') Page (Post Type: 'page') Attachment (Post Type: 'attachment') Revision (Post Type: 'revision') Navigation menu (Post Type: 'nav_menu_item')

How to add Post Type support for Post Formats?

Post Types need to use add_post_type_support() in the functions.php file to tell WordPress which post formats to support: function themename_custom_post_formats_setup() { // add post-formats to post_type 'page' add_post_type_support( 'page', 'post-formats' ); // add post-formats to post_type 'my_custom_post_type' add_post_type_support( 'my_custom_post_type', 'post-formats' ); } add_action( 'init', 'themename_custom_post_formats_setup' );

Page templates

Predefined layouts or formats for sets of common web pages.

Style.css

Required, located in the root directory of theme. The header comment displays info about the theme.

What is a sidebar?

Sidebar is any area on your WordPress website, which contains Widgets. It used to mean only a side strip on a WordPress site, but now its meaning has expanded to any area that includes widgets.

How to enable support for thumbnails and featured images?

Support is declared by putting the following in your theme's functions.php file: add_theme_support( 'post-thumbnails' );

What is the Customize API?

The Customize API (Customizer) is a framework for live-previewing any change to WordPress. It provides a unified interface for users to customize various aspects of their theme and their site, from colors and layouts to widgets, menus, and more. Themes and plugins alike can add options to the Customizer. The Customizer is the canonical way to add options to your theme.

How does Customize API work, and what the four main types?

The Customize API is object-oriented. There are four main types of Customizer objects: Panels, Sections, Settings, and Controls. Settings associate UI elements (controls) with settings that are saved in the database. Sections are UI containers for controls, to improve their organization. Panels are containers for sections, allowing multiple sections to be grouped together. Each Customizer object is represented by a PHP class, and all of the objects are managed by the Customize Manager object, WP_Customize_Manager.

What is The Loop?

The Loop is the default mechanism WordPress uses for outputting posts through a theme's template files. It loops through each post retrieved for the current page one at a time and performs the action specified in your theme. You can use it to display post titles and excerpts for example.

How to enqueue CSS files, give an example of a snippet.

The basic function for enqueuing a style is: " wp_enqueue_style( $handle, $src, $deps, $ver, $media ); " $handle is simply the name of the stylesheet. $src is where it is located. The rest of the parameters are optional. $deps refers to whether or not this stylesheet is dependent on another stylesheet. If this is set, this stylesheet will not be loaded unless its dependent stylesheet is loaded first. $ver sets the version number. $media can specify which type of media to load this stylesheet in, such as 'all', 'screen', 'print' or 'handheld.' Example: wp_enqueue_style( 'slider', get_template_directory_uri() . '/css/slider.css',false,'1.1','all');

What is the purpose of functions.php?

The functions.php file is where you add unique features to your WordPress theme. It can be used to hook into the core functions of WordPress to make your theme more modular, extensible, and functional. Note: The same result can be produced using either a plugin, or functions.php. WARNING: If a WordPress plugin calls the same function, or filter, as you do in your functions.php, the results can be unexpected, even causing your site to be disabled.

Template Hierarchy

The logic WordPress uses tod ecide which theme template file(s) to use, depending on the content being requested.

What does the post_class() function do?

The post_class() outputs the class="whatever" piece for that div. This includes several different classes of value: post, hentry (for hAtom microformat pages), category-X (where X is the slug of every category the post is in), and tag-X (similar, but with tags). It also adds "sticky" for posts marked as Sticky Posts.

What is the rewind_posts() function?

The rewind_posts() -function resets The Loop, and allows to loop through the same query a second time. Also wp_reset_postdata() can be used, when you are running custom or multiple loops with WP_Query().

What is the "{theme-name}_setup()" -function, and what does it do?

The theme setup function is added to the themes functions.php file. It includes features which should be run when the theme is activated. Some example functions to add within the theme function are: -- Add feed links automatically inside <head> -- add_theme_support( 'automatic-feed-links' ); -- Registering custom menus -- register_nav_menus( array( 'primary' => __( 'Primary Menu', 'myfirsttheme' ), 'secondary' => __( 'Secondary Menu', 'myfirsttheme' ) ) );

How to display sidebars in your theme?

To do this, there are two steps: 1. Create the sidebar.php template file and display the sidebar using the dynamic_sidebar function 2. Load in your theme using the get_sidebar function Additionally, Create a Sidebar Template File: A sidebar template contains the code for your sidebar. WordPress recognizes the file sidebar.php and any template file with the name sidebar-{name}.php. This means that you can organize your files with each sidebar in its own template file.

How do you enable custom headers?

To enable Custom Headers in your theme, add the following to your functions.php file: add_theme_support( 'custom-header' );

How to enable custom logo for your theme?

To enable the use of a custom logo in your theme, add the following to your functions.php file: add_theme_support( 'custom-logo' ); When enabling custom logo support, you can configure five parameters by passing along arguments to the add_theme_support() function using an array: function themename_custom_logo_setup() { $defaults = array( 'height' => 100, 'width' => 400, 'flex-height' => true, 'flex-width' => true, 'header-text' => array( 'site-title', 'site-description' ), ); add_theme_support( 'custom-logo', $defaults ); } add_action( 'after_setup_theme', 'themename_custom_logo_setup' );

How to retrieve an attachment ID or image ID?

To retrieve the attachment ID, use get_posts() or get_children() function. This example retrieves the all attachments of the current post and getting all metadata of attachment by specifying the ID. // Insert into the Loop $args = array( 'post_parent' => get_the_ID(), 'post_type' => 'attachment', ); $attachments = get_posts( $args ); if ( $attachments ) { foreach ( $attachments as $attachment ) { $meta_data = wp_get_attachment_metadata( $attachment->ID, false ); } } If you want to retrieve images from the post ID only, specify post_mime_type as image: $args = array( 'post_parent' => get_the_ID(), 'post_type' => 'attachment', 'post_mime_type' => 'image', );

How to register a sidebar?

To use sidebars, you must register them in functions.php. Here's an example of registering two sidebars: function themename_widgets_init() { register_sidebar( array( 'name' => __( 'Primary Sidebar', 'theme_name' ), 'id' => 'sidebar-1', 'before_widget' => '<aside id="%1$s" class="widget %2$s">', 'after_widget' => '</aside>', 'before_title' => '<h3 class="widget-title">', 'after_title' => '</h3>', ) ); register_sidebar( array( 'name' => __( 'Secondary Sidebar', 'theme_name' ), 'id' => 'sidebar-2', 'before_widget' => '<ul><li id="%1$s" class="widget %2$s">', 'after_widget' => '</li></ul>', 'before_title' => '<h3 class="widget-title">', 'after_title' => '</h3>', ) ); }

What's the best way to link into themes directories?

Using the "get_theme_file_uri()" function.

What are custom headers, how do you call them?

When you enable Custom Headers in your theme, users can change their header image using the WordPress theme Customizer. This gives users more control and flexibility over the look of their site. Headers are placed into a theme using get_custom_header(), but they must first be added to your functions.php file using add_theme_support(). Custom headers are optional.

How does WordPress decide which template(s) should be displayed?

With the query string. 1. WordPress matches every query string to a query type to decide which page is being requested. 2. WordPress selects a template in the order of the template hierarchy 3. Uses the first matching template file in the themes directory. To get a deeper understanding of Template Hierarchy, go to: https://developer.wordpress.org/themes/basics/template-hierarchy/

What are Nonses

WordPress nonces are one-time use security tokens generated by WordPress to help protect URLs and forms from misuse. If your theme allows users to submit data; be it in the Admin or the front-end; nonces can be used to verify a user intends to perform an action, and is instrumental in protecting against Cross-Site Request Forgery(CSRF).

How can you create custom template files and call them?

You can call custom template parts to any location of your side by using the "get_template_part()" -function. For example, if you would like to create a custom template to handle your post content you could create a template file called content.php and then add a specific content layout for product content by extending the file name to content-product.php. You would then load this template file in your theme like this: get_template_part( 'content', 'product' );

What are Template Tags, and what can they do?

You can use a template tag to call another theme file or information from the database. - they can print dynamic content; - they can be used in multiple theme files; and - they separate the theme into smaller, more understandable, sections.

To add, remove, or modify any Customizer object, and to access the Customizer Manager, use the customize_register hook

function themeslug_customize_register( $wp_customize ) { // Do stuff with $wp_customize, the WP_Customize_Manager object. } add_action( 'customize_register', 'themeslug_customize_register' );

How to develop widgets?

https://developer.wordpress.org/themes/functionality/widgets/

Here is an example of how to create custom Featured Image sizes in your theme's functions.php file.

if ( function_exists( 'add_theme_support' ) ) { add_theme_support( 'post-thumbnails' ); set_post_thumbnail_size( 150, 150, true ); // default Featured Image dimensions (cropped) // additional image sizes // delete the next line if you do not need additional image sizes add_image_size( 'category-thumb', 300, 9999 ); // 300 pixels wide (and unlimited height) }

How to display custom logo in your theme?

if ( function_exists( 'the_custom_logo' ) ) { the_custom_logo(); }

What are the absolutely required files in a WordPress theme?

index.php and style.css

How to display menus?

wp_nav_menu( array( 'theme_location' => 'header-menu' ) ); You can also add container class: wp_nav_menu( array( 'theme_location' => 'extra-menu', 'container_class' => 'my_extra_menu_class' ) );