Sensei’s theme compatibility handling ensures that Sensei looks good on your website’s frontend, no matter what theme you decide to use.
How does it work?
When Sensei displays full-page information on the frontend (for example, a course page, a lesson page, the course results page, a quiz page, etc), it needs to use custom PHP templates in order to display that information properly. Previously, Sensei would do this by overriding the theme’s PHP file for these pages and instead use its own.
The problem with this approach is that Sensei had no way of knowing what markup to generate that would work well with the individual theme’s CSS. As a result, for many themes, Sensei pages had serious display issues (the sidebar was in the wrong place, the content container was full-width instead of the width required by the theme, etc).
Since version 1.12, Sensei’s theme compatibility handling seeks to solve the problem in a different way. Instead of rendering the full page with possibly incompatible markup, it attempts to render the Sensei page content within the content area of the theme’s page.php template.
As a result, when Sensei is running its theme compatibility support, it never tries to render the full markup for a frontend page. Instead, it renders all of the special content and UI in the content area, while allowing the theme’s page.php file to render all of the appropriate wrapper markup. This ensures that the theme’s CSS works with the Sensei page.
How to disable theme compatibility?
For most themes, theme compatibility will be enabled by default. It is disabled in the following two cases:
- The theme or site explicitly declares Sensei support using
add_theme_support( 'sensei' ); - The theme is implicitly supported by Sensei itself (you can see which themes are supported by Sensei by looking in the
includes/theme-integrationsdirectory of your Sensei installation).
If you want to disable theme compatibility, but your theme does not explicitly declare support for Sensei, you may use the following code snippet:
add_action( 'after_setup_theme', 'declare_sensei_support' );
function declare_sensei_support() {
add_theme_support( 'sensei' );
}
How to add support for my theme?
Although theme compatibility should work in the majority of cases (and we will continue to work on making it better), in some cases it is better to add explicit Sensei support to your theme or site. To do so, please follow the steps in this document.
Troubleshooting issues
Double-rendering
The most likely issue you will come across with theme compatibility is double-rendering of some post data. Because Sensei uses the theme’s page.php template, it’s impossible to know exactly what the theme will render on the page. Sensei’s theme compatibility does its best to handle common items that the theme may attempt to display (the post title, comments section, etc) but it’s possible that the theme will still render something that is also rendered by the Sensei template.
If this is the case, the solution is to find where that item is being rendered in the theme’s page.php template or in Sensei and disable one of them. This may be done with a theme option, a Sensei setting, or a filter, depending on what is being double-rendered.
If you cannot find an option, setting, or filter, then you may need to customize a template in order to remove the double-rendering. You could customize the theme’s page.php template, or the Sensei template that is being rendered. To customize the theme template, you should use a child theme to ensure that your customizations are not overwritten by future updates. If you wish to customize a Sensei template, use these instructions.
Archive Page Issues
Because of the way archive pages work in theme compatibility (e.g. course category, lesson tag, course module, etc), there may be cases where some global variables (e.g. $post, $wp_query) do not have the values that might be expected. Most of the time, this should not be a problem, but it may come up in some cases.
Any code that runs while Sensei’s template is being rendered is guaranteed to have the global variables set as expected. This includes any code that runs within a Sensei action or filter, and any code that runs within the WordPress loop. Also, any code run within a widget will have the globals set as expected.
To prevent issues of this nature, ensure that any code expecting a Sensei object in a global variable runs within one of the cases mentioned above. Any such code that runs outside of those cases may find an unexpected object in the global variable, and thus may not function properly.
Other Troubleshooting
If you are experiencing display or functionality issues on a Sensei page, try switching to the Twenty Seventeen theme, which is implicitly supported by Sensei. If the issue does not exist on the supported theme, then you may be experiencing a problem with the theme compatibility support.
In this case you may want to try following the steps in this document to add explicit support for your theme. It is usually not difficult, but does require looking at some of your theme files, and adding some code snippets to your site.
If the problem persists after all troubleshooting steps, please contact our support team, and they will be happy to help!