WordPress Theme Creation 2: Intro to Theme Options

This tutorial follows on from where the Theme Creation 1 tutorial left off. It is now time to start doing some actual WordPress development. This is quite a long post- but stick with me

, because mastering the customizer is important for any theme developer.

Here is what we will do this time:

  1. Learn how to include stylesheets and scripts the WordPress way.
  2. Add Google fonts the correct way.
  3. Get an introduction to the basics of the Kirki plugin
  4. Create our first typography options in the customizer.
  5. Create background options in the customizer.

The design

This is the design I created for our theme:

wordpress

If you would like the layered PSD, let me know, and I will send it to you. You may use and adapt this design in any way you please.

The design uses only one font(it is a Google font): Open Sans Condensed.
The colors are: Yellow(#fdd017) for the headers and links, White(#ffffff) for paragraphs and lists and Grey(#33333) for the background
All images are courtesy of Unsplash.

It is more customary to complete the theme first, then to add the theme options. But, I am going to be doing things a bit differently in this series. I would like to introduce you to the customizer and using Kirki as soon as possible. So, we will be dealing with each section’s styles and then its options. That way, by the end of this tutorial series, you would have had enough exposure and practice to confidently create your own theme options.

Include JavaScript and CSS the correct way

We will add other scripts and stylesheets later, but we’ll start with Bootstrap and Font Awesome. For WordPress themes it is required that you download, include and enqueue your scripts and styles. This is because a CDN could be unreliable. There is no way to ensure that the CDN will always be available in future.

Download Font Awesome from here. Go down to Download and Customize and click the Download button. In the popup, click No thanks, just download Font Awesome. Then follow the steps below:

Step 1: You need to create a css folder in the root of your theme like this: Go to your server’s www directory:www/wordpress/wp-content/themes/your-theme’s name/ and make the new folder (it’s important that it is named css).
Step 2 Unzip the Font Awesome .zip.
Step 3: From the css folder inside the Font Awesome folder, copy only the font-awesome.min.css and paste it into your theme’s new css folder.
Step 4: Also copy the entire fonts folder and paste it into your theme’s root (same directory as your new css folder).
Step 5: Now, open your theme’s functions.php

Please Note: from here on, I will use my own theme’s prefix: mooi. If your theme is named differently, please remember to use your own wherever you see mooi.

Go down until you find this function:(at about line 101)

/**
 * Enqueue scripts and styles.
 */
function mooi_scripts() {
	wp_enqueue_style( 'mooi-style', get_stylesheet_uri() );

	wp_enqueue_script( 'mooi-navigation', get_template_directory_uri() . '/js/navigation.js', array(), '20151215', true );

	wp_enqueue_script( 'mooi-skip-link-focus-fix', get_template_directory_uri() . '/js/skip-link-focus-fix.js', array(), '20151215', true );

	if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
		wp_enqueue_script( 'comment-reply' );
	}
}
add_action( 'wp_enqueue_scripts', 'mooi_scripts' );

This function enqueues or our scripts and styles. It is WordPress best practice to add these files here. Hard coding to link stylesheets and scripts, like you would do in HTML is not advised in WordPress theming.

Add the line exactly as I have done below, and remember to save the document:

/**
 * Enqueue scripts and styles.
 */
function mooi_scripts() {
	wp_enqueue_style( 'mooi-style', get_stylesheet_uri() );

	// Here we enqueue Font Awesome properly
	wp_enqueue_style( 'mooi-fa-css', get_template_directory_uri() . '/css/font-awesome.min.css', array(), '' );	

	wp_enqueue_script( 'mooi-navigation', get_template_directory_uri() . '/js/navigation.js', array(), '20151215', true );

	wp_enqueue_script( 'mooi-skip-link-focus-fix', get_template_directory_uri() . '/js/skip-link-focus-fix.js', array(), '20151215', true );

	if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
		wp_enqueue_script( 'comment-reply' );
	}
}
add_action( 'wp_enqueue_scripts', 'mooi_scripts' );

