nagyist / kirki-helpers

Helper scripts for theme authors

kirki-helpers

Helper scripts for theme authors.

If you're starting a new theme based on underscores, we recommend you start using our fork from https://github.com/aristath/_s as it already includes both of the methods described below, and also has 2 example settings for typography.

Integrating Kirki in your themes

If you want to use Kirki in your themes, it is not recommended to include the plugin files in your theme. By recommending your users install Kirki as a plugin they can get bugfixes easier and faster. A lot of themes use TGMPA to recommend installing plugins, but if you only require Kirki then using TGMPA might be an overkill. In that case, you can use the include-kirki.php file to recommend the installation of Kirki.

When the user visits the customizer, if they don’t have Kirki installed they will see a button prompting them to install it. You can configure the description in that file and make sure you change the textdomain in that file from textdomain to the actual textdomain your theme uses.

Usage:

In your theme's functions.php file add the following line, changing '/inc/include-kirki.php' to the path where the file is located:

require_once get_template_directory() . '/inc/include-kirki.php';

Making sure that output works when Kirki is not installed

If you use the output argument in your fields, Kirki will automatically generate the CSS needed for your theme, as well as any Google-Fonts scripts. In order to make sure that user styles will continue to work even if they uninstall the Kirki plugin, you can include the class-my-theme-kirki file.

Usage:

• Rename the file to use the actual name of your theme. Example: twentysixteen-kirki.php.
• Inside the file, search for My_Theme_Kirki and replace it using your theme-name as a prefix. Example: Twentysixteen_Kirki.
• In your theme's functions.php file add the following line, changing '/inc/class-my-theme-kirki' to the path where the file is located:

require_once get_template_directory() . '/inc/class-my-theme-kirki.php';

Once you do the above, instead of using Kirki to add your config, panels, sections & fields as documented in the Kirki Documentation examples, you will have to use your own class.

Example:

Good:

Twentysixteen_Kirki::add_config( 'my_theme', array(
	'capability'    => 'edit_theme_options',
	'option_type'   => 'theme_mod',
) );

Bad:

Kirki::add_config( 'my_theme', array(
	'capability'    => 'edit_theme_options',
	'option_type'   => 'theme_mod',
) );

The Twentysixteen_Kirki class will act as a proxy to the Kirki class. If the Kirki plugin is installed, then it will be used to add your panels, sections, fields etc. However if the plugin is not installed, the Twentysixteen_Kirki will make sure that all your CSS and google-fonts will still work.