Sage Theme Sidebars are WordPress sidebars set up DRY using the theme’s wrapper. Basically sidebars done the right way. You will need to add the code to register a new sidebar and add the code to the theme file where you want the sidebar to be loaded. Just like you would normally add a sidebar to a regular theme. There are however a few things you need to look at. These include:

• the location to add the various code snippets,
• namespaces and the
• Sage specific loading and hiding of the general sidebar.

OK let’s dive into the matter and take it a step at the time.

Registering Sidebars in Sage

In your theme folder under theme/lib you can find the file setup.php. It combines what used to be called config.php and init.php. It basically is a config file containing code to add thumbnail sizes, sidebar, menus, theme assets as well as some tweaks when you use soil. Inside this file you will find this piece of code:

function widgets_init() {

 register_sidebar([
 'name' => __('Primary', 'sage'),
 'id' => 'sidebar-primary',
 'before_widget' => '<section class="widget %1$s %2$s">',
 'after_widget' => '</section>',
 'before_title' => '<h3>',
 'after_title' => '</h3>'
 ]);
 register_sidebar([
 'name' => __('Footer', 'sage'),
 'id' => 'sidebar-footer',
 'before_widget' => '<section class="widget %1$s %2$s">',
 'after_widget' => '</section>',
 'before_title' => '<h3>',
 'after_title' => '</h3>'
 ]);
}
add_action('widgets_init', __NAMESPACE__ . '\\widgets_init')

This is where Sage registers its sidebars. Here you could copy the code of one of the Sage theme sidebars and customize it to your liking. The action to add these sidebars uses coding you may not be familiar with as Sage uses namespaces which are available since PHP 5.3. Really useful to organize code the way you organize files in folders.

Loading Setup File

Also, as you may have noticed, the sidebars are not added to functions.php, but to a separate file. In functions.php this file is loaded with the following array:

$sage_includes = [
 'lib/assets.php', // Scripts and stylesheets
 'lib/extras.php', // Custom functions 
 'lib/media.php', // Media functions
 'lib/setup.php', // Theme setup
 'lib/titles.php', // Page titles
 'lib/wrapper.php', // Theme wrapper class
 'lib/customizer.php', // Theme customizer 
 'lib/widget.php' // Theme customizer
];

Sage does it this way to not overload the functions.php with all code and organize all more logically. And I like it. Otherwise I would not be using this awesome starters theme in the first place.

NB widgets_init() might be confusing here as it is when you start out with sidebars or asides. But sidebars load widgets after all so that is the function we need and action we use to load all the registered sidebars.

Displaying the General Sidebars

Displaying the sidebars is just like with any other sidebar. You could use the code:

<?php if ( dynamic_sidebar('example_widget_area_name') ) : else : endif; ?>

in any theme file for example. However, Sage does apply the DRY principle and does not like to repeat itself. So it uses base.php to load all code that is used cross files to load template files with or without a general sidebar (vertical one). Here a snippet from that bare file:

<div class="wrap container" role="document">
 <div class="content row">
 <main class="main">
 <?php include Wrapper\template_path(); ?>
 </main><!-- /.main -->
 <?php if (Setup\display_sidebar()) : ?>
 <aside class="sidebar">
 <?php include Wrapper\sidebar_path(); ?>
 </aside><!-- /.sidebar -->
 <?php endif; ?>
 </div><!-- /.content -->
 </div><!-- /.wrap -->

As you can see it determines whether or not the sidebar should be loaded. This being the general sidebar.

Sidebars File

And then the base.php file  load the sidebars from templates/sidebar.php. It does this using the sidebar_path() function. That function is inside lib.wrapper.php and states:

function sidebar_path() {
 return new SageWrapping('templates/sidebar.php');
}

This loads a new instance of SageWrapping with the sidebar file. I could write a whole section on the wrapper, but I won’t here to keep this article within bounds. More on the Sage wrapper here. In that file sidebar.php you will initially find only:

<?php dynamic_sidebar('sidebar-primary'); ?>

This is the main sidebar that is loaded selectively using the soon to be mentioned display_sidebar() function. One for my theme in progress has:

 <?php if (!is_woocommerce()) : ?>
 <?php dynamic_sidebar('sidebar-primary'); ?>
 <?php endif; ?> 
 <?php if (taxonomy_exists('product_cat')) : ?>
 <?php dynamic_sidebar('shop-main'); ?>
 <?php endif; ?>

As you can see I added some WooCommerce specific code for loading Sage theme sidebars for the shop part of things.

Hiding the Main Sidebar

Sage has an added function / filter you can easily use to show or hide the general sidebar that comes with the theme. It is inside the file lib/setup.php:

/**
 * Determine which pages should NOT display the sidebar
 */
function display_sidebar() {
 static $display;
 isset($display) || $display = !in_array(true, [
 // The sidebar will NOT be displayed if ANY of the following return true.
 // @link https://codex.wordpress.org/Conditional_Tags
 is_404(),
 is_front_page(),
 is_page_template('template-custom.php'),
 ]);
 return apply_filters('sage/display_sidebar', $display);
}

You just add the WordPress conditional tag of the page, post, custom post type you do not want to see loaded with a sidebar et voila!

Under extras.php you can see a class is added when the above mentioned array does not contain the conditional posts/pages/custom post types:

 // Add class if sidebar is active
 if (Setup\display_sidebar()) {
 $classes[] = 'sidebar-primary';
 }

This as most pages either have a sidebar or aside or do not. Again, this is not relevant for footer or header sidebars or special sidebar areas.

Other Widgetized Areas

Other sidebars that are not content sidebars or asides loaded left or right of the main content are loaded in template files like they would normally be. They are normally added to the template parts where they should be loaded like the footer sidebar which is loaded from a template part using the following snippet in the base.php file:

get_template_part('templates/footer');

This as they will not be part of the display_sidebars function as they are not content asides. In the footer template_part you will find:

<footer class="content-info">
 <div class="container">
 <?php dynamic_sidebar('sidebar-footer'); ?>
 </div>
</footer>

which loads the sidebar-footer. For most of our themes we have at least four footer widget areas or sidebars.

Summary

Well, that’s it. Now you know how Sage loads content sidebars or asides and other widgetized areas. You also know a bit more about the Sage theme wrapper used to keep things DRY. This to make sure we do not repeat ourselves. In the upcoming posts I will talk some more about the wrapper as well as creating template parts and general Sage theme development.