Now you can go back to your theme in the browser. Right click and inspect element and look in the <head></head>. You should see you the enqueued file there. If you do not, go back and check your code again.

wordpress

Download Bootstrap from here and follow the steps below:.

Step 1: Unzip the Bootstrap .zip you just downloaded.
Step 2: From the css folder, copy bootstrap.min.css
Step 3: Paste that into your theme’s css folder.
Step 4: From the js folder, copy bootstrap.min.js
Step 5: Paste that into your theme’s js folder.
Step 6: Go back to the same function in your functions.php, and add these lines:

/**
 * Enqueue scripts and styles.
 */
function mooi_scripts() {
	wp_enqueue_style( 'mooi-style', get_stylesheet_uri() );

	// Here we enqueue Font Awesome properly
	wp_enqueue_style( 'mooi-fa-css', get_template_directory_uri() . '/css/font-awesome.min.css', array(), '' );	

	// Here we enqueue the Bootstrap style
	wp_enqueue_style( 'mooi-bootstrap-css', get_template_directory_uri() . '/css/bootstrap.min.css', array(), '' );

	// Here we enqueue the Bootstrap JavaScript
	wp_enqueue_script( 'mooi-bootstrap-js', get_template_directory_uri() . '/js/bootstrap.min.js', array(), '20151215', true );

	wp_enqueue_script( 'mooi-navigation', get_template_directory_uri() . '/js/navigation.js', array(), '20151215', true );

	wp_enqueue_script( 'mooi-skip-link-focus-fix', get_template_directory_uri() . '/js/skip-link-focus-fix.js', array(), '20151215', true );

	if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
		wp_enqueue_script( 'comment-reply' );
	}
}
add_action( 'wp_enqueue_scripts', 'mooi_scripts' );

Inspect the element in your browser again. You should see the enqueued stylesheet in the <head></head>. The script should be at the bottom, just above the closing </body> tag. If you do not see it, you need to check your code again.

Include Google fonts the correct way

Next, we want to include our theme’s default Google font.

/**
 * Enqueue scripts and styles.
 */
function mooi_scripts() {
	wp_enqueue_style( 'mooi-style', get_stylesheet_uri() );

	// Here we enqueue Font Awesome properly
	wp_enqueue_style( 'mooi-fa-css', get_template_directory_uri() . '/css/font-awesome.min.css', array(), '' );	

	// Here we enqueue the Bootstrap style
	wp_enqueue_style( 'mooi-bootstrap-css', get_template_directory_uri() . '/css/bootstrap.min.css', array(), '' );

	// Here we enqueue the Bootstrap JavaScript
	wp_enqueue_script( 'mooi-bootstrap-js', get_template_directory_uri() . '/js/bootstrap.min.js', array(), '20151215', true );

	// Here we enqueue our default Google font
	wp_enqueue_style( 'mooi-google-fonts', 'http://fonts.googleapis.com/css?family=Open+Sans+Condensed:300italic,400italic,700italic,400,700,300', false );
	
	wp_enqueue_script( 'mooi-navigation', get_template_directory_uri() . '/js/navigation.js', array(), '20151215', true );

	wp_enqueue_script( 'mooi-skip-link-focus-fix', get_template_directory_uri() . '/js/skip-link-focus-fix.js', array(), '20151215', true );

	if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
		wp_enqueue_script( 'comment-reply' );
	}
}
add_action( 'wp_enqueue_scripts', 'mooi_scripts' );

Also, as you will soon see, this theme has typography controls already created for the customizer. It is important that we do 2 things before we get to installing the Kirki plugin.

Open your style.css and go down to the Typography section, and change the font-family. Also change the colors to #fdd017 for the headers and #ffffff for the p element:

/*--------------------------------------------------------------
# Typography
--------------------------------------------------------------*/
body,
button,
input,
select,
textarea {
	font-family: 'Open Sans Condensed', sans-serif;
	font-size: 16px;
	font-size: 1rem;
	line-height: 1.5;
}

