Updating a Child Theme

What happens when I update a theme that uses customized
templates?
Child templates don’t work in exactly the same as child styles.
Child styles extend style rules already put in place by the parent
theme. Even if the parent gets a new, updated style.css file,
the child styles remain, and WordPress applies them on top
of the parent styles.
But page templates don’t extend parent templates, they replace
them. As soon as you add footer.php to your child theme,
WordPress starts ignoring the footer.php in the original theme.
That means that if you update the parent theme and change
the original footer.php file, no one really notices.
This is probably the safest way to handle theme updates,
because there really isn’t a way that WordPress could combine
two versions of a template. However, it means that if you
plan to customize all the templates in a theme, you probably
shouldn’t create a child theme. Instead, you may as well build
a completely separate theme of your own.

Advertisements
Updating a Child Theme

How Child Themes Work and When They Don’t

Since Child Theme Configurator was released on WordPress.org in November of 2013, thousands of users have created child themes on their WordPress sites with the free Child Theme Configurator plugin.

Having helped hundreds of users to get all kinds of themes to work, we have seen over and over again that when there is a problem, it is usually because the theme did not follow basic guidelines.

If you have tried all of the suggestions below and continue to have trouble making child themes work, download and run the WordPress Theme Check plugin and contact the theme author if it does not pass.

This tutorial boils how child themes work down to six points:

  1. A child theme is a special feature of WordPress that lets you override specific styles and functions of another theme.
  2. WordPress first checks for files in the active theme. If the active theme is using another theme as a parent, WordPress then checks for files in the parent theme (and the active theme officially becomes a “child” theme).
  3. The terms “stylesheet” and “template” have specific meanings when referring to parent or child themes.
  4. Themes and plugins should use the “wp_enqueue_scripts” action so WordPress can control the order in which stylesheets and scripts are loaded.
  5. The Active theme’s “style.css” file should be loaded last, whether or not it is used by the theme.
  6. Some themes and plugins do not follow WordPress guidelines, but there may be workarounds.

1. A child theme is a special feature of WordPress that lets you override specific styles and functions of another theme.

Both the child theme and the parent theme must be installed, and the child theme must be activated.

The “active” theme is the theme currently being used for the live WordPress site, whether or not it is a “child” theme. Being a child theme that references another “parent” theme does not mean WordPress will automatically use it as the “active” theme.

Why this affects how child themes work:

  1. A child theme does not function on its own. It requires another inactive theme to be installed to act as its “parent” theme.

2. WordPress first checks for files in the active theme, then checks for files in the parent theme.

How Child Themes Work

WordPress Basic Program Flow (click to enlarge)

In order for WordPress to be able inherit styles and functions from another “parent” theme, it needs to be able to read files from both themes, but treats the child theme as the “active” theme.

WordPress first reads the active theme’s stylesheet (style.css) to get the theme’s “header” properties. It then checks if the theme has a functions file (functions.php) and executes it if it exists.

If the theme’s “header” properties indicate another theme should be used as a parent it then looks for a functions file in the parent theme and executes it as well.

This is the key to how child themes work: two theme directories are checked for files, first the “active” or “child” directory, then the “parent” directory.

Next, WordPress determines the “template” to use based on the nature of the web site request. Once it decides the type of output to render, it first checks the active theme directory for the most appropriate “template” file.

If it does not find it there, and the active theme is a child theme, it then checks the parent theme directory for an appropriate “template” file. Read more about how WordPress determines the most appropriate “template” file for the job.

WordPress begins to render the template file, executing instructions as it goes. Each time an additional template is required, WordPress checks the theme directories, first the child, then the parent, for the most appropriate match and runs it.

Throughout this process, WordPress fires various “actions” that branch off to other sections of code. Section 4 explains how actions are used with themes to control stylesheets and scripts.

Why this affects how child themes work:

  1. WordPress will use the child version of a template if it exists. This means you can customize the child version without changing the parent version.
  2. WordPress will use the parent theme template if it does not exist in the child theme. This means you only need to create child theme templates you want to customize.
  3. The child theme runs first so you can “override” specific functions in the child theme functions file (assuming the parent functions are coded correctly, see section 6).

3. The terms “stylesheet” and “template” have specific meanings when referring to parent or child themes.
Stylesheet

We normally use the term “stylesheet” to mean “a CSS file that defines how elements should be drawn by the browser.” However, in the context of WordPress themes,“stylesheet” refers to “the active theme’s directory name inside the theme root.”

For example, if “Twenty Fifteen” is the active theme, the function get_stylesheet()would return “twentyfifteen”. get_stylesheet() always returns the active theme’s directory name inside the theme root whether or not the active theme is a child theme.

Template

We usually use the term “template” to mean “a PHP file used to render output sent to the browser.” Often a single response is the combined result of several templates.

Unfortunately, in the context of WordPress themes, “template” refers to “the theme used as a parent, or fallback theme.” It is a specific “header” property used in a theme’s style.css file. It is also what makes WordPress consider a theme to be a “child” theme.

The function get_template() returns the parent theme’s directory name inside the theme root if the active theme is a child theme, but returns the active theme’s directory name otherwise.

Read more about confusing WordPress theme function names and “header” properties.

Why this affects how child themes work:

  1. “Stylesheet” refers to the “child” or “active” theme when describing a theme directory.
  2. “Template” refers to the “parent” theme when describing a theme directory.
  3. For the purpose of this tutorial, only the terms “parent,” “child” or“active” are used to describe themes. The term “template” always refers to a PHP file used to render output to the browser, and “stylesheet”always refers to specific a CSS file.

4: Themes and plugins should use the“wp_enqueue_scripts” action to load stylesheets.

How WordPress Enqueue Scripts Action Queue Works

