Config File – Customizing Colors, Fonts, and Theme Defaults
All current Mai Themes use a config based system for global settings and defaults. Any theme can override the defaults by adding a config.php file in the root directory of the theme.
Create a config.php file in your theme, if it doesn’t exist (you will need server access to do this) in wp-content/themes/mai-{active-theme-name-here}/config.php
Make sure you flush transients after creating or editing the config.php file. as most of the dynamic CSS generated via this file is stored and cached as transients in WP. An easy way to delete these transients is to open the Customizer, hit Publish/Update, and close it again.
Default Colors
This is an example of a basic config that sets default colors.
<?php
/**
* Mai Engine default settings config.
* This config sets default settings.
* Once settings are saved in the Customizer the saved values takeover.
*
* Use Mai Config Generator to generate a custom config for your site defaults.
* or see /mai-engine/config/_default.php for all config options.
*
* @package BizBudding\MaiEngine
* @link https://bizbudding.com
* @author BizBudding
* @copyright Copyright © 2020 BizBudding
* @license GPL-2.0-or-later
*/
return [
'global-styles' => [
'colors' => [
'header' => '#ffffff', // Site header background.
'background' => '#ffffff', // Body background.
'alt' => '#f8f9fa', // Background alt.
'body' => '#6c747d', // Body text color.
'heading' => '#343a40', // Heading text color.
'link' => '#007bff', // Link color.
'primary' => '#007bff', // Button primary bg color.
'secondary' => '#6c747d', // Button secondary bg color.
'black' => '#000000',
'white' => '#ffffff',
],
'custom-colors' => [
[
'color' => '#bcda83', // var(--color-custom-1).
'color' => '#9370db', // var(--color-custom-2).
],
],
],
];
Additional Colors
You can easily add additional named colors that will always be available as Customizer and block color picker values, as well as automatically generated CSS custom properties.
<?php
/**
* Mai Engine default settings config.
* This config sets default settings.
* Once settings are saved in the Customizer the saved values takeover.
*
* Use Mai Config Generator to generate a custom config for your site defaults.
* or see /mai-engine/config/_default.php for all config options.
*
* @package BizBudding\MaiEngine
* @link https://bizbudding.com
* @author BizBudding
* @copyright Copyright © 2020 BizBudding
* @license GPL-2.0-or-later
*/
return [
'global-styles' => [
'colors' => [
'header' => '#ffffff', // Site header background.
'background' => '#ffffff', // Body background.
'alt' => '#f8f9fa', // Background alt.
'body' => '#6c747d', // Body text color.
'heading' => '#343a40', // Heading text color.
'link' => '#007bff', // Link color.
'primary' => '#007bff', // Button primary bg color.
'secondary' => '#6c747d', // Button secondary bg color.
'black' => '#000000',
'white' => '#ffffff',
'accent-yellow' => '#FFCF59',
'accent-peach' => '#F5837B',
'accent-pink' => '#DD4289',
'accent-green' => '#71BE96',
'accent-blue' => '#657CDF',
'accent-teal' => '#7CC4C7',
],
'custom-colors' => [
[
'color' => '#bcda83', // var(--color-custom-1).
],
],
],
];
Default And Additional Fonts
This is an example of a basic config that is changing the default google fonts, and adds an additional font for use in custom CSS. Note: Once typography values are saved in the Customizer, the default fonts for body/heading are ignored in config.
<?php
/**
* Mai Engine default settings config.
* This config sets default settings.
* Once settings are saved in the Customizer the saved values takeover.
*
* Use Mai Config Generator to generate a custom config for your site defaults.
* or see /mai-engine/config/_default.php for all config options.
*
* @package BizBudding\MaiEngine
* @link https://bizbudding.com
* @author BizBudding
* @copyright Copyright © 2020 BizBudding
* @license GPL-2.0-or-later
*/
return [
'global-styles' => [
'fonts' => [
'body' => 'Roboto:300,500', // 300 is regular and 500 is bold.
'heading' => 'Playfair Display:400',
'accent' => 'Playfair Display:600italic', // Use in CSS via var(--accent-font-family).
],
],
];
Customize Font Weights And Variants (since v2.21.0)
These parameters allow you to set a specific variant/weight for your body and heading fonts. Make sure the font-family you choose has these font weights/variants available.
<?php
/**
* Mai Engine default settings config.
* This config sets default settings.
* Once settings are saved in the Customizer the saved values takeover.
*
* Use Mai Config Generator to generate a custom config for your site defaults.
* or see /mai-engine/config/_default.php for all config options.
*
* @package BizBudding\MaiEngine
* @link https://bizbudding.com
* @author BizBudding
* @copyright Copyright © 2020 BizBudding
* @license GPL-2.0-or-later
*/
return [
'global-styles' => [
'font-variants' => [
'body' => [
'light' => '300', // Optionally declare a light font weight. Automatically generates var(--body-font-weight-light).
'bold' => '800', // Optionally declare a specific bold font weight. If empty, a default will be used. Automatically generates var(--body-font-weight-bold).
'italic' => '400', // Default uses italic version of the body weight. Optionally declare a specific weight here.
'bolditalic' => '800', // Default uses italic version of the bold weight. Optionally declare a specific variant here.
'additional' => '', // Optionally add comma-separated list of additional body font weights to load. Uses chosen body font family.
],
'heading' => [
'light' => '', // Optionally declare a light font weight here. Automatically generates var(--heading-font-weight-light).
'bold' => '', // Optionally declare a bold weight here. Automatically generates var(--heading-font-weight-bold).
'italic' => '', // Optionally declare a italic weight here.
'bolditalic' => '', // Optionally declare a bold italic weight here.
'additional' => '', // Optionally add comma-separated list of additional heading font weights to load. Uses chosen heading font family.
],
],
],
];
Image Orientation And Aspect Ratio
This is how you can enable portrait and square image orientations and change/set the aspect ratio of all orientations. Make sure you regenerate images after changing these settings.
<?php
/**
* Mai Engine default settings config.
* This config sets default settings.
* Once settings are saved in the Customizer the saved values takeover.
*
* Use Mai Config Generator to generate a custom config for your site defaults.
* or see /mai-engine/config/_default.php for all config options.
*
* @package BizBudding\MaiEngine
* @link https://bizbudding.com
* @author BizBudding
* @copyright Copyright © 2020 BizBudding
* @license GPL-2.0-or-later
*/
return [
'image-sizes' => [
'add' => [
'landscape' => '4:3',
'portrait' => '3:4',
'square' => '1:1',
],
],
];
Customize And Add New Content Areas (formerly Template Parts)
This is how you can customize the output of existing template parts, or add completely new ones.
<?php
/**
* Mai Engine default settings config.
* This config sets default settings.
* Once settings are saved in the Customizer the saved values takeover.
*
* Use Mai Config Generator to generate a custom config for your site defaults.
* or see /mai-engine/config/_default.php for all config options.
*
* @package BizBudding\MaiEngine
* @link https://bizbudding.com
* @author BizBudding
* @copyright Copyright © 2020 BizBudding
* @license GPL-2.0-or-later
*/
return [
'template-parts' => [
// Only show Before Header template part on the homepage.
'before-header' => [
'condition' => 'is_front_page',
],
// Add new Featured Posts template part before entries on category/tag archives.
'featured-posts' => [
'hook' => 'genesis_before_content_sidebar_wrap',
'priority' => 16,
'menu_order' => 80,
'before' => '<div class="archive-featured template-part">',
'after' => '</div>',
'condition' => function() {
return is_category() || is_tag();
},
],
],
];
Conditionally Enqueue Scripts And Styles
This will load a file in /wp-content/themes/mai-{theme-name}/assets/css/single-post.css that will only load on single posts. Use the same syntax for 'scripts' instead of 'styles' as well.
<?php
/**
* Mai Engine default settings config.
* This config sets default settings.
* Once settings are saved in the Customizer the saved values takeover.
*
* Use https://bizbudding.com/mai-theme/plugins/mai-config-generator to generate a custom config for your site defaults.
* or see /mai-engine/config/_default.php for all config options.
*
* @package BizBudding\MaiEngine
* @link https://bizbudding.com
* @author BizBudding
* @copyright Copyright © 2022 BizBudding
* @license GPL-2.0-or-later
*/
return [
'styles' => [
'single-post' => [
'src' => get_stylesheet_directory_uri() . '/assets/css/single-post.css',
'condition' => function () {
return is_singular( 'post' );
},
],
],
];
Starter Config
Don’t use this as-is, just use as a starter and customize/add/remove things as needed.
Mai Theme starter config.php
<?php
/**
* Mai Engine default settings config.
* This config sets default settings.
* Once settings are saved in the Customizer the saved values takeover.
*
* Use Mai Config Generator to generate a custom config for your site defaults.
* or see /mai-engine/config/_default.php for all config options.
*
* @package BizBudding\MaiEngine
* @link https://bizbudding.com
* @author BizBudding
* @copyright Copyright © 2020 BizBudding
* @license GPL-2.0-or-later
*/
return [
// Default global styles, colors, and fonts.
'global-styles' => [
'colors' => [
'black' => '#000000',
'white' => '#ffffff',
'header' => '#ffffff', // Site header background.
'background' => '#ffffff', // Body background.
'alt' => '#f8f9fa', // Background alt.
'body' => '#6c747d', // Body text color.
'heading' => '#343a40', // Heading text color.
'link' => '#007bff', // Link color.
'primary' => '#007bff', // Button primary background color.
'secondary' => '#6c747d', // Button secondary background color.
],
'custom-colors' => [
[
'color' => '#bcda83', // var(--color-custom-1).
],
],
'fonts' => [
'body' => 'Roboto:300,500', // 300 is regular and 500 is bold.
'heading' => 'Playfair Display:400',
],
],
// Set default theme support settings.
'theme-support' => [
'add' => [
'sticky-header',
'transparent-header',
],
],
// Enable image orientations and set aspect ratio.
'image-sizes' => [
'add' => [
'landscape' => '4:3',
'portrait' => '3:4',
'square' => '1:1',
],
],
// Custom template parts.
'template-parts' => [
// Only show Before Header template part on the homepage.
'before-header' => [
'condition' => 'is_front_page',
],
// Add new Featured Posts template part before entries on category/tag archives.
'featured-posts' => [
'hook' => 'genesis_before_content_sidebar_wrap',
'priority' => 16,
'menu_order' => 80,
'before' => '<div class="archive-featured template-part">',
'after' => '</div>',
'condition' => function() {
return is_category() || is_tag();
},
],
],
];
Filter Config Items
Sometimes creating a whole config file is overkill when you only want to change small things. Here are some examples using our mai_{config-item}_config PHP filter.
These filters can be added directly to functions.php of your child theme or in a custom functionality or Code Snippets plugin.
Custom font and weight
Load a custom font family and weight, with automatic CSS custom properties.
/**
* Load custom font and weight.
*
* @param array $config The existing global styles config.
*
* @return array
*/
add_filter( 'mai_global-styles_config', function( $config ) {
/**
* Use this font in CSS:
*
* font-family: var(--heading-bold-font-family);
* font-weight: var(--heading-bold-font-weight);
*/
$config['fonts']['heading-bold'] = 'Noto Serif JP:900';
return $config;
});
Custom image orientation aspect ratios
Change landscape image aspect ratio and add portrait and square orientations.
/**
* Modify landscape image aspect ratio.
* Add portrait and/or square image orientation with specific aspect ratio.
*
* @param array $config The existing image size data.
*
* @return array
*/
add_filter( 'mai_image-sizes_config', function( $config ) {
// Change default image orientations.
$config['add']['landscape'] = '4:3';
$config['add']['portrait'] = '3:4';
$config['add']['square'] = '1:1';
// Add a new image orientation.
$config['add']['theater'] = '16:9';
return $config;
});