h1,
h2,
h3,
h4,
h5,
h6 {
	font-family: 'Open Sans Condensed', sans-serif;
	clear: both;
	color: #fdd017;
}

p,
dl {
	margin-bottom: 1.5em;
	color: #ffffff;
	font-family: 'Open Sans Condensed', sans-serif;
}

.cat-links,
.tags-links,
.edit-link,
.posted-on,
.byline {
	color: #999999;
}

Add these styles to the links

/*--------------------------------------------------------------
## Links
--------------------------------------------------------------*/
a {
	color: #fdd017;
}

a:visited {
	color: #fdd017;
}

a:hover,
a:focus,
a:active {
	color: #999999 !important;
	text-decoration: none !important;
}

a:focus {
	outline: 0;
}

a:hover,
a:active {
	outline: 0;

}

Most of our design’s typography styles are set now. Next we can start creating some options.

Intro to the Kirki plugin

Kirki is not a framework. It’s a toolkit that makes it easier for everyone to create a meaningful user interface. We can add configurations, fields, sections and panels to the customizer. It does not replace the Customizer API. It is just a wrapper for default WordPress methods. Its simplified syntax allows you to write more with less code.

There are 4 main Customizer objects: Panels, Sections, Settings, and Controls(fields). Settings associate UI elements (controls) with settings that are saved in the database. Sections are UI containers for controls, to improve their organization. Panels are containers for sections, allowing multiple sections to be grouped together.

Now, open your customizer.php (you will find it in the inc folder). I know you don’t know what’s going on here yet. I will explain this code in more detail in the next section, but for now, find the 'font-family' => 'Roboto', and change it to 'font-family' => 'Open Sans Condensed',. Do that in both the body-typography controls. Also uncomment the color option for the headers and add in our yellow hex value: #fdd017

/**
 * Add the body-typography control
 */
mooi_Kirki::add_field( 'mooi_theme', array(
	'type'        => 'typography',
	'settings'    => 'body_typography',
	'label'       => esc_attr__( 'Body Typography', 'mooi' ),
	'description' => esc_attr__( 'Select the main typography options for your site.', 'mooi' ),
	'help'        => esc_attr__( 'The typography options you set here apply to all content on your site.', 'mooi' ),
	'section'     => 'typography',
	'priority'    => 10,
	'default'     => array(
		'font-family'    => 'Open Sans Condensed',
		'variant'        => '400',
		'font-size'      => '16px',
		'line-height'    => '1.5',
		// 'letter-spacing' => '0',
		'color'          => '#333333',
	),
	'output' => array(
		array(
			'element' => 'body',
		),
	),
) );

/**
 * Add the body-typography control
 */