Simplified diagram showing the wp_enqueue_scripts action (click to enlarge)

WordPress was designed to be extended. One way it accomplishes this is through the WordPress Plugin API, using “actions.” An “action” is a queue (list) of functions to be run at a specific point in the WordPress program flow. Each action is like a miniature program that is created on-the-fly as WordPress runs.

Themes and Plugins can add functions to an action queue and they will be run in order of priority when when WordPress executes that particular action. By default, they will run in the order they were added to the queue.

The priority can be set to a specific value to place it higher or lower in the queue. This allows Themes and plugins to influence when a function runs in relation to other functions in the program flow.

The most important action when it comes to loading stylesheets and scripts is the“wp_enqueue_scripts” action. As WordPress runs, themes, plugins and other components add functions to this action so that they are all output to the browser in a controlled sequence at one time.

Using the wp_enqueue_scripts action allows a child theme to override the default styles of the theme, thereby customizing the appearance. This is explained in more detail in the next section.

Some themes still hard-code stylesheet links into the template file. As a result WordPress cannot control the order stylesheets load which leads to other issues.This is discussed in more detail in section 6.

Why this affects how child themes work:

  1. Using wp_enqueue_scripts to load stylesheets and scripts is recommended because it allows WordPress to optimize the load order and prevent conflicts.
  2. This method also allows themes and plugins to influence how stylesheets and scripts load in relation to one another.
  3. Hard-coding stylesheet links in the header template causes stylesheets to load in the wrong order (see section 6)

5. The Active theme’s “style.css” file should be loaded last, whether or not it is used by the theme.

Some themes do not use the conventional style.css file for their styles. Although this is perfectly acceptable, the theme should enqueue the active theme’s style.cssanyway to enable the styles to be customized by a child theme.

Even if a theme does not load the active style.css file, Child Theme Configurator provides ways to make it work.

What does CSS Mean?

CSS is short for “Cascading Style Sheets”, a language that defines how elements are drawn on in the browser. As CSS is read from top-to-bottom, rules “cascade” down to the rules below them, in other words, rules that are defined later “inherit” the rules defined earlier.

This also applies to multiple stylesheets as well. For example, lets assume a web page uses two stylesheets. In the HTML, suppose they are loaded like this:

<link rel="stylesheet" src="/path/to/stylesheet1.css" />
<link rel="stylesheet" src="/path/to/stylesheet2.css" />

This means that the rules in stylesheet2.css inherit the rules in stylesheet1.css. In addition, rules in stylesheet2.css take priority, or “override,” rules in stylesheet1.css.

Therefore, the rules in stylesheet2.css are the “final word” for how elements are drawn, but any rules in stylesheet1.css will be used if they are not defined in stylesheet2.css.

CSS in WordPress

How WordPress Enqueue Scripts Action Queue Works

Simplified Diagram showing how themes load stylesheets (click to enlarge)

The example above is important because in order to be able to change the rules of a style, the changed rule must load after the style being changed. (Unless you use !important, you may be thinking.)

Therefore, WordPress must be able to load first the parent styles, then the child styles, in that order, so that the CSS “cascades” correctly.

This can be accomplished several ways, but three are commonly used:

  1. The Child theme enqueues the Parent stylesheet, then the Parent theme enqueues the active (child) theme’s stylesheet. This is compatible with most themes, and is the default method used by Child Theme Configurator.
  2. The Parent theme enqueues the parent stylesheet if the active theme is a child theme, and then enqueues the active (child) theme’s stylesheet. As suggested by Justin Tadlock, this is the ideal solution, but is not used as often as it should.
  3. The Parent theme enqueues the active (child) theme’s stylesheet, which uses@import to load the parent stylesheet before loading the rest of the stylesheet. This method is no longer recommended.

Child Theme Configurator provides several options to handle loading the stylesheets.

Tutorial: Stylesheet Handling

Determining Which Stylesheet Handling Option to UseThis video tutorial shows how to determine the appropriate stylesheet handling option to use and troubleshoot common theme stylesheet issues View Video

Why is @import no longer recommended?

Linking stylesheets allows the browser to load stylesheets asynchronously (at the same time) while @import “blocks” (makes the browser wait before loading the rest of the code). This can lead to slower load times, search engine penalties and the dreadedFlash of Unstyled Content.

In 2009, Steve Souders published Don’t Use @import, which uses browser timelines to illustrate the speed differences of @import instead of or in combination with link.

Aside from that, WordPress cannot control the order stylesheets are loaded when a stylesheet imports another stylesheet. Any styles in the imported file immediately take priority over styles loaded before it and this may have unintended consequences.

However, because some themes hard-code the stylesheet link in the template file,the common practice to ensure the active stylesheet was able to override the parent stylesheet was to use @import to import it via the active stylesheet. This is why, until recently, @import was recommended for child themes.

Child Theme Configurator provides several “stylesheet handling” options to solve this problem without using @import.

Child Theme Configurator still provides option to use the older @import method, but it should only be used if absolutely necessary.

Why this affects how child themes work:

  1. Stylesheets inherit from and take priority over styles loaded before them by the browser.
  2. For a child theme to control the styles of a site, the active stylesheet must load after the other stylesheets.
  3. Child Theme Configurator provides several options for handling stylesheets depending on the way the theme is written.

6. Some themes and plugins do not follow WordPress guidelines, but there may be workarounds.

Action Queue Example

How adding actions with higher priority can change the stylesheet load order

WordPress has evolved quickly in recent years, and methods that were common practice before have been replaced by newer, better practices.

Themes that are listed in the theme repository on WordPress.orgundergo a thorough vetting process and in our experience we see the most issues with “premium” themes. Even so, any theme can have issues, and Child Theme Configurator provides ways to work around common problems.

