For the most part, Sensei will work nicely with any WordPress theme. Just install a theme, activate it, and you’re good to go!
A small percentage of our users, however, may encounter theme compatibility issues. This advanced-level support document is for them.
TLDR: Add the following code snippet to your theme’s functions.php file (if you’re using a child theme), or to a plugin such as Code Snippets:
Technical Background
Theme compatibility issues can occur when the default Sensei content wrappers do not match those of the chosen theme. This is because Sensei pages use templates of their own, and it’s impossible for Sensei to know the exact markup a particular theme uses.
A content wrapper is just an HTML element, usually a <div>, that encloses all of the content on a post or page. These wrapper elements are normally added to allow the theme developer finer control over the appearance of the content.
When there is a mismatch between content wrappers, Sensei’s theme compatibility handling will do its best to render the content correctly. In some cases though, you may find it necessary to explicitly add support for your theme. To do so, you’ll need to add some code that tells Sensei which content wrappers it uses, so that courses and lessons get added in the right location. You will also need to add code that tells Sensei that you have added custom support for your theme.
Declaring Sensei Support for Your Theme
To prevent Sensei from using its default theme compatibility functionality, you must declare Sensei support by adding the following to your functions.php file:
Content Wrappers
The default Sensei content wrappers are in the following files:
- templates/globals/wrapper-start.php
- templates/globals/wrapper-end.php
These wrappers will work for most well-built themes.
We also provide custom wrappers for the following themes:
- _s
- Storefront
- Twenty Eleven
- Twenty Twelve
- Twenty Thirteen
- Twenty Fourteen
- Twenty Fifteen
- Twenty Sixteen
- Twenty Seventeen
Note: The wrappers for these themes are stored in the /theme-integrations/ folder and will be loaded automatically if you are using one of those themes. If you’d prefer not to load the wrappers for these themes and provide your own instead, you can prevent them from loading by adding the following code to your theme’s functions.php file:
add_filter( 'sensei_load_default_supported_theme_wrappers', '__return_false' );
If your theme uses a different structure, you’ll need to specify your own content wrappers by adding some code to your theme’s functions.php file, or to a plugin such as Code Snippets.
Specifying Your Own Wrappers
First, you’ll need to find the correct HTML structure for the wrappers. To do that, open your theme’s page.php file and look for the theme’s container divs. These are thedivs that appear before and after the content loop, which is responsible for displaying a page’s content.
Wrappers for the TwentyTen Theme
By default, the Sensei wrappers don’t work well with the TwentyTen theme (don’t worry, if you want to use it, this example will show you how!)
For example, if you look at a single quiz page, you can see how the sidebar is being pushed down below the main content:
If you look at the page.php file for the TwentyTen theme, you can see the HTML that is placed around the content loop:
The opening wrappers are the two openingdivs above the main content loop, and the closing wrappers are the corresponding closingdivs below the loop. You also need to include the get_sidebar function, which will output the sidebar on your Sensei pages.
If your theme’s page.php file is much more complex than this, and you can’t easily tell what the opening and closing wrappers are, you may need to get a developer to help you figure it out. We recommend Codeable or one of our WooExperts.
To make this theme work with Sensei, we need to unhook the default wrappers, and then hook in our own functions to specify the wrappers for this theme.
To unhook the default Sensei wrappers, add the following code to the end of the functions.php file in the theme:
Now hook in your own functions, which specify the correct start and end wrappers for the theme. Add this to the end of the functions.php file:
Now if you view the quiz page again, you’ll see that the sidebar is where it’s supposed to be.
Pagination Wrappers
Prior to version 1.1.0, Sensei used the standard WordPress pagination functions to navigate between courses, lessons, and quizzes. However, we’ve improved this by updating the pagination functions to display the next Course, Lesson, and Quiz, taking into account the order settings and the pre-requisite settings. The files that are used to accomplish this are
templates/globals/pagination-lesson.php – loads pagination for lessons
templates/globals/pagination-posts.php – loads default pagination for courses
templates/globals/pagination-quiz.php – loads pagination for quizzes