mooi_Kirki::add_field( 'mooi_theme', array(
	'type'        => 'typography',
	'settings'    => 'headers_typography',
	'label'       => esc_attr__( 'Headers Typography', 'mooi' ),
	'description' => esc_attr__( 'Select the typography options for your headers.', 'mooi' ),
	'help'        => esc_attr__( 'The typography options you set here will override the Body Typography options for all headers on your site (post titles, widget titles etc).', 'mooi' ),
	'section'     => 'typography',
	'priority'    => 10,
	'default'     => array(
		'font-family'    => 'Open Sans Condensed',
		'variant'        => '400',
		// 'font-size'      => '16px',
		// 'line-height'    => '1.5',
		// 'letter-spacing' => '0',
		'color'          => '#fdd017',
	),
	'output' => array(
		array(
			'element' => array( 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', '.h1', '.h2', '.h3', '.h4', '.h5', '.h6' ),
		),
	),
) );

If you go the the customizer now, you will see the notice that Kirki needs to be installed. Click the Install Now button.

wordpress

Once installed, you will see the Kirki options for typography with Google fonts. If you play around with it, you will see the changes in the Live Preview.

wordpress

Let’s go back to the customizer.php file and look at it in more detail. Open it in your text editor. At about line 28 you will see the code below.

/**
 * Add the theme configuration
 */
mooi_Kirki::add_config( 'mooi_theme', array(
	'option_type' => 'theme_mod',
	'capability'  => 'edit_theme_options',
) );

This is the configuration which was created for our theme. If we weren’t using this theme with Kirki already integrated, this configuration would be the first thing we would have to create. All fields that are linked to the ID of this configuration will inherit its properties.

'option_type' => 'theme_mod', : The option_type could be either theme_mod or option. Theme Modifications represent what’s available for a specific theme. WordPress saves all options managed by The Customizer as a single array in the database. Options are available to any theme and/or any plugin. In contrast to the The Customizer, WordPress saves each value as a single record in the database. So, it is generally accepted practice to use `theme_mod` for themes.

'capability' => 'edit_theme_options', : This can be any valid WordPress capability. See the Codex here for more info.

Below that you will see the typography section. Remember that a section is a wrapper for a bunch of fields. We need to create a section before we can add any fields, because we can not have orphan fields. This is the code which created the typography section:

/**
 * Add the typography section
 */
mooi_Kirki::add_section( 'typography', array(
	'title'      => esc_attr__( 'Typography', 'mooi' ),
	'priority'   => 2,
	'capability' => 'edit_theme_options',
) );

'typography' is the section ID- you can give it any name you like. We need this, because it must be referenced in all fields that belong to this section. The title is the name it will display in the customizer. 'priority' => 2, determines the position this section will have in the customizer.

Below that, you will see the 2 typography fields that we saw before. The type is important. You can read more about the different types of controls you can create in the Kirki Documentation (it would be good to familiarize yourself with all of these, so you know what is possible).
You can see that our section is referenced in the field, with this line 'section' => 'typography',. The 'settings' => 'paragraph_typography', will become important later when we use our fields in our theme template files. You will see that each field has a label, description and help text. The image below shows where each will be displayed in the customizer:

wordpress

esc_attr__ is required because it retrieves the translation of text and escapes it for safe use in an attribute. Again, you will see that fields also have priority that determines their position. Also, the typography fields specifically have default CSS values that also display in the customizer. The output indicates which elements are affected by the field.

Our first typography options

I want to change and add to these typography fields to give users more options. I want them to be able to change the font types and colors for the site-title, paragraph content, menu and other links separately. So, the first thing to do, is to change the body typography option to only apply to the paragraph and list elements. Change the field that applies to ‘body’, to look like this.

/**
 * Add the paragraph-typography control
 */
mooi_Kirki::add_field( 'mooi_theme', array(
	'type'        => 'typography',
	'settings'    => 'paragraph_typography',
	'label'       => esc_attr__( 'Paragraph Typography', 'mooi' ),
	'description' => esc_attr__( 'Select the main typography options for the paragraph text and lists on your site.', 'mooi' ),
	'help'        => esc_attr__( 'The typography options you set here apply to all the paragraph and list content on your site.', 'mooi' ),
	'section'     => 'typography',
	'priority'    => 10,
	'default'     => array(
		'font-family'    => 'Open Sans Condensed',
		'variant'        => '400',
		'font-size'      => '16px',
		'line-height'    => '1.5',
		// 'letter-spacing' => '0',
		'color'          => '#333333',
	),
	'output' => array(
		array(
			'element' => array ('p', 'li' ),
		),
	),
) );

Next, I add a typography field that only applies to the site title, at the bottom of the customizer.php.

/**
 * Add the site title control
 */
mooi_Kirki::add_field( 'mooi_theme', array(
	'type'        => 'typography',
	'settings'    => 'title_typography',
	'label'       => esc_attr__( 'Title Typography', 'mooi' ),
	'description' => esc_attr__( 'Select the typography options for your site title.', 'mooi' ),
	'help'        => esc_attr__( 'The typography options you set here apply to your site title.', 'mooi' ),
	'section'     => 'typography',
	'priority'    => 10,
	'default'     => array(
		'font-family'    => 'Open Sans Condensed',
		'variant'        => '400',
		//'font-size'      => '16px',
		'line-height'    => '1.5',
		// 'letter-spacing' => '0',
		'color'          => '#fdd017',
	),
	'output' => array(
		array(
			'element' => array( '.site-title a'),
		),
	),
) );

Then, I add the typography control that applies to only the menu.

/**
 * Add the navigation links control
 */
mooi_Kirki::add_field( 'mooi_theme', array(
	'type'        => 'typography',
	'settings'    => 'navigation_typography',
	'label'       => esc_attr__( 'Navigation Typography', 'mooi' ),
	'description' => esc_attr__( 'Select the typography options for your menu .', 'mooi' ),
	'help'        => esc_attr__( 'The typography options you set here apply to your menu.', 'mooi' ),
	'section'     => 'typography',
	'priority'    => 10,
	'default'     => array(
		'font-family'    => 'Open Sans Condensed',
		'variant'        => '400',
		//'font-size'      => '16px',
		'line-height'    => '1.5',
		// 'letter-spacing' => '0',
		'color'          => '#fdd017',
	),
	'output' => array(
		array(
			'element' => array( '.main-navigation a'),
		),
	),
) );

And lastly, I add the control that applies to regular links.

/**
 * Add the links control
 */
mooi_Kirki::add_field( 'mooi_theme', array(
	'type'        => 'typography',
	'settings'    => 'links_typography',
	'label'       => esc_attr__( 'Links Typography', 'mooi' ),
	'description' => esc_attr__( 'Select the typography options for your links.', 'mooi' ),
	'help'        => esc_attr__( 'The typography options you set here apply to your links.', 'mooi' ),
	'section'     => 'typography',
	'priority'    => 10,
	'default'     => array(
		'font-family'    => 'Open Sans Condensed',
		'variant'        => '400',
		//'font-size'      => '16px',
		'line-height'    => '1.5',
		// 'letter-spacing' => '0',
		'color'          => '#fdd017',
	),
	'output' => array(
		array(
			'element' => array( 'a' ),
		),
	),
) );

You might think it’s overkill, but I want my users to have as much control as possible. Now, you can go play around with it in the customizer. Make sure that every change you make is applied, otherwise, check your code again. The crazyiness below proves that users will already have the ability to make their theme unique (even if it makes no sense) by just changing font types and colors.

wordpress

Create background options in the customizer

Next, I want to give the users background options.The customizer comes with some existing options here: colors, header image and background image. I would like us to remove those options and create our own single Backgrounds panel. Open your customizer.php and add the three lines I added below inside the mooi_customize_register function.

/**
 * Add postMessage support for site title and description for the Theme Customizer.
 *
 * @param WP_Customize_Manager $wp_customize Theme Customizer object.
 */
function mooi_customize_register( $wp_customize ) {
	$wp_customize->get_setting( 'blogname' )->transport         = 'postMessage';
	$wp_customize->get_setting( 'blogdescription' )->transport  = 'postMessage';
	$wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';

	// we add the code below to remove these sections
	$wp_customize->remove_section( 'colors');
	$wp_customize->remove_section( 'header_image');
	$wp_customize->remove_section( 'background_image');
}
add_action( 'customize_register', 'mooi_customize_register' );

wordpress

You will see that the default background-color for the whole design is #333333. Again, in the interest of giving users as much customization freedom as possible, we will give them the options to change the header-, footer- and body-background.

To do this, this is the structure we are going to create:
-> A panel called Backgrounds
——–> A section called Header Background
—————->A field to add a header image or header background color
——–> A section called Body Background
—————->A field to add a body image or body background color
——–> A section called Footer Background
—————->A field to add a footer image or footer background color

It is now time to create our first panel. Add this code to the bottom of customizer.php

/**
 * Add the Background panel
 */
mooi_Kirki::add_panel( 'backgrounds', array(
	'priority'    => 10,
	'title'       => esc_attr__( 'Backgrounds', 'mooi' ),
) );

This panel will not display in your customizer yet, since it is useless without sections and fields, so let’s add our 3 sections as discussed.

/**
 * Add the header background section
 */
mooi_Kirki::add_section( 'header_background', array(
	'title'      => esc_attr__( 'Header Background', 'mooi' ),
	'priority'   => 2,
	'capability' => 'edit_theme_options',
	'panel'       => 'backgrounds',
) );

/**
 * Add the body background section
 */
mooi_Kirki::add_section( 'body_background', array(
	'title'      => esc_attr__( 'Body Background', 'mooi' ),
	'priority'   => 2,
	'capability' => 'edit_theme_options',
	'panel'       => 'backgrounds',
) );

/**
 * Add the footer background section
 */
mooi_Kirki::add_section( 'footer_background', array(
	'title'      => esc_attr__( 'Footer Background', 'mooi' ),
	'priority'   => 2,
	'capability' => 'edit_theme_options',
	'panel'       => 'backgrounds',
) );

Now for the fun part! Let’s add the fields. The code should seem slightly familiar to you by now. Compared to our typography controls, there is nothing drastically different in these controls. One thing to note: default color is set to our theme #333333, but just beneath that we also give users the option to add an image, so they can choose. If they set an image, it will override the default color.

/**
 * Add the header background control
 */
mooi_Kirki::add_field( 'mooi_theme', array(
    'type'        => 'background',
    'settings'    => 'header_background',
    'label'       => esc_attr__( 'Choose your header background', 'mooi' ),
    'description' => esc_attr__( 'The header background you specify here will apply to the header area, including your menus and your branding.', 'mooi' ),
    'section'     => 'header_background',
    'default'     => array(
        'color'    => '#333333',
        'image'    => '',
        'repeat'   => 'no-repeat',
        'size'     => 'cover',
        'attach'   => 'fixed',
        'position' => 'left-top',
    ),
    'priority'    => 10,
    'output'      => '#masthead'
) );
/**
 * Add the main background control
 */
mooi_Kirki::add_field( 'mooi_theme', array(
    'type'        => 'background',
    'settings'    => 'main_background',
    'label'       => esc_attr__( 'Choose your main background', 'mooi' ),
    'description' => esc_attr__( 'The background you specify here will apply to the main part of your page, where your content will be.', 'mooi' ),
    'section'     => 'body_background',
    'default'     => array(
        'color'    => '#333333',
        'image'    => '',
        'repeat'   => 'no-repeat',
        'size'     => 'cover',
        'attach'   => 'fixed',
        'position' => 'left-top',
    ),
    'priority'    => 10,
    'output'      => '#content'
) );
/**
 * Add the footer background control
 */
mooi_Kirki::add_field( 'mooi_theme', array(
    'type'        => 'background',
    'settings'    => 'footer_background',
    'label'       => esc_attr__( 'Choose your footer background', 'mooi' ),
    'description' => esc_attr__( 'The background you specify here will apply to the footer of your theme.', 'mooi' ),
    'section'     => 'footer_background',
    'default'     => array(
        'color'    => '#333333',
        'image'    => '',
        'repeat'   => 'no-repeat',
        'size'     => 'cover',
        'attach'   => 'fixed',
        'position' => 'left-top',
    ),
    'priority'    => 10,
    'output'      => '#colophon'
) );

Cool stuff! You should be able to see your panel, sections and fields now.

wordpress

And you can play around with them

wordpress

Great stuff! Hopefully, you now have an idea of how easy it is to use Kirki, and you already imagining the possibilities for your future themes. We still have a long way to go, but we’ve made a good start. This is what we’ll be focussing on next time:

  1. Style the header.
  2. Learn how to add logo options to the customizer.
  3. Create the footer
  4. Add 3 widget-ready areas to the footer.

Until then,

Happy coding!

Leave a Reply

Your email address will not be published. Required fields are marked *