The most common theme mistakes that prevent child themes from working:
  1. Placing the wp_head()anywhere except just before the closing </head> tag.

    Linking stylesheets or scripts after the wp_head action will almost always cause them to load in a way that no child theme or plugin can override them using actions (see wp_head() in the Codex).

    If you find yourself in this scenario, try copying the header.php to the child theme using the Files tab and manually editing it so that the wp_head() function call appears just before the </head> tag. You can then set the appropriate stylesheet handling option on the Parent/Child tab.

  2. Hard coding the stylesheet link in the template instead of usingwp_enqueue_scripts in a theme function.

    Because the linked stylesheets load before WordPress outputs the enqueued stylesheets, the child theme cannot link the parent styles ahead of the active stylesheet.

    Child Theme Configurator provides a stylesheet handling option to work around this problem. By selecting “Enqueue both parent and child stylesheets,” the child theme will first enqueue the parent stylesheet, then enqueue the active theme stylesheet later in the program flow. This allows the active theme stylesheet to override styles in the parent theme stylesheet without using @import. SeeDetermining which stylesheet handling option to use in the Child Theme Configurator documentation.

  3. Using get_template() or get_bloginfo('template_url') instead ofget_stylesheet_uri() to link the theme stylesheet.

    Even if correctly enqueued, WordPress will never load the child theme stylesheet if used as a parent theme. Use the “Enqueue child stylesheet” option in CTC to enable the child theme styles.

  4. Using a closing PHP tag (?>) at the end of a file.

    While this will not throw a fatal error, it directs anything that follows to the browser. This can lead to unexpected behavior, particularly if it occurs prior to the http header.

  5. Loading style.css before other stylesheets

    Selecting the “Enqueue parent stylesheet” option in CTC will work, but you will not be able to customize any stylesheets that load after style.css.

  6. Not loading style.css at all.

    This is easily fixed by selecting the “Enqueue child stylesheet” option in CTC to enable the child theme styles.

  7. Not wrapping functions in if !(function_exists()))

    This means the theme functions cannot be overridden by a child theme. This is not a major concern unless you plan to make significant changes to the PHP, in which case you should probably use a different theme.

Why this affects how child themes work:

  1. Some themes will not work as parent themes without modifications.
  2. Child Theme Configurator provides workarounds for many common issues with child themes.

No theme can do everything you want.

Nor should it. In our experience, trying to be “one size fits all” actually makes a theme less useful. The more features that are built into a theme, the more complicated the interface gets, the slower the site runs, and the buggier the code becomes. If your “premium” theme is larger than 5MB zipped, it may be too bloated to perform well.

A child theme allows you to start with a well designed, stable theme that is not overloaded with bells and whistles and then work in the needed features yourself with plugins. A child theme lets you create the site you want by extending an existing WordPress theme with your own personal touch.

Most importantly, a child theme does not restrict you to the few custom options the theme provides. It becomes a blank canvas on which you can paint anything you want, and Child Theme Configurator helps you make child themes work.

Resources for How Child Themes Work
How Child Themes Work and When They Don’t

How to Use Child Theme Configurator

How to Use Child Theme Configurator

FAQs

Installation and Setup
  1. To install from the Plugins Admin:
    • In the WordPress Admin, go to “Plugins > Add New.”
    • Type “child theme” in the “Search” box and click “Search Plugins.”
    • Locate “Child Theme Configurator” in the list and click “Install Now.”
  2. To install manually:
    • Download the Child Theme Configurator plugin archive.
    • In the WordPress Admin, go to “Plugins > Add New.”
    • Click the “Upload” link at the top of the page.
    • Browse your computer for the Child Theme Configurator zip archive and click “Install.”
  3. In the WordPress Admin, go to “Plugins > Installed Plugins.” Locate “Child Theme Configurator” in the list and click “Activate” (“Network Activate” first for multisite).
  4. Navigate to “Tools > Child Themes” (multisite users can also go to “Network Admin > Themes > Child Themes”).

FAQs

How to Create a Child Theme

Open the Child theme Configurator

Open the Child theme Configurator

First Time using Parent/Child Tab

First Time using Parent/Child Tab

Additional Child Theme Properties

Additional Child Theme Properties

Parent/Child Tab with existing Child Theme

Parent/Child Tab with existing Child Theme

NOTE: Only users with “install_themes” capability will have access to the Child Theme Configurator. In the WordPress admin, select “Tools > Child Themes.” Multisite users can also go to “Network Admin > Themes > Child Themes.”

  1. Select the theme

    you want to configure from the “Parent Theme” menu.

  2. Select “New” or “Existing”.
    • If there are currently no child themes available, the “Child Theme” and “Child Theme Names” will be entered for you automatically based on the parent theme selected. You may edit these if you like, but they cannot be the same as an existing theme.
    • If there are existing child themes available, there will be an additional menu labeled “Use Existing Child Theme” from which you can select, or enter a new value in the input box to create a new one.
  3. Enter a Theme Name, Theme Website, Author, Author Website, Description, Tags and Version (optional)

    for the child theme. If using an existing child theme, they will be entered automatically based on the child theme selected.

  4. Choose how WordPress should handle the parent theme stylesheet.

    For most themes, just leave the default “Enqueue parent theme.” If your child theme is not applying styles correctly, see Determining Which Stylesheet Handling Option to Use.

  5. Copy Parent Options (optional)

    If you want to maintain the same theme options as the parent theme, check “Copy Parent Theme Menus, Widgets and other Options”. Depending on the theme, some options may need to be applied using separate theme option controls. NOTE: This will overwrite any child theme options you may have already set.

  6. Save Backup (optional)

    If using an existing child theme, you can check “Backup Stylesheet”, to create a backup of the child theme stylesheet in the child theme directory.

  7. Restore from backup (optional):

    If using an existing child theme, you can choose whether to reload the current child theme stylesheet (leave unchanged), reset all values, or restore it from a backup. If there are backup files available, they will appear as radio button options.

  8. Choose additional stylesheets

    If your WordPress theme uses additional stylesheets, you can open the “Parse Additional Stylesheets” toggle and they will appear as checkbox options. Stylesheets that are being used by the parent theme should be automatically selected for you. Only select additional stylesheets you wish to customize to reduce overhead. NOTE: If the parent theme uses Bootstrap stylesheets, they will not be automatically selected. You can select Bootstrap stylesheets manually if you need to customize them, but in most cases they add unecessary overhead to the configuration data.

  9. Click “Generate/Rebuild Child Theme Files” to create your child theme.

    Please Note: This plugin makes significant modifications to your child theme, to include changing CSS, removing comments and adding php functions. If you are using an existing Child Theme please consider using the Duplicate Child Theme option before proceeding.

  10. IMPORTANT: Always test your child theme with Live Preview before activating!

