child-theme-development.md

extends	title	group	prev	next	order
docs	Child Theme Development	Extending	integrating-advanced-custom-fields	asset	2

The Tonik Starter Theme supports a standard parent-child theme workflow. However, if you would like to use same structure and functionalities as parent theme we encourage you to take a look at our child theme boilerplate.

Installation

WordPress child theme should be placed in the same wp-content/themes folder as a parent theme. Here we have to fetch our fresh starter files.

1. Creating New Child Theme

# Go to the `themes` directory of your WordPress installation.
$ cd wp-content/themes

Create project via composer create-project composer command.

$ composer create-project tonik/child-theme <theme-name>

You can also directly download or clone the repository to the wp-content/themes directory.

# Clone repository to the <theme-name> folder.
$ git clone -b master [email protected]:tonik/child-theme.git <theme-name>

2. Resolving Child Theme Dependencies

Child theme only downloads only one optional dependency, a CLI.

# Install composer dependencies.
$ composer install

3. Activate Child Theme

Now, you are ready to turn on your newly created theme. Go to the WordPress admin panel and activate the theme on Appearance > Themes page. Familiar with WP-CLI? Use theme activate command.

# Activate newly created child theme.
$ wp theme activate <theme-name>

Configuration

Starter uses special placeholder strings for various theme details and information (like name, description and project textdomain). Child Theme additionally introduces a {{ theme.parent }} placeholder for defining a folder name of the parent theme.

Initiating with CLI

Child themes can be also initialized with our CLI and fill placeholders for you. A setup wizard will guide you through the entire process.

# Run setup wizard.
$ vendor/bin/tonik

Directory Structure

Structure of a child theme is quite similar to the parent.

child-theme              # — Root of your theme
   ├── app/              # — Parent Theme application logic (overwrites parent)
   ├── child/            # — Child Theme application logic
   │   ├── Http/         # — Http layer of child theme
   │   ├── Setup/        # — Setups for child theme
   ├── build/            # — Webpack builder configuration and instruction files
   ├── bootstrap/        # — Files responsible for bootstrapping a theme
   ├── config/           # — Child Theme's Configuration files
   ├── public/           # — Front-end compiled/builded assets (don't edit)
   ├── resources/        # — Resources files
   │   ├── languages     # — Child Theme's localization files
   │   ├── templates     # — Child Theme's template files (overwrites parent)

child/

Holds child theme specific components. Files it this folder are additionally by child theme in functions.php file.

• Http - Modules responsible for registering child theme's stylesheets and javascript files
• Setup - Modules to adjust various parts of the WordPress like actions, filters or supports by a child theme

Developing

By default, child boilerplate does not come with the builder or task runner for theme's assets. However, if you need it, you can copy relevant Webpack configuration files and settings directly from a parent theme.

Overwriting Parent Files

Autoload and Template components use localize_template to include files, so parent files can be easily overwritten by a child theme. They only have to be accessible on the same path as they are in the parent.

For example, let's overwrite one of the parent template file. Assume that parent contains a footer.tpl.php file in resources/templates directory. Now to you just have to create the same file at the same file path in a child theme.

Understanding a Service Container

It's important to understand that a service container is shared across parent and child theme. Thanks to this you have access to all services defined in parent theme and you can easily use it directly in child theme files.

However, this enforces you to namespace new services defined at child level. It is recommended to prefix service names with child keyword.

theme()->bind('child.service', function() {
  // Child specific service
});

Accessing Child and Parent Theme Configs

After learning about prefixes from the previous paragraph. It is now clear that child theme configuration can be accessed at child.config service name.

// Gets child theme config values ...
$config = theme('child.config');
// ... as well as config helper function
$config = config();

A call to config service will still return a parent theme configuration values.

// Gets parent theme config values.
$config = theme('config');