The SIDEBAR will take you through the steps for creating a WordPress Sidebar. Wordpress Sidebars are designed to contain WordPress Widgets, and are generally used on the side of the page, but may be inserted in other places, as well. They can be used in footers, or as a layout method for the main content section of the page.

We will add a sidebar to a theme that already uses sidebars, placing the new sidebar on a particular page, such as a page that displays a single post.

Along the way, we will look at the template hierarchy -- a logic tree that determines which PHP file template WordPress uses to display a page. Also, we will look at the structure of the "Single" page template to learn what parts of the page are being handled by which sections of the script.

This project has the following steps:

• Either set up a new WordPress site or work with the one that you set up in one of the earlier projects.
• Activate a WordPress theme that uses sidebars. The theme included with current WordPress versions (Twenty Twenty-One) doesn't use sidebars, so choose a different one, such as Twenty Sixteen.
• Create a child theme for the theme and activate it.
• Edit the functions.php file for the child theme to define and register the sidebar.
• Add the sidebar to your theme by creating child theme versions of the sidebar template and the single post template.
• Add some Widgets to the new sidebar in the WordPress dashboard.

Project Set-up. You can continue working with any of the WordPress sites you set up previously, or you can start a new site. If you start a new site, I recommend naming it n413_sidebar. The instructions will assume you are using a new project. Set up a new database and do a fresh install of the Wordpress files, as explained in The INSTALL. Be sure to namespace the table names if you are adding this project to a database that already contains other projects.

Twenty Sixteen. The current versions of WordPress come with themes that do not have sidebars, so we will use an older theme, Twenty Sixteen, that does use sidebars on the right side of the main layout. Adding a sidebar to a theme that does not support sidebars, such as Twenty Twenty-One, is a more complex process, so we won't try to tackle that job here.

In the dashboard, go to Appearance>Themes and use the "Add New" option and search for Twenty Sixteen. Once it downloads, install it and click "Activate" to make it the active theme. Create a front page, as you did in The BLOG and add a few blog posts now.

Child Theme. Create a new child theme, just as you did for The CHILD. You will need to modify the style sheet header to point to the twentysixteen theme directory. The header should look like this:

/*
Theme Name: Twenty Sixteen Child
Theme URI: http://www.example.com/ 
description: >-
  A child theme for Twenty-Sixteen and the N413/AMPJAM Sidebar Project
Author: <your name>
Author URI: http://example.com
Template: twentysixteen
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Tags: right-sidebar
Text Domain: twenty-sixteen-child
*/
/* Custom CSS goes after this line */           
            

Borrow the index.php file from the twentysixteen theme directory, and create the functions.php file just as you did for The CHILD. You can copy the functions.php file from that project into this one.

If you created widgets in The WIDGET, copy those files and the PHP code in the functions.php file into the new project.

Be sure to activate the child theme in the Wordpress dashboard.

The Sidebar. The sidebar is defined by an array of sidebar properties sent to a WordPress function named register_sidebar(). The WordPress function is wrapped in a function you define, and then called by one of the WordPress add_action "hooks". It looks like this:

//define a custom sidebar
function register_custom_sidebar() {
    register_sidebar(
        array(  'name'          => 'Custom Sidebar',
                'id'            => 'custom_sidebar',
                'description'   => 'The Custom Sidebar displays on any pages that need to show widgets.',
                'before_widget' => '<section>',
                'after_widget'  => '</section>',
                'before_title'  => '<h3>',
                'after_title'   => '</h3>'
        ) //array
    ); // end register_sidebar()
}// end register_custom_sidebar()

add_action( 'widgets_init', 'register_custom_sidebar' );

Here are the important points:

• register_custom_sidebar This is the name of the function you provide. You can name it any way you like. The function name is is used in the add_action "hook" used to call the function.
• register_sidebar This is a WordPress function and must conform to the WordPress specifications. It requires an array of arguments to construct the sidebar. This function should not be confused with a similar function, register_sidebars(), which creates multiple sidebars and requires a slightly different set of arguments.
• name This is the name of the sidebar as it should appear in the WordPress dashboard interface. WordPress documentation will often show this used with a translation function for multi-lingual implementations.
• id This is the id used to refer to the sidebar in PHP code when the siidebar is added to the theme.
• description The description will appear in the WordPress dashboard interface. It is often shown used with a translation function, as well.
• before_widget This will be any HTML Markup that needs to be placed before the sidebar's widgets. The HTML string will be passed to the widget as the widget() function's $args parameter (See The WIDGET), where it is drawn by the widget() function's code.
• after_widget This will be any HTML Markup that needs to follow the widget. It will typically close any tags created by before_widget, and is passed to the widget in the same way as the before_widget parameter.
• before_title This is an HTML Markup string that will be passed to the widget to place before the widget title.
• after_title HTML Markup that will close any before_title tags.
• add_action() This is a WordPress function that will add the register_custom_sidebar() function to the list of WordPress "hooks". This will cause the function to run when the widgets_init event occurs.

Add this code to your functions.php script in the child theme and save the file. If you go to the WordPress dashboard's Appearance>Widgets page, you should see the new sidebar displayed there with the name you provided as the name argument.

Adding the Sidebar to your Theme. The sidebar must be added to the PHP code for your theme. For this project, we want to create a special sidebar for only one part of the site, so we will modify only the pages that display single posts. The first step in the process is to create a customized sidebar template file for the child theme. Look in the twentysixteen theme directory and find the file named "sidebar.php". Copy this file into your child theme directory and rename it "sidebar-custom_sidebar.php". The file's script should look like this:

