Most themes are compatible with PowerPress. PowerPress is developed and tested using the default themes packaged with WordPress including Twenty Ten, Twenty Twelve, Twenty Thirteen and all future default themes. These themes use WordPress best practices and adhere to theme rules set by WordPress.org. Any child theme based on these themes should also work without issue.
Though we do not test these themes during development, we've been told Genesis-based themes are 100% compatible with PowerPress.
If a theme is not compatible initially, in most cases the "Try to fix options" built into PowerPress can correct them.
What does PowerPress do that's so special?
PowerPress logic adds the player and links only once for a given post or page. This is to prevent duplicate players from appearing in a page. PowerPress does this by adding the player and links during the first iteration of the the_excerpt or the_content filters. Subsequent calls to the_content and the_excerpt filters for a given post are ignored.
Under normal circumstances this works quite well and prevents duplicate players for a given media file appearing more than once in a page. For a handful of themes, poor usage of WordPress functions may cause issues.
WordPress the_excerpt and the_content functions explained
It is documented on WordPress.org that the_excerpt and the_content functions must be within The Loop (a designated area in the theme that loops through and displays page content). The Loop functions allow WordPress core and plugins such as PowerPress to know when to add data to the page's content. If the functions are called outside of The Loop, functionality such as the podcast player and links will be added to content that it was not intended for.
Some themes and plugins will use the_content or the_excerpt filters outside of The Loop for non-page displaying purposes. For example, when a theme calls the_excerpt in the page's header for use in a description meta tag, the_excerpt filter will proceed to call the_content function (the automatic excerpt feature) to get the page's content. Then the_content function will iterate through the_content filter, notifying WordPress core and the plugins to add functionality to the page's content. The content is then processed through the the_excerpt filter, all HTML is removed (which removes the player and links just added by PowerPress) and the remaining text is shortened. Then the_excerpt filter ends, allowing the_excerpt function to return its result to the theme for the description meta tag. Even though the returned result is the first few sentences of the page's content, the above iteration occurs, which is a waste of CPU and memory use.
If a theme needs the excerpt and/or the content when outside of The Loop (such as in the header of your theme), consider creating a function to get the excerpt or content from the $post object.
How to fix a player and links display issue with PowerPress
PowePress 6.2.1+ comes with four methods that may fix the absence-of-a-player problem.
Method 1: The PowerPress shortcode can be used to insert the player and links into a specific location in the content. Click here for more information about the PowerPress shortcode.
Method 2: Let PowerPress try to fix. Go to PowerPress Settings page, to the Appearance tab. Scroll down to the option titled "Having Issues?" Select the appropriate option and click save. If you have configured server caching (either WordPress caching plugin or a service such as CloudFlare or Varnish), clear your cache when testing these options.
Having Issues? Options explained
Yes, try to fix option works by adding an HTML comment to the content to determine if the player and links have been added to the content already. When a theme or plugin uses the post content for another purpose, later calls to the_content / the_exerpt will not include the HTML comment, this lets PowerPress know it needs to add the player to the content.
The HTML comment is safe to use and does not include any specific information.
Typical Use: When you do not see your player and links in any pages on your site.
Yes, alternative fix option works by waiting until the wp_head action is completed. This option will ignore the_content / the_excerpt filter if it is called preceding the wp_head action. Once the wp_head action is completed, PowerPress will add the player and links to the the_content / the_excerpt filters.
Typical Use: When you see text from the player and links in your site's header meta tags.
Yes, excluding excerpts option works just like the first method by adding an HTML comment to determine if the player and links have been added. It will not apply when the_excerpt is used. Only direct calls to the_content will be fixed.
Typical Use: When you see duplicate text from the player and links where excerpts are displayed in your site pages, such as in search results.
Yes, wp_head check option works by creating a PHP Exception object to examine the function calls that have been made to determine if the the_content/the_excerpt call was made in the wp_head (HTML <head>) section of the HTML page.
Typical Use: When you do not see your player and links in any pages on your site.
None of the options above fix my display problem
If none of the "Having Issues?" options work, this is an indication that the theme is not using the_content / the_excerpt filters. There may be valid reasons for this, such as a custom content carousel or a newspaper style grid for a home-page. For such situations, the theme developer can utilize PowerPress the_powerpress_content and get_the_powerpress_content template functions (also referred to as theme tags). Please visit PowerPress and your Theme to learn more about these functions.