With Customify, developers can easily create advanced theme-specific options inside the WordPress Customizer. Using those options, a user can make presentational changes without having to know or edit the theme code.
This plugin is primarily intended to be used together with Pixelgrade themes. So the best way to get acquainted with it's capabilities is to study the way one of Pixelgrade's themes integrates with it.
Made with care by Pixelgrade
First you need to install and activate the stable version. This will always be on wordpress.org
Now go to ‘Appearance -> Customize’ menu and have fun with the new fields provided by your active theme.
The Customify $config can be filtered by any theme and this is how you do it, include this filter in your theme(probably in functions.php)
// Advice: change this function's name and make sure it is unique
add_filter('customify_filter_fields', 'make_this_function_name_unique' );
function make_this_function_name_unique( $config ) {
// usually the sections key will be here, but a check won't hurt
if ( ! isset($config['sections']) ) {
$config['sections'] = array();
}
// this means that we add a new entry named "theme_added_settings" in the sections area
$config['sections']['theme_added_settings'] = array(
'title' => 'Section added dynamically',
'settings' => array(
// this is the field id and it must be unique
'field_example' => array(
'type' => 'color', // there is a list of types below
'label' => 'Body color', // the label is optional but is nice to have one
'css' => array(
// the CSS key is the one which controls the output of this field
array(
// a CSS selector
'selector' => '#logo',
// the CSS property which should be affected by this field
'property' => 'background-color',
)
// repeat this as long as you need
array(
'selector' => 'body',
'property' => 'color',
)
)
)
)
);
// when working with filters always return filtered value
return $config;
}Customify also creates its own defaults this way. You can see that in customify/customify_config.php
Personally I like to simply copy this file in my child theme and include it in functions.php with
require 'customify_config.php'And after that the sky is the limit. I can style any elements or group of elements in the Customizer.
The intro is over let's get to some advanced stuff.
| Fields | Live Preview Support! | Description |
|---|---|---|
| Text | Yes with classes | A simple text input |
| Textarea | Yes with classes | A simple text area input |
| Ace Editor | Yes with classes | An ace editor that supports plain_text / css / html / javascript / json / markdown |
| Color | Yes | A simple color picker |
| Range | Yes | The default html5 range input |
| Font | Custom Live Preview | A complete font selector with Live Preview, google fonts, filtrable theme fonts and custom callbacks |
| Select | No | The standard HTML select |
| Radio | No | |
| Checkbox | No | |
| Upload | No | This field allows you to upload a file which you can use it later in front-end |
| Image | No | This is like the upload field, but it accepts only images |
| Date | No | |
| Pages select | No | The standard WordPress Page Select |
| Select2 | No | An awesome select |
| Presets | No | An radio input option to select a group of options (inception style ^^) |
This is the array which is processed by the customify_filter_fields filter and it contains:
- 'sections' an array with sections(each section holds an array with fields)
- 'panels' an array of panels( each panel holds an array with sections)
- 'opt-name' the option key name which will hold all these options
The css configuration can also hold a media parameter which will make the output of the CSS property, to wrap in the specified media query, for example:
'site_title_size' => array(
'type' => 'range',
'label' => 'Site Title Size',
'default' => 24,
'css' => array(
array(
'property' => 'font-size',
'selector' => '.site-title',
'media' => 'screen and (min-width: 1000px)'
)
)
)This will make the property take effect only on screens larger than 1000px, because on mobile devices you may not want a bigger logo.
Each field can take a 'callback_filter' parameter.This should be a function name which should be called when a field is changed.
For example let's take this range field:
'sidebar_width' => array(
'type' => 'range',
'label' => 'Sidebar width',
'input_attrs' => array(
'min' => 60,
'max' => 320,
'step' => 60,
),
'css' => array(
array(
'selector' => 'span.col',
'property' => 'width',
'unit' => 'px',
'callback_filter' => 'this_setting_can_call_this_function'
)
)
)Now let's create a callback which multiplies the effect of this css property Let's say that we want the sidebar to grow faster in length and double its value when the slider is changed
function this_setting_can_call_this_function( $value, $selector, $property, $unit ) {
$this_property_output = $selector . ' { '. $property .': '. ( $value * 2 ) . $unit . "; } \n";
return $this_property_output;
}HTML field | No | A field which allows you to add custom HTML in customizer and hook into it with javascript later ;)
There are a few fields which support this feature for now, but those are awesome.These fields are capable to update the previewer iframe without refreshing the iframe, the preview should be instant.
This is recommended for color fields because you won't need to stop drag-and-dropping the color select to see what color would be better.
Note
All the text fields have support for a live preview but they require an array of classes instead of the boolean true for the live parameter.
For example a fields which would provide the copyright text from footer whould be like this:
'footer_copyright' => array(
'type' => 'text',
'label' => 'Footer Copyright'
'default' => 'All contents © Pixelgrade 2011-2015'
'sanitize_callback' => 'wp_kses_post',
'live' => array( '.copyright-class' )
)For this example the element with the .copyright-class class will get the text replaced as soon as the user types a
new text. I bet this is awesome.
Along with version 1.2.3 we've added support for conditional fields. This means that you can use the show_if argument
to display a field only when another field has a certain value.
This gist shows how this can be done.
Since version 1.1.0 we added support for presets options. With this fields, you can pre-define other options. Here is and example of how to config this.
'theme_style' => array(
'type' => 'preset',
'label' => __( 'Select a style:', 'customify' ),
'desc' => __( 'Conveniently change the design of your site with built-in style presets. Easy as pie.', 'customify' ),
'default' => 'silk',
'choices_type' => 'select',
'choices' => array(
'silk' => array(
'label' => __( 'Silk', 'customify' ),
'options' => array(
'links_color' => '#FAC2A8', //second
'headings_color' => '#A84469', //main
'body_color' => '#ffffff', // -
'headings_font' => 'Playfair Display', //main
'body_font' => 'Merriweather'
)
),
'red' => array(
'label' => __( 'Urban', 'customify' ),
'options' => array(
'links_color' => 'red',
'headings_color' => 'red',
'body_color' => 'red',
'headings_font' => 'Exo',
'body_font' => 'Pacifico'
)
),
'black' => array(
'label' => __( 'Black', 'customify' ),
'options' => array(
'links_color' => '#ebebeb',
'headings_color' => '#333',
'body_color' => '#989898',
'headings_font' => 'Arvo',
'body_font' => 'Lora'
)
),
)
)The above example will output a select which will change all the fields configured in the options array.
If you don't like the select type, at choices_type you can choose between select, button and an awesome radio select which allows you to not only change the font-end options but also the preview button style.
Wanna have a preset like this?
Just add this section in your config
'presets_section' => array(
'title' => __( 'Style Presets', 'customify' ),
'options' => array(
'theme_style' => array(
'type' => 'preset',
'label' => __( 'Select a style:', 'customify' ),
'desc' => __( 'Conveniently change the design of your site with built-in style presets. Easy as pie.', 'customify' ),
'default' => 'royal',
'choices_type' => 'awesome',
'choices' => array(
'royal' => array(
'label' => __( 'Royal', 'customify' ),
'preview' => array(
'color-text' => '#ffffff',
'background-card' => '#615375',
'background-label' => '#46414c',
'font-main' => 'Abril Fatface',
'font-alt' => 'PT Serif',
),
'options' => array(
'links_color' => '#8eb2c5',
'headings_color' => '#725c92',
'body_color' => '#6f8089',
'page_background' => '#615375',
'headings_font' => 'Abril Fatface',
'body_font' => 'PT Serif',
)
),
'lovely' => array(
'label' => __( 'Lovely', 'customify' ),
'preview' => array(
'color-text' => '#ffffff',
'background-card' => '#d15c57',
'background-label' => '#5c374b',
'font-main' => 'Playfair Display',
'font-alt' => 'Playfair Display',
),
'options' => array(
'links_color' => '#cc3747',
'headings_color' => '#d15c57',
'body_color' => '#5c374b',
'page_background' => '#d15c57',
'headings_font' => 'Playfair Display',
'body_font' => 'Playfair Display',
)
),
'queen' => array(
'label' => __( 'Queen', 'customify' ),
'preview' => array(
'color-text' => '#fbedec',
'background-card' => '#773347',
'background-label' => '#41212a',
'font-main' => 'Cinzel Decorative',
'font-alt' => 'Gentium Basic',
),
'options' => array(
'links_color' => '#cd8085',
'headings_color' => '#54323c',
'body_color' => '#cd8085',
'page_background' => '#fff',
'headings_font' => 'Cinzel Decorative',
'body_font' => 'Gentium Basic',
)
),
'carrot' => array(
'label' => __( 'Carrot', 'customify' ),
'preview' => array(
'color-text' => '#ffffff',
'background-card' => '#df421d',
'background-label' => '#85210a',
'font-main' => 'Oswald',
'font-alt' => 'PT Sans Narrow',
),
'options' => array(
'links_color' => '#df421d',
'headings_color' => '#df421d',
'body_color' => '#7e7e7e',
'page_background' => '#fff',
'headings_font' => 'Oswald',
'body_font' => 'PT Sans Narrow',
)
),
'adler' => array(
'label' => __( 'Adler', 'customify' ),
'preview' => array(
'color-text' => '#fff',
'background-card' => '#0e364f',
'background-label' => '#000000',
'font-main' => 'Permanent Marker',
'font-alt' => 'Droid Sans Mono',
),
'options' => array(
'links_color' => '#68f3c8',
'headings_color' => '#0e364f',
'body_color' => '#45525a',
'page_background' => '#ffffff',
'headings_font' => 'Permanent Marker',
'body_font' => 'Droid Sans Mono'
)
),
'velvet' => array(
'label' => __( 'Velvet', 'customify' ),
'preview' => array(
'color-text' => '#ffffff',
'background-card' => '#282828',
'background-label' => '#000000',
'font-main' => 'Pinyon Script',
'font-alt' => 'Josefin Sans',
),
'options' => array(
'links_color' => '#000000',
'headings_color' => '#000000',
'body_color' => '#000000',
'page_background' => '#000000',
'headings_font' => 'Pinyon Script',
'body_font' => 'Josefin Sans',
)
),
)
),
)
)In 1.3.0 we introduced the new font selector, it works with live preview only and it has this possible configs:
'headings_font' => array(
'type' => 'font',
'label' => esc_html__( 'Headings', 'customify' ),
'desc' => esc_html__( 'o descriere', 'customify' ),
'selector' => 'h1, h2, h3, h4, .title, .sub-title',
// Set the defaults
'default' => array(
'font-family' => 'Open Sans',
'font-weight' => '400',
'font-size' => 24,
'line-height' => 1.5,
'letter-spacing' => 1,
'text-align' => 'initial',
'text-transform' => 'uppercase',
'text-decoration' => 'underline'
),
//'load_all_weights' => true,
'recommended' => $recommended_headings_fonts, // List of recommended fonts defined by theme
// Sub Fields Configuration (optional)
'fields' => array(
'font-size' => array( // Set custom values for a range slider
'min' => 10,
'max' => 40,
'step' => 1,
'unit' => 'px',
),
'line-height' => array(0, 2, 0.1, ''), // Short-hand version
'letter-spacing' => array(-1, 4, 0.1, 'em'),
'text-align' => true, // Disable sub-field (False by default)
'text-transform' => true,
'text-decoration'=> true,
),
'callback' => 'your_custom_callback_function'
),In the above example you can see the callback parameter, it supports a PHP or Javascript function which should replace the current output of the font
function your_custom_callback_function( $value, $font ) {
return $combined_css';
}
function add_javascript_callback_function() { ?>
<script>
function your_custom_callback_function( $values, field ) {
return $combined_css;
}
</script>
<?php }
add_action( 'customize_preview_init', 'add_javascript_callback_function' );Also this font selector comes with the ability to add custom fonts from a theme. If a theme comes with the name of a font and a stylesheet with its fontface it will be added as the first option of the font selector
function theme_add_customify_theme_fonts ( $fonts ) {
$fonts['Custom Font'] = array(
'family' => 'Custom Font',
'src' => get_template_directory_uri() . '/assets/fonts/custom_font/stylesheet.css',
'variants' => array( '400', '700' )
);
return $fonts;
}
add_filter( 'customify_theme_fonts', 'theme_add_customify_theme_fonts' );We know developers are a special kind of breed and they need special kinds of treats. That is why we have introduced options dedicated to them.
In the plugin's settings page (WP Dashboard > Settings > Customify) you will find a checkbox called Enable Reset Buttons that once activated will show a new Customizer section called Customify Toolbox and also introduce buttons in each section or panel configured via the plugin.
All these buttons will reset the options to their default values.
If you want to go even further, there is a nuclear option. Simply define the CUSTOMIFY_DEV_FORCE_DEFAULTS constant to true and everywhere the default value will be used. You can play with the values in the Customizer and the live preview will work, but no value gets saved in the database.
Add this in your wp-config.php file:
define( 'CUSTOMIFY_DEV_FORCE_DEFAULTS', true);GPLv2 and later, of course!
This plugin also includes the following libraries:
- Select 2 - https://select2.github.io/
- Ace Editor - https://ace.c9.io/
- React jQuery Plugin - https://github.com/natedavisolds/jquery-react