<?php
/**
 * The template for the sidebar containing the main widget area
 *
 * @package WordPress
 * @subpackage Twenty_Sixteen
 * @since Twenty Sixteen 1.0
 */
?>

<?php if ( is_active_sidebar( 'sidebar-1' ) ) : ?>
	<aside id="secondary" class="sidebar widget-area" role="complementary">
		<?php dynamic_sidebar( 'sidebar-1' ); ?>
	</aside><!-- .sidebar .widget-area -->
<?php endif; ?>	
			

The template file checks whether the sidebar is active (has widgets) and/or exists, and provides the necessary HTML markup around your sidebar for proper positioning. The dynamic_sidebar() function will draw the code for the sidebar and its widgets.

Simply drop in the id for the new sidebar ("custom_sidebar") in place of "sidebar-1" in the two functions. If you wish, you can modify the template header text to show that this is a custom sidebar for the child theme. The template text for this file is only informational.

The second step is to add the sidebar to a content page, using the WordPress get_sidebar() function. This will locate and load the sidebar template file. But first, we need to know which page to add the sidebar to. This is where some deeper understanding of how WordPress renders pages is useful. Take a quick look at the Template Hierarchy chart and its explanation in The HIERARCHY.

For our sidebar, we will place it on the page that draws individual posts. Trace out the path for single posts in the template hierarchy chart. Compare the chart listings with the files available in the twentysixteen theme directory. You should arrive at "single.php". Keep in mind that we never modify the theme directly. Instead, we will copy single.php to the child theme folder. WordPress will look for the file it needs in the child theme first. So our new copy of single.php will take priority over the Twenty Sixteen single.php. Now we can change it, break it, do anything we want, and the worst that can happen is we start over with a clean copy.

Single.php Have a look at the script for single.php and look for a few "landmarks":

• The first to note is the get_header()function, which will load the <head> section of the HTML document, and some of the opening tags, such as <body> and any header-style navigation. The code for this will be found in the theme's header.php script. Importantly, the header.php file will contain the opening tag for the main container div for the page content. This detail will vary from one theme to another. We want our sidebar to be inside this element if it is to display to the left or right of the main content.
• Next, note the two elements that follow:
  • <div id="primary" class="content-area"> This element is a wrapper for the post content. We want the sidebar to be a sibling for this element and display beside it.
  • <main id="main" class="site-main" role="main"> This element is a second wrapper for the post and the "article" tag that contains the post.
• Now look for while ( have_posts() ). This "while" loop is the start of "The Loop" and will iterate through any posts in the WordPress query. One notable feature of "The Loop" is the get_template_part() function. This function will call a PHP file in the template-parts directory that will provide the markup for drawing the post, such as the <article> tag.
• Following the close of the "while" loop, you will see the closing tag for the </main> tag followed by a get_sidebar('content-bottom') function and the closing </div> tag for the #primary .content-area element. This get_sidebar() function will draw a sidebar named 'content-bottom' (if it exists) at the bottom of the post.
• A second get_sidebar() function will follow the close of the #primary .content-area element, and this is the one we are interested in working with.
• Last will be the get_footer() function, which will call the theme's footer.php file. It will close any remaining tags (such as the container div opened in header.php) and draw the footer.

get_sidebar() The second get_sidebar() function will get a file named sidebar.php if there is no argument provided to the function. If we provide a sidebar name as the argument, it will look for sidebar-{name}.php. If we insert 'custom_sidebar' as the argument, it will load our sidebar in just the right location -- assuming there are any widgets in the sidebar.

Widgets. Now, go to the WordPress dashboard, look for Appearance > Widgets and find the "Custom Sidebar". Drag a few widgets into it and edit the titles so you will recognize them in the sidebar. Use your "Hello World" Widget if you included it in this project.

Load the Home page for the project, and notice the that the standard sidebar is still shown there. It should have a "Recent Posts" widget that will link you to one of your blog posts. Once you load a blog post, you should see your custom sidebar display on the single-post page.

Congratulations! You now have a custom sidebar for your blog posts. You can use this method to put a special sidebar on any of your pages. You can even customize whether the sidebar is on the left or right of the #primary .content-area element, using customized CSS in your child theme. You can put sidebars below the posts or in the footer, if you choose. Anywhere you want to display a widget, you can insert a sidebar as the container. And you should now be seeing opportunities to start styling parts of the theme with CSS as you learn where the scripts for various components will be found.

Customizing Other Themes There are some special considerations for themes that are not already set up for sidebars, such as Twenty Twenty-One. The difficulty arises from the way the various HTML elements are distributed among the header, content, and footer files. In particular, Twenty Twenty-One places the opening container element, the #primary .content-area element, and the <main> element in the header.php file. It also closes these elements in the footer.php file.

This means that a sidebar that displays alongside the content in the main body of the page would need to be added to the footer file, after the close of the #primary .content-area element. (Along with some CSS changes for the #primary .content-area element.) And this change would happen on all the pages that use the footer file. If you needed the sidebar to only display on a particular page, you would need to make a special footer template file for that page, similar to the way the sidebar template was modified here.

It is possible to modify any theme, but some themes are set up in ways that make certain modificatiions easier than others. If you feel adventurous, try working with some different themes!