Roots 101 – Notes, tips, and more

admin Uncategorized

1. The Theme Wrapper

http://roots.io/an-introduction-to-the-roots-theme-wrapper/

The goal of a theme wrapper [3] is to remove any repeated markup from individual templates and put it into a single file. This file, base.php becomes the single, unambiguous, authoritative representation of knowledge (i.e. the base format code).

You never need to make calls to get_header(), get_footer() or get_sidebar() again. You can also refactor the base format of your site by editing  base.php.

  • Step 1: WordPress figures out which template to use (see this post about the template hierarchy)Once this template has been chosen, but before it’s loaded, WordPress runs the template_include($template) filter (ed. This filter hook can be used to override WordPress’s default template behavior).We use this filter to run our wrap function that saves the $main_template path and $base as static variables in our Roots_Wrapping class;The wrap function also checks to see if the $base is index (in which case we know to use the default base.php) and finally returns a new instance ofRoots_Wrapping.

    Note by me:

    add_filter('template_include', array('Roots_Wrapping', 'wrap'), 99);

    What happens here is that a class (Roots_Wrapping) method (wrap) is passed as a callback function (99 is the priority). See also Function Reference/add filter

  • Step 2: The theme wrapper selects which base to chooseDuring the construction of our new Roots_Wrapping instance, we set a variable for the $slug (which defaults to base) and create a new $templates array with the fallback template base.php as the first item.We then check to see if the $base exists (i.e. confirming we’re not starting on index.php) and shift a more specific template to the front of the $templates array,

    We then use the magic __toString() function to apply a filter to our final $templates array, before returning the full path to the most specific existing base template via the inbuilt WordPress function locate_template.

Step 3: The base-*.php file serves the content

Wrapping Things Up

Effectively we’ve started and ended with the standard WordPress Template Hierarchy, but grabbed the base format from the appropriate base file in between. The markup of our content is wrapped between our base markup, the cycle completes and the theme wrapper’s job is now done. In fact, because the theme wrapper starts and ends with the output from the standard Template Hierarchy, the vast majority of issues can be resolved just by looking through and understanding the Template Hierarchy Codex Page.

 

theme-wrapper-explain

TIPS and Q&A

  • Template-custom.php
    Q: All I want to do is have a page template that doesn’t wrap all the content in a div.container (so I can have full width sections) – I don’t even see a way to do this since all templates call base.php which has it coded in.
    A: There is a template-custom.php file in Roots, which has no sidebar. If you add a base-template-custom.php file, it will use that over the default base.php file, so you can remove the .container divs.
    .. Conditional tags are fine too. Which you use depends on how significant the markup change is and/or how convoluted the logic is; with a new base file reserved for the more complex scenarios.
  • A: Example. I want to have a template that has a custom scrolling feature for the content just on those pages. And with how base is set up it would be beneficial for me to adjust this page templates own base template.
    How could i alter this function so that if i use page-scrolling.php, it uses base-scrolling.php?
    Q: When using page-scrolling.php, it will automatically try to load base-page-scrolling.php. So you can either change your naming convention or use the roots_wrap_base filter to manually override the result, or the Roots Wrapper Override plugin if you don’t mind spending $10.

2. Sidebar

Two different sidebars:

You’ll want to register a new sidebar in /lib/widgets.php. Then, to call it only on the home page, you can set up a new base file and replace the sidebar call, but if this is the only change you are making, you might want to just set up a conditional in your /template/sidebar.php to call the new sidebar only on the home page.

http://discourse.roots.io/t/tutorial-roots-theme-carve-job/64/8

One thing I would say is Section D should take advantage of the Roots Bootstrap Walker and WordPress Menus. You just need to create a secondary navigation menu and change the classes when the menu is called:

<?php
if (has_nav_menu('secondary_navigation')) :
  wp_nav_menu(array('theme_location' => 'secondary_navigation', 'menu_class' => 'nav nav-pills nav-stacked'));
endif;
?>

Q: Hi Foxaii, in which file do I put that Walker code to add those classes to my sidebar menus?

A: Go to lib/init.php and add the second menu:

register_nav_menus(array( 'primary_navigation' => __('Primary Navigation', 'roots'), 'secondary_navigation' => __('Secondary Navigation', 'roots'), ));

Then put the original code I posted in whatever template you want it. You can then choose which menu to display in the menus dash.

3. _main.js

Page specific functions:

Notes on DOM-based routing (http://goo.gl/EUTi53 by Paul IrishOnly):
– Only fires on body classes that match. If a body class contains a dash, * replace the dash with an underscore when adding it to the object below.
– .noConflict()
The routing is enclosed within an anonymous function so that you can  always reference jQuery with $, even when in .noConflict() mode.