Create WordPress theme from scratch : Part 10 – Custom Header and Background

Welcome to Part 10 of the series Create WordPress theme from scratch. In this tutorial, we will add custom header and background image to our completed theme.

If you missed the Part 9 of this series, then check it out here.

Add Custom Background

The WordPress Custom Backgrounds is a theme feature that lets the users easily customize the background color and image of the site.

To enable support for custom background images, we need to edit the theme functions file. In your functions.php file, add the following lines of code at the end of mytheme_setup function.

add_theme_support( 'custom-background', apply_filters( 'mytheme_custom_background_defaults', array(
    'default-color'    => '#ffffff'
) ) );

In the code above, we are passing the argument through a filter called mytheme_custom_background_defaults which can be used to customize the default options.

That’s all we need to add custom background support. WordPress takes care of the rest. To see custom backgrounds in action, go to Dashboard > Appearance > Customize > Background Image.

In the example above we are providing the default background color. Here is the complete list of supported arguments.

  • default-color – Default background color.
  • default-image – Default background image URL.
  • default-repeat – CSS background-repeat property value like no-repeat.
  • default-position-x – CSS background-repeat property value like center.
  • default-attachment – CSS background-attachment property value like scroll or fixed.
  • wp-head-callback – A callback function that will be attached to the wp_head action hook.
  • admin-head-callback – A callback function that will be attached to the admin_head action hook.
  • admin-preview-callback – I don’t know what this does.

Note: I have never used wp-head-callback, admin-head-callback and admin-preview-callback arguments.

Add Custom Header

By enabling support for WordPress Custom Headers users can assign a header image, an image that appears in the theme top header section (You can, of course, display it anywhere you like).

Adding support for custom headers is as easy as calling add_theme_support. Create a new file called custom-header.php in the inc directory in your theme. Inside this newly created file, paste the following lines of code.

<?php

function mytheme_add_custom_header_support() {
    add_theme_support( 'custom-header', apply_filters( 'mytheme_custom_header_args', array(
        'width'               => 1920,
        'height'              => 360,
        'flex-height'         => true,
        'wp-head-callback'    => 'mytheme_header_style',
    ) ) );
}
add_action( 'after_setup_theme', 'mytheme_add_custom_header_support' );

function mytheme_header_style() {
    if ( display_header_text() ) {
        return;
    }
    ?>
    <style type="text/css">
        .site-branding {
            margin: 0 auto 0 0;
        }

        .site-branding .site-title,
        .site-description {
            clip: rect(1px, 1px, 1px, 1px);
            position: absolute;
        }
    </style>
    <?php
}

And add the following line of code at the end of the functions file functions.php

require_once TEMPLATE_PATH . '/inc/custom-header.php';

Now, let’s see what’s going on. We start with familiar looking code

function mytheme_add_custom_header_support() {
    add_theme_support( 'custom-header', apply_filters( 'mytheme_custom_header_args', array(
        'width'               => 1920,
        'height'              => 360,
        'flex-height'         => true,
        'wp-head-callback'    => 'mytheme_header_style',
    ) ) );
}
add_action( 'after_setup_theme', 'mytheme_add_custom_header_support' );

We are adding a theme feature, so we need to use the proper hook after_setup_theme. In the call to add_theme_support, we are passing our arguments through a filter called mytheme_custom_header_args. This makes it easy to customize in a child theme or a plugin.

Custom header supports the following options.

  • default-image – Default header background image.
  • width – Background image width.
  • height – Background image height.
  • flex-height – Enable or disable flexible image height.
  • flex-width – Enable or disable flexible image width.
  • uploads – Enable or disable an admin to upload other images.
  • random-default – Enable or disable random header background images.
  • header-text – Enable or disable support for header text. What includes the header text is up to the theme author.
  • default-text-color – Default text color code.
  • wp-head-callback – A callback function that will be attached to the wp_head action hook.
  • admin-head-callback – A callback function that will be attached to the admin_head action hook.
  • admin-preview-callback – I don’t know what this does.

Personally, I never used admin-head-callback and admin-preview-callback.

In the example above, we are using the defaults arguments to set the image width to 1920px and the height to 360px. We are also enabling flexible height images.

The callback function mytheme_header_style outputs the required styles needed to hide the header text. The options to hide header text is available in Dashboard > Appearance > Site Identity.

function mytheme_header_style() {
    if ( display_header_text() ) {
        return;
    }
    ?>
    <style type="text/css">
        .site-branding {
            margin: 0 auto 0 0;
        }

        .site-branding .site-title,
        .site-description {
            clip: rect(1px, 1px, 1px, 1px);
            position: absolute;
        }
    </style>
    <?php
}

The function display_header_text returns a Boolean value – whether to display the header text. If the user decides to hide the user text, then we are simply outputting some styles that will hide the header text.

Conclusion

This concludes the tenth part of the series Create WordPress theme from scratch. In the next part of the series, we will create our own custom post type.

Canvas Vs SVG

Next Article

Things You Must Know about Canvas Vs SVG.