FAQs

Determining Which Stylesheet Handling Option to Use

Unstyled Child Theme

Example of an unstyled child theme

For most current themes, using the default “Enqueue parent stylesheet” option works fine.

However, some themes were not written to apply child theme styles correctly. Often this will not be apparent until the theme is used as a child theme.

Child Theme Configurator provides workarounds for many scenarios by controlling the way it handles stylesheets when loading the page. A simple test can determine how the stylesheets load and which option is best for your theme.

Note: The stylesheet handling option cannot fix every issue. Some themes simply cannot be used as child themes without modifying the header.php template. SeeHow Child Themes Work and When They Don’t for more information.

Tutorial: Stylesheet Handling

Determining Which Stylesheet Handling Option to UseThis video tutorial shows how to determine the appropriate stylesheet handling option to use and troubleshoot common theme stylesheet issues View Video

Stylesheet Handling Chart

To test, set “Stylesheet handling” to “None,” click “Generate/Rebuild Child Theme Files,” then view child theme in a browser. Note the appearance and then view the page source. More details are listed below.

“Styles may not be applied correctly” warning?
Theme Appearance
Position of Child Stylesheet
Option to Use

No
Looks like parent
After other stylesheets
None

Yes or No
Looks like parent
Not Present
Enqueue Child Stylesheet

No
Unstyled
After other stylesheets
Enqueue Parent Stylesheet (default)

Yes
Unstyled
Anywhere
Enqueue both Parent and Child Stylesheets*

*Child Theme Configurator usually displays a warning next to the “Stylesheet handling” option. Use the “Enqueue both child and parent stylesheets” option. If the child theme continues to apply styles incorrectly, you may need to copy the header.php template using the Files tab and manually edit the stylesheet links.

Inspecting the page source to determine how the theme handles stylesheets:
  1. Go to the Parent/Child tab and open the “Stylesheet handling” options panel.
  2. Select “None” and click “Generate/Rebuild Child Theme Files.” This will allow you to see how the theme functions as a child theme without any modifications.
  3. When the page has refreshed, open the Child Theme menu. Click the “Live Preview” link for the child theme you are using. You can also go to Appearance > Themes and do the same thing.
  4. If your child theme looks like the “unstyled theme” image above, this means theparent stylesheet is not being loaded. This is perfectly normal.
  5. If the child theme is completely styled and looks like the parent theme, this indicates the theme is loading the parent styles even when used as a child theme.Make a mental note and continue to the next steps.
  6. Example of Child Theme page source

    Example of Child Theme page source showing active theme stylesheet appearing before other stylesheets.

    Right click inside a blank area the preview. Select This Frame > View Frame Source. A panel should open that looks like the image on the right.

  7. Verify that the active (child) theme stylesheet is being loaded. Using the browser’s find feature, type the child theme directory name followed by “style.css.” In other words, if your child theme is “Twenty Fifteen Child,” type “twentyfifteen-child/style.css” and press return.
  8. If a “styles may not be applied correctly” warning appears on the Parent/Child tab then this theme is either using a hard-coded stylesheet link or it is enqueuing it in the wrong order. This usually indicates you should use “Enqueue both Parent and Child Stylesheets” as the handling option, but may indicate other issues with the theme.
  9. If the child theme is completely styled and looks like the parent theme, but the child theme stylesheet cannot be found, then this theme is not loading the active theme’s stylesheet. either because it is using the wrong path (get_template_directory_uri()), or the author did not anticipate the use of child themes. This usually indicates you should use “Enqueue Child Stylesheet” as the handling option.
  10. Ideal stylesheet handling

    Page source showing parent and child stylesheets loading in correct order. Note that in this example, the parent style.css is not loaded but the all the necessary stylesheets are loaded by the parent theme. (Responsive Theme by Cyberchimps)

    If the page looks normal (like the parent theme) and the child stylesheet appears after any other stylesheets, then you can continue to use“None” as the handling option. This means the theme is using the best possible method for handling stylesheets and your work here is done.

  11. Typical stylesheet handling

    Page source showing typical stylesheet handling with the active stylesheet loading after the other stylesheets.

    If the page appears unstyled like the example above, and the child stylesheet is present and it appears after the other stylesheets, then the theme is using the standard method for handling stylesheets. You can use the default, “Enqueue parent stylesheet,” as the handling option.

  12. Once you determine the appropriate stylesheet handling option to use, go to the Parent/Child tab, select the new option, and click “Generate/Rebuild Child Theme Files.”

Premium and Custom Built Child Themes

Working with an existing child theme presents a number of potential challenges.

