wordpress standardized loop api

Standardized Loop API

The Next Big Thing?

Who Am I?

• Chris Jean• chrisjean.com• @chrisjean

• Developer for iThemes• Core contributor• Person who wants to make WordPress better for

everyone

The Problem

• There is very little in the way of methods for plugins to interact with a theme at The Loop level.

• Brief history of integration strategies:o Plugin readme.txt files filled with instructions on

integrating function and action calls into theme template files.

o Plugin-provided or custom built page template files.

o Use of shortcodes as injection points for plugin-generated content.

o Direct theme and plugin developer discussions to create specific solutions.

• These solutions simply aren't sustainable.

The Goal

• To make it easier for themes to provide a foundation of style that plugins can make use of

• To make it easier for plugins to provide output that themes can style

• To do this in a way that does not require the theme to know anything about the plugin and does not require the plugin to know anything about the theme

Case Study: BuddyPress

• BuddyPress has a great need to interact with themes at The Loop level.

• The BuddyPress solution was to build a theme completely tailored specifically for the plugin.

• The end result is that it is extremely difficult to build a BuddyPress-compatible theme without building a child theme of the BuddyPress Default theme.

The Solution

1.Create a way for themes to allow their The Loop content to be replaced without making the template files more difficult to create or maintain.

2.Create a way for plugins to register custom loop handlers that can replace the theme's default loop.

3.Create an HTML and class standard that provides a consistent foundation that themes can style

Following in the Footsteps of Sidebars• WordPress already has a great example for a

standardized way for themes and plugins to coexist and cooperate: Sidebars and Widgets.

• The power of sidebars and widgets hinges off of the dynamic_sidebar function. This function allows themes to provide default content for sidebars that can be replaced by widgets.

• The key is to wrap the default theme content in an if statement that uses the results of dynamic_sidebar as the conditional.

if ( ! dynamic_sidebar( 'primary-widget-area' ) ) : ?> <li id="search" class="widget-container widget_search"> <?php get_search_form(); ?> </li>

<li id="archives" class="widget-container"> <h3 class="widget-title">Archives</h3> <ul> <?php wp_get_archives( 'type=monthly' ); ?> </ul> </li>

<li id="meta" class="widget-container"> <h3 class="widget-title">Meta</h3> <ul> <?php wp_register(); ?> <li><?php wp_loginout(); ?></li> <?php wp_meta(); ?> </ul> </li><?php endif; // end primary widget area ?>

Standard Loop: The Sidebar Way<?php get_header(); ?>

<?php if ( ! dynamic_loop() ) : ?> <div class="loop"> <?php if (have_posts()) : ?> <?php while (have_posts()) : the_post(); ?> <div class="loop-content"> <div <?php post_class( 'hentry' ) ?> id="post-<?php the_ID(); ?>"> <h2 class="entry-title"><?php the_title() ?></h2> <div class="entry-meta"><?php the_time('F jS, Y') ?></div>

<div class="entry-content"> <?php the_content(); ?> </div> <div class="entry-meta"><p><?php the_tags() ?></p></div> </div> </div> <?php endwhile; ?> <div class="loop-utility"> <div class="alignleft"><?php next_posts_link() ?></div> <div class="alignright"><?php previous_posts_link() ?></div> </div> <?php endif; ?> </div><?php endif; ?>

<?php get_sidebar(); ?>

<?php get_footer(); ?>

The Solution

1.Create a way for themes to allow their The Loop content to be replaced without making the template files more difficult to create or maintain.

2.Create a way for plugins to register custom loop handlers that can replace the theme's default loop.

3.Create an HTML and class standard that provides a consistent foundation that themes can style

Registering Dynamic Loop Handlers• Themes use the register_sidebar() function to tell

WordPress that a sidebar location is available. The arguments give the area a name and configure additional settings.

• What we need is a way of registering callbacks that plugins can use, not named areas that can be displayed on the back-end. We need a different solution.

Registering Dynamic Loop HandlersThe registration function should accept:

1.A function callback that decides whether or not the loop should be replaced. If the loop is to be replaced, the callback should run code that generates the new loop.

– An array of arguments to be passed to the callback.– A priority in the same fashion as actions and filters.

register_dynamic_loop_handlerfunction register_dynamic_loop_handler( $function, $args = array(), $priority = 10) { global $dynamic_loop_handlers; $dynamic_loop_handlers[$priority][] = array( $function, $args );}

Calling Dynamic Loop Handlers

Now all we need is a function that can be used in theme templates to run through the registered callbacks in order of priority.

Keeping with the dynamic_sidebar logic, the callback handler should return false if the default loop should be displayed and return true if the default loop is overridden and should not be displayed.

dynamic_loop()function dynamic_loop() { global $dynamic_loop_handlers; if ( empty( $dynamic_loop_handlers ) ) return false; ksort( $dynamic_loop_handlers ); foreach ( $dynamic_loop_handlers as $handlers ) { foreach ( $handlers as $callback ) { list( $function, $args ) = $callback; if ( is_callable( $function ) ) { $result = call_user_func_array( $function, $args ); if ( false != $result ) return true; } } return false;}

Standardized HTML and Class StructureWhile being able to replace The Loop is a big step forward, it will be of limited benefit if the new content uses a completely different structure than the theme. The result will likely be unstyled and will look out of place.

The final piece that ties everything together is a HTML and Class structure that establishes a foundation of styling that allows plugin content to look like it belongs on the site.

Checking for Standard Theme SupportThemes that implement the Standard Loop can use add_theme_support('standard-loop') to indicate that they follow the standard. This allows plugins to use current_theme_supports('standard-loop') to determine the support offered by the current theme and take action as needed if it is not available.

Possible Future Improvements

• Adding more classes that are focused on content. These would be in the vein of "Obligatory WordPress Classes" that can be found in most themes of the past few years.

• Creating a more advanced callback handler that allows for registering criteria for when the callback should be called (thus removing the decision logic from the callback handler).

Call to Action

Are you a theme developer that wants an easier way to allow plugins to provide content that styles nicely in your theme?

Are you a plugin developer that wants to have a better way to add generated content inside the theme and also wants that generated content to automatically take on theme styling?

Go to loopstandard.com and get involved

For More Information

Go to standardloop.com to get sample code and HTML/Class structures.

wordpress standardized loop api

Documents

loop function dynamic

loop content

standard loop

dynamic loop handlers

themes default loop

new loop

loop level

custom loop handlers