Best practice way to implement custom sections into a WordPress theme

Question

I'm having trouble figuring out the best way to implement custom sections in a WordPress theme. For example I'm making a theme that will have four featured sections on the homepage. These sections will be in there own area, separate from the page content.

I know this could be done by adding four widget positions, or one widget position and making the user add four widgets. You could also add the four areas into the theme options panel, or even try and use a page builder plugin. I was wondering if anyone has any advice on which method is best and why? Or any suggestions on alternate methods?

Thanks,

David

Answer 1

The base paradigm in WordPress is The Callback Handler. Actions, filters, widgets, metaboxes and so on … everything runs by registering specific callback handlers for some triggers. This is not always the most elegant way, but the one every beginner must learn, so stick to that paradigm, whenever you’re not sure what to do.

So offer four actions:

do_action( 'home_primary_custom' );
do_action( 'home_secondary_custom_1' );
do_action( 'home_secondary_custom_2' );
do_action( 'home_secondary_custom_3' );

Then you or a third party developer can register a callback for these actions with add_action().

This could be improved: Use a prefix to prevent collisions with plugins or WordPress core changes, and run through an array to keep the code compact and readable.

$prefix = get_stylesheet();

$custom_actions = array (
    'home_primary_custom',
    'home_secondary_custom_1',
    'home_secondary_custom_2',
    'home_secondary_custom_3'
);

foreach ( $custom_actions as $custom_action )
    do_action( "$prefix_$custom_action" );

Now, this might already be too long for a plain template, so you could encapsulate the code in a custom function and register that for another custom action:

// front-page.php
do_action( get_stylesheet() . '_custom_front_actions' );

// functions.php

add_action( get_stylesheet() . '_custom_front_actions', 'custom_front_actions' );

/**
 * Execute custom front actions and print a container if there are any callbacks registered.
 *
 * @wp-hook get_stylesheet() . '_custom_front_actions'
 * @return bool
 */
function custom_front_actions()
{
    $has_callbacks  = FALSE;
    $prefix         = get_stylesheet();

    $custom_actions = array (
        'home_primary_custom',
        'home_secondary_custom_1',
        'home_secondary_custom_2',
        'home_secondary_custom_3'
    );

    // Are there any registered callbacks?
    foreach ( $custom_actions as $custom_action )
    {
        if ( has_action( "$prefix_$custom_action" ) )
        {
            $has_callbacks = TRUE;
            break;
        }
    }

    // No callbacks registered.
    if ( ! $has_callbacks )
        return FALSE;

    print '<div class="' . esc_attr( "$prefix-custom-front-box" ) . '">';

    foreach ( $custom_actions as $custom_action )
        do_action( "$prefix_$custom_action" );

    print '</div>';

    return TRUE;
}

Now you can print a custom container only if there are any callbacks registered. Third party developers can register their own callbacks or remove yours. Your front-page.php needs just one additional line of code.