First, if the child theme was purchased from a theme vendor that subsequently publishes updates, there is no way to protect it from being overwritten when the update is installed. This effectively defeats one of the main reasons to use a child theme in the first place.

Second, modifications will be applied directly to the original child theme stylesheet, creating the risk of permanently changing the author’s design.

Both of these scenarios can be managed by creating a duplicate of the existing child theme and using Child Theme Configurator to apply changes to the new version.

Duplicating Existing Child Themes

duplicate-themeChild Theme Configurator gives you the option to duplicate an existing child theme when you “Generate/Rebuild Child Theme Files” from the Parent/Child Tab. It is only visible when you open the “Additional Fields” toggle next to the “Child Theme” option.

To duplicate the child theme, check the box and enter a “slug” for the new version. Child Theme Configurator will copy all child theme files and apply any settings you enter to new version.

Any theme updates will be applied to the original version so you may need to manually synch the two themes from time to time.

Genesis Framework Child Themes

Child Theme Configurator Pro provides specialized options for working with Genesis.


Copy Theme Options – Don’t Lose Your Hard Work!

If you have already set up widgets, menus and other custom settings, Child Theme Configurator lets you copy them to the new child theme. This is a feature that sets it apart from other child theme plugins.

Simply check “Copy Parent Theme Menus, Widgets and other Customizer Options” when you create child theme files on the Parent/Child tab. If you want to set different options you can either apply them after you activate the child theme, or by using the “Live Preview” under Appearance > Themes.

Normally, when you create child themes, WordPress generates fresh new set of theme options, including Nav Menus and other customizations like Custom header, Background and font colors, and you would have to set them up all over again.

Be aware that some options are specific to each theme, and some are specific to the parent theme only (meaning the child theme CANNOT override them). You will have to find out from the theme author which are which. See Working With Multisite WordPress for additional details about network site options.


FAQs

How to Use the CSS Editors to Customize Styles

There are several ways to identify and override parent styles. The Child Theme Configurator lets you search styles by selector and by property. If you wish to change a specific selector (e.g., h1), use the “Query/Selector” tab. If you have a specific value you wish to change site-wide (e.g., the color of the type), use the “Property/Value” tab.


Select a Query from the menu.

Select a Query from the menu.

Query/Selector CSS Editor Tab

The Query/Selector CSS Editor tab lets you find specific selectors and edit them. First, select the media query group that contains the selector you wish to edit by typing in theQuery autoselect box. Select by clicking with the mouse or by pressing the “Enter” or “Tab” keys. The base media query group is selected by default.

Choose a Selector from the menu.

Choose a Selector from the menu.

Next, find the selector by typing in the Selector autoselect box. Select by clicking with the mouse or by pressing the “Enter” or “Tab” keys.

This will load all of the properties for that selector with the Parent values on the left and the Child theme values inputs on the right. Any existing child values will be automatically populated.

There is also a Sample preview that displays the combination of Parent and Child overrides. Note that the border and background-image get special treatment.

Selector Inputs

Selector Inputs

You can force style overrides (so called “!important” flag) by checking the “!” box next to each input. Please use judiciously.

If you need to rename the selector, click “rename” and an input will appear to edit it. Note:This option is intended for new custom selectors that have no parent theme equivalent. It only renames the child theme version of the selector. If you are editing an override of an existing parent theme selector, the child selector will no longer match and will not correctly override the parent selector.

The “Order” field contains the original sequence of the selector in the parent theme stylesheet. You can change the selector cascade order by entering a lower or higher number in the “Order” field.

Click “Save” to update the child stylesheet and save your changes to the WordPress admin.


New CSS properties can be added using the Child Theme Configurator New Property menu.

New CSS properties can be added using the Child Theme Configurator New Property menu.

Add New Properties

If you wish to add additional properties to a given selector, first load the selector using the Query/Selector tab. Then find the property you wish to override by typing in the New Property autoselect box. Select by clicking with the mouse or by pressing the “Enter” or “Tab” keys. This will add a new input row to the selector inputs. Properties are written to the stylesheet in alphabetial order.

Add Fallback Values

Child Theme Configurator allows you to save multiple values for the same property. This enables “fallback” behavior for older browsers. Use the “New Property” menu to select an existing property and a new input row will be added to the page. Multiple property values are written to the stylesheet in the order they are added to the selector. To reorder, swap the values.


Enter free-form css code in the Raw CSS box.

Enter free-form css code in the Raw CSS box.

Raw CSS Editor

If you wish to add completely new selectors, or even new @media queries, you can enter free-form CSS in the “Raw CSS” textarea. Be aware that your syntax must be correct (i.e., balanced curly braces, etc.) for the parser to load the new styles. You will know it is invalid because a red “X” will appear next to the save button.

If you prefer to use shorthand syntax for properties and values instead of the inputs provided by the Child Theme Configurator, you can enter them here as well. The parser will convert your input into normalized CSS code automatically.


Select a Property from the menu.

Select a Property from the menu.

Property/Value CSS Editor Tab

The Property/Value CSS Editor tab lets you find specific values for a given property and then edit that value for individual selectors that use that property/value combination. First, find the property you wish to override by typing in theProperty autoselect box. Select by clicking with the mouse or by pressing the “Enter” or “Tab” keys.


Click Selectors to view all selectors that use the corresponding property/value.

Click Selectors to view all selectors that use the corresponding property/value.

This will load all of the unique values that exist for that property in the parent stylesheet with a Sample preview for that value. If there are values that exist in the child stylesheet that do not exist in the parent stylesheet, they will be displayed as well.

For each unique value, click the “Selectors” link to view a list of selectors that use that property/value combination, grouped by query with a Sample preview of the value and inputs for the child value. Any existing child values will be automatically populated.


Edit an individual value for each Selector.

Edit an individual value for each Selector.

