Creating Your Own Theme Plugin

How to create your own theme for QuotesDLX.

Sample Theme: a working sample theme named Forest is available to use as an example.

Initializing the Theme

You'll want to create a custom plugin if you're creating a theme. You can then share the plugin if you'd like others to have your custom Quotes theme. If you want to sell your theme, please get in touch and we can work out an agreement.

The quotes_dlx_pre_themes_loaded Action

Before the themes are loaded in via code, the action quotes_dlx_pre_themes_loaded is triggered, which allows you to "hook" in and initialize your own themes.

From there, you can use the filter quotes_dlx_themes to add in your theme callback.

Here's a sample of how to do this using a composer autoloader with a PHP namespace:

quotes-dlx-forest-theme.php

<?php
/**
 * Plugin Name:       QuotesDLX Forest Theme
 * Plugin URI:        https://dlxplugins.com/plugins/quotesdlx/
 * Description:       Green forest theme for QuotesDLX.
 * Version:           1.0.0
 * Requires at least: 5.9
 * Requires PHP:      7.2
 * Author:            MediaRon LLC
 * Author URI:        https://mediaron.com
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       quotes-dlx
 * Domain Path:       /languages
 *
 * @package QuotesDLX
 */

namespace MediaRonLLC\QuotesDLXThemes;

// Support for site-level autoloading.
if ( file_exists( __DIR__ . '/lib/autoload.php' ) ) {
	require_once __DIR__ . '/lib/autoload.php';
}

/**
 * Add your own theme to QuotesDLX.
 *
 * @param array $themes Existing themes that are to be registered.
 */
function add_themes( $themes ) {
	$themes[] = __NAMESPACE__ . '\ForestTheme\Themes_Forest';
	return $themes;
}

/**
 * Theme initialization has begun.
 */
function theme_registration_init() {

	// Init filter to add a theme to the defaults.
	add_filter( 'quotes_dlx_themes', __NAMESPACE__ . '\add_themes' );
}
add_action( 'quotes_dlx_pre_themes_loaded', __NAMESPACE__ . '\theme_registration_init' );

View this file on the Forest GitHub repository.

One important note is when you use the quotes_dlx_themes filter callback, you must provide the class file of your theme initialization file (more on that in a bit).

You can expect the following if you inspect the $themes array, and you would add or subtract from this array depending on your needs.

Array
(
    [0] => MediaRonLLC\QuotesDLX\Themes\Themes_Bubble_Gum
    [1] => MediaRonLLC\QuotesDLX\Themes\Themes_Dark
    [2] => MediaRonLLC\QuotesDLX\Themes\Themes_Light_Branded
    [3] => MediaRonLLC\QuotesDLX\Themes\Themes_Blue
    [4] => MediaRonLLC\QuotesDLX\Themes\Themes_Purple
)

After you've added in your own theme, it may look something like this:

Array
(
    [0] => MediaRonLLC\QuotesDLX\Themes\Themes_Bubble_Gum
    [1] => MediaRonLLC\QuotesDLX\Themes\Themes_Dark
    [2] => MediaRonLLC\QuotesDLX\Themes\Themes_Light_Branded
    [3] => MediaRonLLC\QuotesDLX\Themes\Themes_Blue
    [4] => MediaRonLLC\QuotesDLX\Themes\Themes_Purple
    [5] => MediaRonLLC\QuotesDLXThemes\ForestTheme\Themes_Forest
)

The above expects the Themes_Forest class to be in a ForestTheme directory. Here's a snippet of the code for reference:

/**
 * Add your own theme to QuotesDLX.
 *
 * @param array $themes Existing themes that are to be registered.
 */
function add_themes( $themes ) {
	$themes[] = __NAMESPACE__ . '\ForestTheme\Themes_Forest';
	return $themes;
}

The Theme Initialization File

All of the themes extend a base class that assists in add-on registration. All you need is to extend the class and add in your own settings.

The Theme add-on class can be found here within the QuotesDLX plugin:

├─ php                                                                                                                                                                                                       
│  ├─ Themes                                                                                                        
│  │  ├─ Themes_Addon.php

Your first task when creating the theme initialization file is to extend the Themes_Addon class.

