gamajo / theme-toolkit

Building blocks for developing a config-based theme

Theme Toolkit

Building blocks to develop a config-based WordPress theme.

When building a theme, wouldn't it be nice to separate out the implementation-specific config, from the reusable logic? This is the premise upon which the Using a Config to Write Reusable Code series articles are written, and which this package enables.

It uses the BrightNucleus\Config package for managing the configuration objects, while the classes in this package consumes them to provide an easy way to:

• Register and enqueue Google Fonts.
• Add and remove image sizes.
• Unset (inherited) page templates.
• Add theme support.
• Register and unregister widget areas (sidebars).
• Register and unregister widgets.
• Manage script and style dependencies.

Installation

Requires PHP 7.1.

In a terminal, browse to the directory with your theme in and then:

composer require gamajo/theme-toolkit

You can then autoload (PSR-4) or require the files as needed.

Usage

See the example-config.php. This would typically live in your theme, at config/defaults.php.

Your theme would then contain a function, in the functions.php, to pull in this config, and load up the individual components, which are referred to as bricks:

// functions.php

namespace Gamajo\ExampleTheme;

use BrightNucleus\Config\ConfigFactory;
use Gamajo\ThemeToolkit\Dependencies;
use Gamajo\ThemeToolkit\GoogleFonts;
use Gamajo\ThemeToolkit\ImageSizes;
use Gamajo\ThemeToolkit\Templates;
use Gamajo\ThemeToolkit\ThemeSupport;
use Gamajo\ThemeToolkit\Widgets;
use Gamajo\ThemeToolkit\WidgetAreas;
use Gamajo\ThemeToolkit\ThemeToolkit;

defined( 'ABSPATH' ) || exit;

if ( file_exists( __DIR__ . '/vendor/autoload.php' ) ) {
	require __DIR__ . '/vendor/autoload.php';
}


add_action( 'after_setup_theme', __NAMESPACE__ . '\setup' );
/**
 * Theme setup.
 *
 * Compose the theme toolkit bricks.
 */
function setup() {
	$config_file = __DIR__ . '/config/defaults.php';
	$config = ConfigFactory::createSubConfig( $config_file, 'Gamajo\ExampleTheme' );

	// These bricks are run in admin and front-end.
	$bricks = [
		Dependencies::class,
		ImageSizes::class,
		Templates::class,
		ThemeSupport::class,
		Widgets::class,
		WidgetAreas::class,
	];

	// Apply logic in bricks, with configuration defined in config/defaults.php.
	ThemeToolkit::applyBricks($config, ...$bricks);


	if ( ! is_admin() ) {
		// Only front-end bricks.
		$bricks = [
			GoogleFonts::class,
		];

		ThemeToolkit::applyBricks($config, ...$bricks);

	}
}

The 'Gamajo\ExampleTheme' string matches the two keys in the return at the bottom of the config file. Change this in the config and the function to be your company name and theme name.

You don't have to use all of the bricks in this package; pick and choose.

You can add your own bricks to your theme (in your src/ or similar directory), and then make use of them in the function above.

For Genesis Framework users, see the Genesis Theme Toolkit which has extra bricks for registering layouts, breadcrumbs args etc.

Change Log

Please see CHANGELOG.md.

Credits

Built by Gary Jones
Copyright 2017 Gamajo

theme-toolkit's Issues

Only variables should be passed by reference, ThemeToolkit.php line 62.

When WP_DEBUG is set true, an error is thrown by the line:

$baseClassName = array_pop(explode('\\', $brick));

Because we're passing explode() to array_pop (array &$array).

PR to follow.

Add Dependencies brick which uses brightnucleus/dependencies

Does it make sense to add a Dependencies brick which implements brightnucleus/dependencies and allows config based management of scripts and styles?

I have done so in reworking my Genesis Starter Theme, example: https://github.com/craigsimps/genesis-starter-theme/blob/develop/src/Dependencies.php

Brick: Load textdomain

Needs to default to load_theme_textdomain(), but have some way for a config to specify that it should be load_child_theme_textdomain().

Also, needs actual textdomain to use, and path to the languages directory (default to get_stylesheet_directory() . '/languages').

Use of UNSET class constant in Templates.php

The name of class constant UNSET was changed to UNREGISTER in f4418b8, however, it is still referenced in Templates.php#L63.

Support optional context with Dependencies

Amend Dependencies class, so that it looks for the presence of context key in the config, and if so, passes it through, instead of a null.

See https://github.com/brightnucleus/dependencies#custom-context-data

Brick: Customizer sections, controls and settings

Need the ability to set and use a config for sections, controls, and settings.

section:

• section id
• section args
  • title
  • priority
  • description (optional)
  • active_callback (optional)

control:

• control id (string or class reference)
• control args
  • label (optional)
  • description (optional)
  • section
  • priority (optional)
  • type
  • settings (optional)
  • choices/height/width (optional)

setting:

• setting id
• setting args
  • default (value)
  • type (optional)
  • capability (optional)
  • theme_supports (optional)
  • transport (optional)
  • sanitize_callback (optional)
  • sanitize_js_callback (optional)

Note that "Themes should not register their own panels in most cases". Anything that feature-full that is worthy of a panel should be added via a plugin, not a theme.

Package name spelled incorrectly in file header comment.

File headers include the line:

@package   Gamajo\ThemeTookit

Note the spelling of Toolkit as Tookit.

Add custom header support

_s generates the following:

<?php
/**
 * Sample implementation of the Custom Header feature
 *
 * You can add an optional custom header image to header.php like so ...
 *
	<?php the_header_image_tag(); ?>
 *
 * @link https://developer.wordpress.org/themes/functionality/custom-headers/
 *
 * @package Incipio
 */

/**
 * Set up the WordPress core custom header feature.
 *
 * @uses incipio_header_style()
 */
function incipio_custom_header_setup() {
	add_theme_support( 'custom-header', apply_filters( 'incipio_custom_header_args', array(
		'default-image'          => '',
		'default-text-color'     => '000000',
		'width'                  => 1000,
		'height'                 => 250,
		'flex-height'            => true,
		'wp-head-callback'       => 'incipio_header_style',
	) ) );
}
add_action( 'after_setup_theme', 'incipio_custom_header_setup' );

if ( ! function_exists( 'incipio_header_style' ) ) :
	/**
	 * Styles the header image and text displayed on the blog.
	 *
	 * @see incipio_custom_header_setup().
	 */
	function incipio_header_style() {
		$header_text_color = get_header_textcolor();

		/*
		 * If no custom options for text are set, let's bail.
		 * get_header_textcolor() options: Any hex value, 'blank' to hide text. Default: add_theme_support( 'custom-header' ).
		 */
		if ( get_theme_support( 'custom-header', 'default-text-color' ) === $header_text_color ) {
			return;
		}

		// If we get this far, we have custom styles. Let's do this.
		?>
		<style type="text/css">
		<?php
		// Has the text been hidden?
		if ( ! display_header_text() ) :
		?>
			.site-title,
			.site-description {
				position: absolute;
				clip: rect(1px, 1px, 1px, 1px);
			}
		<?php
			// If the user has set a custom color for the text use that.
			else :
		?>
			.site-title a,
			.site-description {
				color: #<?php echo esc_attr( $header_text_color ); ?>;
			}
		<?php endif; ?>
		</style>
		<?php
	}
endif;

That could be broken up into config (first bit), and a brick (second bit). The config may also allow for defining the front-end classes for site-title and site-description, if needed.

Decision needed: Whether to read from general theme-support config or support a separate array / brick.