Click “Save” to update the child stylesheet and save your changes to the WordPress admin.
If you want to edit all of the properties for the selector you can click the “Edit Selector” link and the selector will automatically load in the Query/Selector Tab.


Spectrum Color Picker

Spectrum Color Picker

Spectrum Color Picker

Child Theme Configurator now uses Spectrum for color inputs. In addition to showing a preview swatch, Spectrum allows you to use red-green-blue-alpha ( RGBA ) colors with transparency. Drag the bar below the color selector to adjust the transparency. Spectrum also supports named colors as well as hue-saturation-luminosity ( HSL and HSLA ) syntax. The new color syntax is applied to the style automatically.


FAQs

Using Web Fonts

Web fonts example

Web fonts example

You can link additional stylesheets and web fonts by typing @import rules into the textarea on the Web Fonts tab.

Note: Child Theme Configurator no longer writes @import rules to the stylesheet. Instead, it uses the @import keyword to identify and enqueue them in the script queue. WordPress then converts them to <link> tags in the rendered HTML.

Example:

@import url(http://fonts.googleapis.com/css?family=Oswald);

Important: do not import the parent theme stylesheet here. Use the “Parent stylesheet handling” option from the Parent/Child tab.

If you selected any stylesheets under “Parse additional stylesheets” when you created your child theme, those styles will be available to create overrides in the Child Theme stylesheet.

WordPress will automatically load the additional stylesheets when it loads the parent theme, so you do not need to add @import rules for them here.

The example shown loads a local custom stylesheet as well as font stylesheets from Google Web Fonts.


FAQs

Files Tab

Files Tab

Files Tab

Parent Templates

Copy PHP template files from the parent theme by checking the boxes and clicking “Copy Selected to Child Theme” and the templates will be added to the child theme directory.

CAUTION: If your child theme is active, the child theme version of the file will be used instead of the parent immediately after it is copied.

The functions.php file is generated separately and cannot be copied here.

Child Theme Files

Templates copied from the parent are listed here. These can be edited using the WordPress Theme Editor in the Appearance Menu. If you have saved any backups they will appear here as well.

Remove child theme files by checking the boxes and clicking “Delete Selected”.

Child Theme Images

You can upload new images using the image upload form. These images reside under the images directory in your child theme and are meant for stylesheet use only. Use the media gallery for content images.

Remove child theme images by checking the boxes and clicking “Delete Selected”.

Child Theme Screenshot

You can upload a custom screenshot for the child theme here.

The theme screenshot should be a 4:3 ratio (eg., 880px x 660px) JPG, PNG or GIF. It will be renamed screenshot.

Export Child Theme as Zip Archive

You can download your child theme for use on another WordPress site by clicking “Export”.


FAQs

Preview and Activate

IMPORTANT: Test your child theme before activating! Some WordPress themes (particularly commercial WordPress themes) do not correctly load parent template files or automatically load child theme stylesheets or php files. In the worst case they will break your website when you activate the child theme.

  1. Navigate to “Appearance > Themes” in the WordPress Admin. You will now see the new Child Theme as one of the installed Themes.
  2. Click “Live Preview” below the new Child Theme to see it in action.
  3. When you are ready to take the Child Theme live, click “Activate.”

MULTISITE USERS: Themes must be Network Enabled before you can use Live Preview with a specific Site. Go to “Themes” in the Network Admin to verify your child theme is Network Enabled.


Working With Multisite WordPress

Using Child Theme Configurator with Network Sites (Multisite WordPress) adds a level of complexity to the process because you can set up child themes from either the Network Admin or from individual sites.

WordPress Themes are shared globally by all network sites; however, each individual site has its own database tables, including customizer options, or “theme mods.” In addition, only themes that are “network enabled” are visible to the individual sites. When you create a new child theme, Child Theme Configurator automatically enables the child theme for all sites on the network so that it is visible under the Appearance > Themes admin page.

There is a difference between customizing themes (using Child Theme Configurator) and changing customizer options, or “theme mods.” Because all sites share the same network-enabled themes, any modifications you make to the child theme are applied to all the sites at the same time, whether or not you are using the Network Admin or an individual site admin.

However, when you use the customizer, widgets or menus admins, you are applying changes to a specific theme for a specific site. These changes are not applied to other sites, even if they are using the same theme.

If you check the box, “Copy Parent Theme Menus, Widgets and other Customizer Options” when creating or rebuilding a child theme, Child Theme Configurator copies only the customizer options, widgets and menus that exist in the parent theme for the current site being administered.

This can be even more confusing when using Child Theme Configurator from the Network Admin, because the “current site” is the primary site, or the site that existed before enabling Multisite WordPress.

In order for the parent theme’s options to be copied, the parent theme must be visible to the current site, and must already have options set that can be copied.Otherwise, the child theme will be created with the default options.


FAQs

Never Create A Child Theme and Activate It At The Same Time

Creating and activating a child theme with a “single click” feature or plugin can break WordPress in spectacular fashion and even disable the WordPress Admin. Learn how to fix a broken theme caused by editing a php file or using a “single click” child theme plugin.

If you do not test a child theme before activating it, you expose your website to the following risks:

  1. If a WordPress theme is not written to be used as a child theme, uses invalid include paths or contains syntax errors, WordPress will throw a fatal error (crash).
  2. If the “stylesheet” directory is used for include paths, then PHP will throw a fatal error because the file probably does not exist.
  3. If the active theme crashes, users will not be able to view your site and you will be unable to get back into the admin.

For these reasons, among others, we strongly recommend that you test child themes (or any themes, for that matter) with Live Preview before activating them.


FAQs

How to Create Child Themes After You Have Made Changes to an Existing Parent Theme

Things get a lot more complicated when you have already made significant changes to your Parent theme. You will need to move all your modifications into a child theme so that updating the parent does not wipe them out. Read through all of the steps below until you understand the process before starting.

  1. IMPORTANT: Make a backup of your customized parent theme using FTP, SSH or your Web Hosts file manager. You’ll need this if things don’t work out and you need to revert.
  2. Create a child theme from the Parent/Child Tab, but do not activate it yet. Make sure you check the “Copy Parent Theme Menus, Widgets and other Options” box.
  3. Go the the Files tab and select any parent templates you have changed from the list of “Parent Templates” and click “Copy Selected to Child Theme.” WordPress will automatically pull the the templates from the new directory when it is activated (but don’t activate it just yet).
  4. Now the tricky part — moving your modified styles to the child theme. The best way to do this is to download your modified “style.css” file from the parent and run a comparison (DIFF) against the original parent “style.css” file. Copy the differences over to a separate file. You can use Notepad++, TextWrangler or any advanced text editor to find differences between two files.

    If you do not have an advanced text editor, you will have to compare them manually. Open the modified stylesheet and manually copy/paste any selector blocks you have changed to a separate text file. A typical selector block looks like this:

    .header-image {
        margin: 0; 
    } 
    

    If any of the selector blocks are within @media query blocks, make sure you add those as well. A typical @media query block looks like this:

    @media screen and (max-width: 980px) { 
        body { 
            color: #333;
        }
    }
    

  5. Once you have all of your changed selectors in a file, copy the entire thing into the “Raw CSS” textarea box at the bottom of the Query/Selector tab. Click the “Save” button to the left of the textarea box (not the one at the top).
  6. Test the new child theme using the Live Preview. Go to Appearance > Themes and click “Live Preview” on the child themes icon. It should display all of your modifications correctly. If not, repeat step 3-5 until everything is working.
  7. Re-install the parent theme to a fresh, clean version and repeat step 6. If you notice anything wrong, you may need to investigate where you missed copying something. If necessary, revert to the backup parent theme and start over.
  8. Once everything looks good, go to Appearance > Themes and activate your new child theme. You can then make changes to the child theme without touching the parent.

FAQs

WordPress Script Queue and Script Dependencies

WordPress has a system to make sure that scripts are loaded in the correct order and that plugins are all using the same version of common libraries. This allows plugins to utilize the vast array of software available without interfering with the execution of other plugins.

In order for this system to work correctly, all plugins have to play by the same rules or conflicts will occur that can cause the plugin, and even WordPress itself, to malfunction. In many cases these bugs are very hard to find, resulting in hours of lost time by WordPress plugin and theme authors trying to help their users.

If Child Theme Configurator detects a conflict that prevents it from executing, it will display an error message that identifies the scripts so you can deactivate the offending plugin and replace it with one that uses script dependencies correctly.


Why plugins should not use their own jQuery and jQuery UI libraries

The main reason is it will break WordPress, particularly the admin. It is not a question of performance.

In his post, Don’t Dequeue WordPress jQuery, Eric Mann (StackExchange moderator) explains many of the arguments for and against replacing the WordPress local versions. Pippin Williamson (EasyDigitalDownloads founder) provides reasons why using your own jQuery is irresponsible Sarah Gooding (WPMUDEV.org) calls it a “deadly sin.”

The bottom line is that WordPress guidelines advise against it, period.

Many WordPress core features and plugins depend on the local versions that ship with WordPress to function. These are registered as “script dependencies” when the features are loaded. When a page is delivered to the browser, WordPress puts all of these dependencies in order and loads the libraries at once (load-scripts.php), before any other scripts in the queue. Any plugin that has registered a dependency will then have access to the library and will execute as expected.

When a plugin enqueues its own version of these libraries, including “content delivery network” (CDN) versions, it destroys the version that was loaded by WordPress and any objects that were created using the core version. It is essentially saying “I am more important than any other plugin and I don’t care what breaks.”

Plugins can “deregister” scripts and then “register” their own versions, but they must first ensure the entire dependency chain is unaffected and also ensure that the version they are loading is compatible with the other libraries in the WordPress core. It is a much better practice to build the plugin around the most current WordPress version and only enqueue libraries that are not available in the WordPress core. Read more about how to enqueue scripts correctly.


FAQs

Memory Considerations

Although it usually takes just a few seconds, parsing stylesheets so that they can be queried and modified using Child Theme Configurator is a memory-intensive process. Some web hosting packages do not allocate enough RAM to PHP for CTC to parse a large number of styles. We generally recommend at least 64MB for WordPress to run smoothly, however many budget hosts limit PHP to 32MB for shared accounts.

Child Theme Configurator estimates the number of styles it can process based on the available memory allocated and will stop parsing when it reaches this limit. If you are getting a notice that some stylesheets could not be parsed try deselecting them under “Parse Additional Stylesheets.”

Only select additional stylesheets that you intend to customize. Many WordPress themes include stylesheets for the admin that are never used for the public-facing site. In addition, Bootstrap stylesheets add a large number of styles (with very long selectors) that add unnecessary overhead to the configuration data.

Most of the time you can customize your WordPress theme by parsing one or two main stylesheets. Some experimentation may be required.


FAQs

File Permissions

Child Theme Configurator uses the WordPress Filesystem API to allow changes to sites that require user permission to edit files. For the majority of users on typical Web Hosts, this feature will be completely transparent.

However, because most of the functionality occurs via AJAX (background) requests, systems that require write permissions will need a way to automatically write to these files.

The plugin will automatically detect your configuration and provide a number of options to resolve this requirement. Use the links provided to find out more about the options available.

  1. Temporarily make the stylesheet writable by clicking the “Make Writable” button that changes the file permissions. You should change this back when you are finished editing for security by clicking “Make read-only” under the “Files” tab.
  2. Add your FTP/SSH credentials to the WordPress config file.
  3. With Windows IIS, you can assign WordPress to an application pool that has write permissions (Windows IIS systems).
  4. Set the stylesheet write permissions on the server manually (not recommended).
  5. Run PHP under Apache with suEXEC (contact your web host).

FAQs

Caveats
  1. IMPORTANT: Test your child theme before activating! Some WordPress themes (particularly commercial WordPress themes) do not correctly load parent template files or automatically load child theme stylesheets or php files. In the worst case they will break your website when you activate the child theme.
  2. Arbitrary comments are not supported. Providing a high level of flexibility for previewing and modifying styles requires sophisticated parsing and data structures. Maintaining comments that bound to any particular element in the stylesheet is prohibitively expensive compared to the value it would add. Although we are working to include this as an option in the future, currently all comments are stripped from the child theme stylesheet code.
  3. Legacy gradient syntax is not supported. The Child Theme Configurator plugin does not support the MS filter gradient or legacy webkit gradient. These will continue to work if they are used in the parent theme, but will not be written to the child theme stylesheet. If there is a demand, we may add it in a future release, but most users should have upgraded by now.
  4. Only two-color gradients. The Child Theme Configurator plugin is powerful, but we have simplified the gradient interface. You can use any gradient you want as long as it has two colors and no intermediate stops.
  5. No @font-face rules. The Child Theme Configurator plugin only supports @media and @import. If you need other @rules, put them in a separate stylesheet and import them into the Child Theme stylesheet.
  6. Not all CSS properties are customizable. The Child Theme Configurator plugin works with the vast majority of vendor-specific properties, however we’ve left out some of the more obscure options. As with legacy gradients, they will work, but will not be automatically enhanced by the Configurator.
  7. CSS properties are auto-discovered. The Child Theme Configurator plugin loads the properties that exist in the Parent stylesheet. You can always add new properties using the “Raw CSS” text area.

FAQs

Glossary
  • Parent Theme

    The WordPress Theme you wish to edit. WordPress first loads the Child Theme, then loads the Parent Theme. If a style exists in the Child Theme, it overrides the Parent Theme.

  • Child Theme

    New Theme based on Parent Theme. You can create any number of Child Themes from a single Parent Theme.

  • Class

    A term used to organize objects. For example, a <div> might be assigned the “blue-text” class. The stylesheet might then assign the color blue to members of the “blue-text” class. Thus, the <div> would display text as blue in the browser.

  • Selector

    One or more html elements, classes, ids or other terms used to identify groups of objects.

  • Property

    One of many standardized terms used to tell the browser how to display objects matching a given selector. Examples are color, background-image and font-size.

  • At-rule

    CSS browser instruction to extend default functionality. The Child Theme Configurator supports two At-rules:

    • @import

      Instructs the browser to load additional CSS information from an external source.

    • @media (Media Query)

      Identifies blocks of styles that are used only when certain browser characteristics are true. Examples are max-width, screen and print.

  • Override

    When a selector exists in both the Child Theme and the Parent Theme, the Child Theme takes priority over the Parent theme. This is where the Child Theme Configurator stands out: it helps you create exact overrides of selectors from the Parent Theme, eliminating hours of trial and error.

  • Important Flag

    CSS allows you to mark rules as “important,” meaning that the rule will take priority over any other selectors with the same property on the page, even higher priority rules. There may be times when this is necessary for a specific purpose, however most of the time the same result can be achieved by carefully naming selectors and adjusting their cascade order to modify inherited styles. Often using the important flag can create more problems than it solves by changing the behavior of higher priority rules.

How to Use Child Theme Configurator

Ordering Pages

Often, when you display a list of pages, you want to dictate which ones show up
first and which ones are last. You can do this by typing in a number for the Order
setting, which appears in the Page Attributes box when you create (or edit) a page.
The Order setting affects the order of your pages in two situations: when you display
pages in an automatic menu and when you display them in the Pages widget with
the “Sort by” box set to “Page order.”
Ordinarily, WordPress sets the order number of every page to 0. Technically, that
means that each page is tied for first position, and the page order setting has no
effect. But if you want to set the order (say you want “Our Story” followed by “Our
Location” followed by “Contact Us”), you’d assign these pages steadily increasing
page-order numbers (say, 0, 1, and 2). The actual numbers don’t really matter—the
important thing is how they compare. WordPress always displays larger-numbered
pages toward the bottom of the list or on the right end of a horizontal menu, with
smaller-numbered pages closer to the top of a list or to the left of a menu bar. If two
or more pages have the same order value, WordPress orders them alphabetically.

TIP If you rearrange a bunch of pages, you need to change their page-order values. The easiest way to do
that is to go to the Pages list (choose Pages→All Pages), point to a post, and click the Quick Edit link. This way,
you can quickly modify some page information, including the order, without opening the whole page for editing.
There’s another way to group pages: You can designate some as child pages that
belong to a specific parent page. (You may have used this type of organization
before, to create subcategories for your posts.) To create
this hierarchy, you set the Parent setting in the Pages Attribute box when you
create or edit the page.

The order settings create the nicely styled menu and nested list .
The menu displays subsidiary pages in submenus, while the Pages widget slightly
indents nested pages.

Life can get a bit confusing when you order and group pages. Just remember that
when WordPress orders pages, it compares only the pages at the same level. For
example, you can use the page order to adjust the position of the Assault Charges,
Drug Offenses, Family Law, and Personal Injury Defense pages with respect to one
another. However, WordPress won’t compare the order values of the Family Law
and Legal Disclaimers pages, because they aren’t at the same level and won’t ever
be shown next to each other.

Ordering Pages