<?php
/**
 * Initialization for the light theme.
 *
 * @package quotes-dlx
 */

namespace MediaRonLLC\QuotesDLXThemes\ForestTheme;

use MediaRonLLC\QuotesDLX\Themes\Themes_Addon as Themes_Addon;

/**
 * Holds variables for the Forest theme.
 */
class Themes_Forest extends Themes_Addon {

In this case, you'd:

1. Set up a custom namespace for your file

2. Use the QuotesDLX Themes_Addon class as a reference

3. Extend the Themes_Addon class.

Here's the full code of the sample Forest theme as far as initialization.

Follow along on GitHub.

Themes_Forest.php

<?php
/**
 * Initialization for the forest theme.
 *
 * @package quotes-dlx
 */

namespace MediaRonLLC\QuotesDLXThemes\ForestTheme;

use MediaRonLLC\QuotesDLX\Themes\Themes_Addon as Themes_Addon;

/**
 * Holds variables for the Forest theme.
 */
class Themes_Forest extends Themes_Addon {

	/**
	 * Contains an instance of this class, if available.
	 *
	 * @since  1.0.0
	 * @var    Themes_Forest $instance If available, contains an instance of this class
	 */
	private static $instance = null;

	/**
	 * Theme name.
	 *
	 * @var string $name The theme name.
	 */
	protected static $name = 'Forest';

	/**
	 * Slug for the theme.
	 *
	 * @var string $slug The theme slug.
	 */
	protected static $slug = 'forest';

	/**
	 * Category for the theme.
	 *
	 * @var string $category The theme category.
	 */
	protected static $category = 'core';

	/**
	 * Theme version.
	 *
	 * @var string $version The theme version.
	 */
	protected static $version = '1.0.0';

	/**
	 * Description for the theme.
	 *
	 * @var string $theme_description The theme description.
	 */
	protected static $theme_description;

	/**
	 * Author name.
	 *
	 * @var string $author_name The author of the theme.
	 */
	protected static $author_name = 'Ronald Huereca';

	/**
	 * Author URL.
	 *
	 * @var string $author_url URL for the author.
	 */
	protected static $author_url = 'https://mediaron.com';

	/**
	 * Large Image Width. Used for previews.
	 *
	 * @var int $full_width Image width of full-size image.
	 */
	protected static $full_width = 900;

	/**
	 * Large Image height. Used for previews.
	 *
	 * @var int $full_height Image height of full-size image.
	 */
	protected static $full_height = 500;

	/**
	 * Theme color or gradient.
	 *
	 * @var string $preview_color The theme preview color hexcode or gradient color.
	 */
	protected static $preview_gradient = 'linear-gradient(90deg, rgba(58,73,40,1) 14%, rgba(109,74,59,1) 85%);';

	/**
	 * Preview URL image for theme.
	 *
	 * @var string $preview_image_url The theme preview image URL.
	 */
	protected static $preview_image_url = '';

	/**
	 * Accent Color (hex code) for the theme.
	 *
	 * @var string $accent_color Accent color of theme.
	 */
	protected static $accent_color = '#657786';

	/**
	 * Returns an instance of this class, and stores it in the $instance property.
	 *
	 * @since  1.0.0
	 *
	 * @return ThemesForest $instance An instance of the Themes_Light_Branded class
	 */
	public static function get_instance() {

		if ( null === self::$instance ) {
			self::$instance = new Themes_Forest();
		}

		return self::$instance;
	}

	/**
	 * Get the name of the theme.
	 */
	protected static function get_name() {
		return _x( 'Forest', 'A lucious green forest theme to make your quotes stand out.', 'quotes-dlx' );
	}

	/**
	 * Get the slug of the theme.
	 */
	protected static function get_slug() {
		return self::$slug;
	}

	/**
	 * Get the preview gradient of the theme.
	 */
	protected static function get_preview_gradient() {
		return self::$preview_gradient;
	}

	/**
	 * Get the stylesheet URL.
	 */
	protected static function get_stylesheet_url() {
		return plugins_url( 'dist/theme-forest-css.css', dirname( __FILE__ ) );
	}

	/**
	 * Get the image preview URL.
	 */
	protected static function get_preview_image_url() {
		return plugins_url( 'images/forest-theme-preview.jpg', dirname( __FILE__ ) );
	}

	/**
	 * Get the category.
	 */
	protected static function get_category() {
		return self::$category;
	}

	/**
	 * Get the author.
	 *
	 * @return string author.
	 */
	protected static function get_author() {
		return self::$author_name;
	}

	/**
	 * Get the author url.
	 *
	 * @return string Author URL.
	 */
	protected static function get_author_url() {
		return self::$author_url;
	}

	/**
	 * Get the theme description.
	 *
	 * @return string Theme description.
	 */
	protected static function get_description() {
		self::$theme_description = __( 'A lucious green forest theme to make your quotes stand out. Works great on a dark or light background.', 'quotes-dlx' );
		return self::$theme_description;
	}

	/**
	 * Get the theme version.
	 *
	 * @return string Theme version.
	 */
	protected static function get_version() {
		return self::$version;
	}

	/**
	 * Get the theme image preview width.
	 *
	 * @return int Theme image width.
	 */
	protected static function get_image_width() {
		return self::$full_width;
	}

	/**
	 * Get the theme image preview height.
	 *
	 * @return int Theme image height.
	 */
	protected static function get_image_height() {
		return self::$full_height;
	}

	/**
	 * Get the colors of the theme.
	 *
	 * @return array $args {
	 *    @type string $name  Name of the color.
	 *    @type string $slug  Slug of the color.
	 *    @type string $color Hex code (including #) of the color.
	 * }
	 */
	protected static function get_colors() {
		return array(
			array(
				'name'  => __( 'Primary', 'quotes-dlx' ),
				'slug'  => 'primary',
				'color' => '#3A4928',
			),
			array(
				'name'  => __( 'Secondary', 'quotes-dlx' ),
				'slug'  => 'secondary',
				'color' => '#6d4a3b',
			),
			array(
				'name'  => __( 'Accent', 'quotes-dlx' ),
				'slug'  => 'accent',
				'color' => '#cc7000',
			),
			array(
				'name'  => __( 'Text Color', 'quotes-dlx' ),
				'slug'  => 'text-color',
				'color' => '#FFFFFF',
			),
			array(
				'name'  => __( 'Quotes Color', 'quotes-dlx' ),
				'slug'  => 'quotes-color',
				'color' => '#cebfb9',
			),
			array(
				'name'  => __( 'Border Color', 'quotes-dlx' ),
				'slug'  => 'border-color',
				'color' => '#685046',
			),
			array(
				'name'  => __( 'Inner Background Color', 'quotes-dlx' ),
				'slug'  => 'inner-background-color',
				'color' => '#FFFFFF',
			),
			array(
				'name'  => __( 'Buttons Primary Color', 'quotes-dlx' ),
				'slug'  => 'button-primary-color',
				'color' => '#6d4a3b',
			),
			array(
				'name'  => __( 'Buttons Secondary Color', 'quotes-dlx' ),
				'slug'  => 'button-secondary-color',
				'color' => '#FFFFFF',
			),
			array(
				'name'  => __( 'Button Primary Text Color', 'quotes-dlx' ),
				'slug'  => 'button-primary-text-color',
				'color' => '#FFFFFF',
			),
			array(
				'name'  => __( 'Button Secondary Text Color', 'quotes-dlx' ),
				'slug'  => 'button-secondary-text-color',
				'color' => '#6d4a3b',
			),
			array(
				'name'  => __( 'Button Border', 'quotes-dlx' ),
				'slug'  => 'button-primary-border-color',
				'color' => '#DDDDDD',
			),
			array(
				'name'  => __( 'Light', 'quotes-dlx' ),
				'slug'  => 'light',
				'color' => '#FFFFFF',
			),
			array(
				'name'  => __( 'Dark', 'quotes-dlx' ),
				'slug'  => 'dark',
				'color' => '#2B2B2B',
			),
		);
	}
}

Let's go over the important bits.

Theme Name/Label

/**
 * Theme name.
 *
 * @var string $name The theme name.
 */
protected static $name = 'Forest';

This is the name or label of your theme. You can name your theme anything you like, but be mindful that you'll need a unique slug.

Theme Slug

/**
 * Slug for the theme.
 *
 * @var string $slug The theme slug.
 */
protected static $slug = 'forest';

This will be the slug you use in your stylesheet and also for saving theme options, so be sure it's unique.

Theme Category

/**
 * Category for the theme.
 *
 * @var string $category The theme category.
 */
protected static $category = 'core';

Each theme can have a custom category. At the moment, there aren't enough themes to justify sorting, but this may be added in the future.

You can add your own custom categories by using the Themes_Addon_Categories class. For example, here is how the Core category is created.

Themes_Init.php

// Register any categories.
Themes_Addon_Categories::register(
	'Core',
	array(
		'description' => __( 'Default themes that come with the plugin', 'quotes-dlx' ),
	)
);

And the location of the categories class.

├─ php                                                                                                                                                                                                       
│  ├─ Themes                                                                                                        
│  │  ├─ Themes_Addon_Categories.php

Theme Version

Set your theme version here. This isn't being used at the moment, but it's a good practice to update your version with every theme update.

/**
 * Theme version.
 *
 * @var string $version The theme version.
 */
protected static $version = '1.0.0';

Theme Description

/**
 * Description for the theme.
 *
 * @var string $theme_description The theme description.
 */
protected static $theme_description;

You would leave this empty and use a getter to return the theme's description.

/**
 * Get the theme description.
 *
 * @return string Theme description.
 */
protected static function get_description() {
	self::$theme_description = __( 'A lucious green forest theme to make your quotes stand out. Works great on a dark or light background.', 'quotes-dlx' );
	return self::$theme_description;
}

Theme Author

Fill out your name here.

/**
 * Author name.
 *
 * @var string $author_name The author of the theme.
 */
protected static $author_name = 'Ronald Huereca';

Theme Author URL

You can fill in your website domain here.

/**
 * Author URL.
 *
 * @var string $author_url URL for the author.
 */
protected static $author_url = 'https://mediaron.com';

Preview Image Dimensions

For the preview that shows in the theme options, it is recommended to specify the exact size.

Preview Sizes: The recommended size is 900x500.

/**
 * Large Image Width. Used for previews.
 *
 * @var int $full_width Image width of full-size image.
 */
protected static $full_width = 900;

/**
 * Large Image height. Used for previews.
 *
 * @var int $full_height Image height of full-size image.
 */
protected static $full_height = 500;

Preview Gradient

A preview gradient will show up in the block editor to showcase your primary and secondary colors.

Theme Preview Gradients

/**
 * Theme color or gradient.
 *
 * @var string $preview_color The theme preview color hexcode or gradient color.
 */
protected static $preview_gradient = 'linear-gradient(90deg, rgba(58,73,40,1) 14%, rgba(109,74,59,1) 85%);';

Preview URL

You can leave this blank.

/**
 * Preview URL image for theme.
 *
 * @var string $preview_image_url The theme preview image URL.
 */
protected static $preview_image_url = '';

get_name

Use this to return a localized version of the name of the theme.

/**
 * Get the name of the theme.
 */
protected static function get_name() {
	return _x( 'Forest', 'A lucious green forest theme to make your quotes stand out.', 'quotes-dlx' );
}

get_slug

This will return the slug for the theme.

/**
 * Get the slug of the theme.
 */
protected static function get_slug() {
	return self::$slug;
}

get_preview_gradient

This will return the preview gradient set.

// Some code/**
 * Get the preview gradient of the theme.
 */
protected static function get_preview_gradient() {
	return self::$preview_gradient;
}

get_stylesheet_url

This will return the location to your CSS file for the theme.

/**
 * Get the stylesheet URL.
 */
protected static function get_stylesheet_url() {
	return plugins_url( 'dist/theme-forest-css.css', dirname( __FILE__ ) );
}

get_preview_image_url

This will return the path to the image used in the theme preview.

/**
 * Get the image preview URL.
 */
protected static function get_preview_image_url() {
	return plugins_url( 'images/forest-theme-preview.jpg', dirname( __FILE__ ) );
}

get_theme_category

This will return the theme's category.

/**
 * Get the category.
 */
protected static function get_category() {
	return self::$category;
}

get_author

This will return the theme's author.

/**
 * Get the author.
 *
 * @return string author.
 */
protected static function get_author() {
	return self::$author_name;
}

get_author_url

This will return the website for the theme's author.

/**
 * Get the author url.
 *
 * @return string Author URL.
 */
protected static function get_author_url() {
	return self::$author_url;
}

get_description

Return a translatable theme description.

/**
 * Get the theme description.
 *
 * @return string Theme description.
 */
protected static function get_description() {
	self::$theme_description = __( 'A lucious green forest theme to make your quotes stand out. Works great on a dark or light background.', 'quotes-dlx' );
	return self::$theme_description;
}

get_version

Return the theme's version.

/**
 * Get the theme version.
 *
 * @return string Theme version.
 */
protected static function get_version() {
	return self::$version;
}

get_image_width

Return the width of the image

/**
 * Get the theme image preview width.
 *
 * @return int Theme image width.
 */
protected static function get_image_width() {
	return self::$full_width;
}

get_image_height

Return the height of the image.

/**
 * Get the theme image preview height.
 *
 * @return int Theme image height.
 */
protected static function get_image_height() {
	return self::$full_height;
}

get_colors

Define your own colors, slugs, and labels for the theme.

The slug: the slug is important as a CSS variable will be created based on your theme slug and your color slug.

For example, with a color slug of "purple" and a theme slug of "forest", the following CSS variable will be created:

--qdlx-forest-purple: {your color}

You can then reference this variable in your CSS file:

blockquote { color: var( --qdlx-forest-purple, #67009C ); }

/**
 * Get the colors of the theme.
 *
 * @return array $args {
 *    @type string $name  Name of the color.
 *    @type string $slug  Slug of the color.
 *    @type string $color Hex code (including #) of the color.
 * }
 */
protected static function get_colors() {
	return array(
		array(
			'name'  => __( 'Primary', 'quotes-dlx' ),
			'slug'  => 'primary',
			'color' => '#3A4928',
		),
		array(
			'name'  => __( 'Secondary', 'quotes-dlx' ),
			'slug'  => 'secondary',
			'color' => '#6d4a3b',
		),
		array(
			'name'  => __( 'Accent', 'quotes-dlx' ),
			'slug'  => 'accent',
			'color' => '#cc7000',
		),
		array(
			'name'  => __( 'Text Color', 'quotes-dlx' ),
			'slug'  => 'text-color',
			'color' => '#FFFFFF',
		),
		array(
			'name'  => __( 'Quotes Color', 'quotes-dlx' ),
			'slug'  => 'quotes-color',
			'color' => '#cebfb9',
		),
		array(
			'name'  => __( 'Border Color', 'quotes-dlx' ),
			'slug'  => 'border-color',
			'color' => '#685046',
		),
		array(
			'name'  => __( 'Inner Background Color', 'quotes-dlx' ),
			'slug'  => 'inner-background-color',
			'color' => '#FFFFFF',
		),
		array(
			'name'  => __( 'Buttons Primary Color', 'quotes-dlx' ),
			'slug'  => 'button-primary-color',
			'color' => '#6d4a3b',
		),
		array(
			'name'  => __( 'Buttons Secondary Color', 'quotes-dlx' ),
			'slug'  => 'button-secondary-color',
			'color' => '#FFFFFF',
		),
		array(
			'name'  => __( 'Button Primary Text Color', 'quotes-dlx' ),
			'slug'  => 'button-primary-text-color',
			'color' => '#FFFFFF',
		),
		array(
			'name'  => __( 'Button Secondary Text Color', 'quotes-dlx' ),
			'slug'  => 'button-secondary-text-color',
			'color' => '#6d4a3b',
		),
		array(
			'name'  => __( 'Button Border', 'quotes-dlx' ),
			'slug'  => 'button-primary-border-color',
			'color' => '#DDDDDD',
		),
		array(
			'name'  => __( 'Light', 'quotes-dlx' ),
			'slug'  => 'light',
			'color' => '#FFFFFF',
		),
		array(
			'name'  => __( 'Dark', 'quotes-dlx' ),
			'slug'  => 'dark',
			'color' => '#2B2B2B',
		),
	);
}

You can add as little or as many colors as you would like. These colors will show up as swatches when customizing a theme's colors.

Colors Show Up When Customizing a Theme