• Stars
    star
    258
  • Rank 158,189 (Top 4 %)
  • Language
    PHP
  • Created over 10 years ago
  • Updated over 6 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Customizer Library

Customizer Library

A helpful library for working with the WordPress customizer.

About

The customizer allows WordPress developers to add options for themes and plugins, but it should be easier to work with. This library abstracts out some of the complexity.

Instead of adding options to the $wp_customize object directly, developers can just define an array of controls and sections and pass it to the Customizer_Library class.

To see how this works in practice, please see the Customizer Library Demo theme.

The Customizer Library adds sections, settings and controls to the customizer based on the array that gets passed to it. There is default sanitization for all options (though you're still welcome to pass a sanitize_callback). All options are also saved by default as theme_mods (though look for a future update to make this more flexible).

At the moment there is only one custom control (for textarea), but look for additional controls as the library matures.

The Customizer Library includes additional classes and helper functions for creating inline styles and loading Google fonts. These functions and classes were developed by The Theme Foundry for their theme Make and I've found them quite useful in my own projects. However, I'm considering moving them into seperate modules in order to make the core library as focused as possible. Feedback on this is welcome.

Installation

The Customizer Library can be included in your own projects git submodule if you'd like to be able to pull down changes. To include it in your own projects the same way, navigate to the directory and use:

git submodule add [email protected]:devinsays/customizer-library customizer-library

Options

The Customizer Library currently supports these options:

  • Checkbox
  • Select
  • Radio
  • Upload
  • Image
  • Color
  • Text
  • URL
  • Range
  • Textarea
  • Select (Typography)

Sections

Sections are convenient ways to group controls in the customizer.

Customizer Sections can be defined like this:

// Example Section

$sections[] = array(
	'id' => 'example', // Required
	'title' => __( 'Example Section', 'textdomain' ), // Required
	'priority' => '30', // Optional
	'description' => 'Example description', // Optional
	'panel' => 'panel_id' // optional, and it requires WP >= 4.0
);

Panels

Panels are a convenient way to group your different sections.

Here's an example that adds a panel, a section to the panel, and then a text option to that section:

// Panel Example
$panel = 'panel';

$panels[] = array(
	'id' => $panel,
	'title' => __( 'Panel Examples', 'demo' ),
	'priority' => '100'
);

$section = 'panel-section';

$sections[] = array(
	'id' => $section,
	'title' => __( 'Panel Section', 'demo' ),
	'priority' => '10',
	'panel' => $panel
);

$options['example-panel-text'] = array(
	'id' => 'example-panel-text',
	'label'   => __( 'Example Text Input', 'demo' ),
	'section' => $section,
	'type'    => 'text',
);

The Customizer_Library uses the core function $wp_customize->add_panel( $id, $args ); to add panels, and all the same $args are available. See codex.

Text

$options['example-text'] = array(
	'id' => 'example-text',
	'label'   => __( 'Example Text Input', 'textdomain' ),
	'section' => $section,
	'type'    => 'text',
);

URL

$options['example-url'] = array(
	'id' => 'example-url',
	'label'   => __( 'Example URL Input', 'textdomain' ),
	'section' => $section,
	'type'    => 'url',
);

Checkbox

$options['example-checkbox'] = array(
	'id' => 'example-checkbox',
	'label'   => __( 'Example Checkbox', 'textdomain' ),
	'section' => $section,
	'type'    => 'checkbox',
	'default' => 0,
);

Select

$choices = array(
	'choice-1' => 'Choice One',
	'choice-2' => 'Choice Two',
	'choice-3' => 'Choice Three'
);

$options['example-select'] = array(
	'id' => 'example-select',
	'label'   => __( 'Example Select', 'textdomain' ),
	'section' => $section,
	'type'    => 'select',
	'choices' => $choices,
	'default' => 'choice-1'
);

Drop Down Pages

$options['example-dropdown-pages'] = array( 'id' => 'example-dropdown-pages', 'label' => __( 'Example Drop Down Pages', 'textdomain' ), 'section' => $section, 'type' => 'dropdown-pages', 'default' => '' );


### Radio

~~~php
$choices = array(
	'choice-1' => 'Choice One',
	'choice-2' => 'Choice Two',
	'choice-3' => 'Choice Three'
);

$options['example-radio'] = array(
	'id' => 'example-radio',
	'label'   => __( 'Example Radio', 'textdomain' ),
	'section' => $section,
	'type'    => 'radio',
	'choices' => $choices,
	'default' => 'choice-1'
);

Upload

$options['example-upload'] = array(
	'id' => 'example-upload',
	'label'   => __( 'Example Upload', 'demo' ),
	'section' => $section,
	'type'    => 'upload',
	'default' => '',
);

Color

$options['example-color'] = array(
	'id' => 'example-color',
	'label'   => __( 'Example Color', 'demo' ),
	'section' => $section,
	'type'    => 'color',
	'default' => $color // hex
);

Textarea

$options['example-textarea'] = array(
	'id' => 'example-textarea',
	'label'   => __( 'Example Textarea', 'demo' ),
	'section' => $section,
	'type'    => 'textarea',
	'default' => __( 'Example textarea text.', 'demo'),
);

Select (Typography)

$options['example-font'] = array(
	'id' => 'example-font',
	'label'   => __( 'Example Font', 'demo' ),
	'section' => $section,
	'type'    => 'select',
	'choices' => customizer_library_get_font_choices(),
	'default' => 'Monoton'
);

Range

$options['example-range'] = array(
	'id' => 'example-range',
	'label'   => __( 'Example Range Input', 'demo' ),
	'section' => $section,
	'type'    => 'range',
	'input_attrs' => array(
        'min'   => 0,
        'max'   => 10,
        'step'  => 1,
        'style' => 'color: #0a0',
	)
);

Content

$options['example-content'] = array(
	'id' => 'example-content',
	'label' => __( 'Example Content', 'textdomain' ),
	'section' => $section,
	'type' => 'content',
	'content' => '<p>' . __( 'Content to output. Use <a href="#">HTML</a> if you like.', 'textdomain' ) . '</p>',
	'description' => __( 'Optional: Example Description.', 'textdomain' )
);

Pass $options to Customizer Library

After all the options and sections are defined, load them with the Customizer Library:

// Adds the sections to the $options array
$options['sections'] = $sections;

$customizer_library = Customizer_Library::Instance();
$customizer_library->add_options( $options );

Demo

A full working example can be found here: https://github.com/devinsays/customizer-library-demo/blob/master/inc/customizer-options.php

Styles

The Customizer Library has a helper class to output inline styles. This code was originally developed by The Theme Foundry for use in Make. To see how it works, see "inc/styles.php".

CSS selector(s) and value are passed to Customizer_Library_Styles class like this:

Customizer_Library_Styles()->add( array(
	'selectors' => array(
		'.primary'
	),
	'declarations' => array(
		'color' => $color
	)
) );

Media Queries

Media queries can also be be used with Customizer_Library_Styles. Here's an example for outputting logo-image-2x on high resolution devices.

$setting = 'logo-image-2x';
$mod = get_theme_mod( $setting, false );

if ( $mod ) {

	Customizer_Library_Styles()->add( array(
		'selectors' => array(
			'.logo'
		),
		'declarations' => array(
			'background-image' => 'url(' . $mod . ')'
		),
		'media' => '(-webkit-min-device-pixel-ratio: 1.3),(-o-min-device-pixel-ratio: 2.6/2),(min--moz-device-pixel-ratio: 1.3),(min-device-pixel-ratio: 1.3),(min-resolution: 1.3dppx)'
	) );

}

Fonts

The Customizer Library has a helper functions to output font stacks and load inline fonts. This code was also developed by The Theme Foundry for use in Make. You can see an example of font enqueing in "inc/mods.php":

function demo_fonts() {

	// Font options
	$fonts = array(
		get_theme_mod( 'primary-font', customizer_library_get_default( 'primary-font' ) ),
		get_theme_mod( 'secondary-font', customizer_library_get_default( 'secondary-font' ) )
	);

	$font_uri = customizer_library_get_google_font_uri( $fonts );

	// Load Google Fonts
	wp_enqueue_style( 'demo_fonts', $font_uri, array(), null, 'screen' );

}
add_action( 'wp_enqueue_scripts', 'demo_fonts' );

Fonts can be used in inline styles like this:

// Primary Font
$setting = 'primary-font';
$mod = get_theme_mod( $setting, customizer_library_get_default( $setting ) );
$stack = customizer_library_get_font_stack( $mod );

if ( $mod != customizer_library_get_default( $setting ) ) {

	Customizer_Library_Styles()->add( array(
		'selectors' => array(
			'.primary'
		),
		'declarations' => array(
			'font-family' => $stack
		)
	) );

}

Change Log

Development

  • Enhancement: Content option (for help text, HTML output, etc.)

1.3.0

  • Enhancement: Add text input option
  • Enhancement: Sort system fonts and webfonts within dropdown
  • Enhancement: Add Panels Support, from WP 4.0
  • Enhancement: Add support for "url" type
  • Enhancement: Add support for "range" type
  • Enhancement: Add support for "dropdown-pages" type
  • Update: Change how setting parameters are added

1.2.0

  • Enhancement: Allow setting parameters
  • Update: Refactor interface loop

1.1.0

  • Bugfix: customizer.js enqueue relative to library
  • Enhancement: Use new textarea control from core

1.0.0

  • Public Release

More Repositories

1

options-framework-plugin

An Options Panel Framework to help speed theme development.
PHP
838
star
2

options-framework-theme

An Options Panel Framework to help speed theme development.
PHP
757
star
3

flutter_todo

Example Flutter to-do app that uses a REST API.
Dart
191
star
4

portfolio-post-type

A WordPress plugin that creates a Portfolio post type.
PHP
154
star
5

laravel-react-bootstrap

Example to-do app (including auth) built with Laravel 8 and React.
PHP
145
star
6

team-post-type

Some boilerplate post type code.
PHP
122
star
7

portfolio-press

A WordPress theme for artists and designers to showcase their work.
CSS
62
star
8

better-blockquotes

A plugin for improving the blockquote button in the WordPress editor.
PHP
57
star
9

customizer-library-demo

Demo for the Customizer Library project.
PHP
54
star
10

thematic-options

A theme options framework for WordPress.
PHP
53
star
11

documentation-post-type

Created a WordPress custom post type for product documentation.
PHP
40
star
12

platform

A base theme designed for development workflow.
PHP
37
star
13

event-posts

A small plugin that creates and event post type and meta boxes
PHP
37
star
14

woocommerce-coupon-restrictions

Experiments with coupon restrictions.
PHP
29
star
15

edd-theme-updater

Sample theme updater for EDD.
PHP
25
star
16

angular-experiments

Collection of experiments as I work through learning Angular + the JSON API for WordPress.
PHP
23
star
17

foghorn

Foghorn is a minimalist WordPress theme built off the foundation of Twenty Eleven.
PHP
19
star
18

edd-account-helpers

Example code for building a dashboard are with Easy Digital Downloads.
PHP
16
star
19

visual

Visual is a dark minimalist WordPress theme for displaying photos and images.
CSS
14
star
20

options-framework-theme-demos

Demos for Options Framework.
PHP
13
star
21

customizer-background-control

Registers a new custom customizer control for backgrounds.
PHP
12
star
22

no-slug-portfolio-post-types

Tiny little plugin to remove the slug from portfolio post types.
PHP
11
star
23

history-future

Snappy WordPress Ajax Theme for Byron Reece
PHP
11
star
24

auto-set-featured-image

Auto set a featured image in WordPress.
PHP
11
star
25

light

A lightweight WordPress blog theme
PHP
9
star
26

post-author-optimization-for-woocommerce

Stores the customer_user for WooCommerce orders and subscriptions in the post_author column of posts table.
PHP
9
star
27

woocommerce-customer-source

Learn where your WooCommerce customers are coming from.
PHP
8
star
28

flutter_okta

Proof of concept Flutter + Okta integration.
Dart
8
star
29

edd-free-license-generator

Allows users to bypass checkout page when downloading a specific product. Should be used in conjuction with the EDD Software Licensing Plugin.
PHP
8
star
30

laravel-react-material

Example Material UI to do app that integrates with a Laravel REST API.
JavaScript
6
star
31

post-loaded-avatars

A simple WordPress plugin to post load avatar images.
PHP
6
star
32

gad7

A mobile app built on Flutter to help track anxiety.
Dart
5
star
33

instant-content

WordPress plugin for purchasing Demand Media content.
PHP
3
star
34

salaryinflation

Calculate an inflation adjusted salary.
JavaScript
3
star
35

portfolio-plus

Commercial version of Portfolio Press
PHP
2
star
36

date_picker_input

Example of a date picker input in Flutter.
Dart
2
star
37

twentyfifteen-srcset

Experiments with Twenty Fifteen and Responsive Images
PHP
2
star
38

postlistr-plugin

Trying to learn some backbone.
PHP
1
star
39

wpe-sync

Bash script for syncing in WP Engine environment.
Shell
1
star
40

flutterfort

Gatsby.js site for Flutter blog.
JavaScript
1
star
41

woocommerce-wholesale-role-restriction

This extension prevents customers with a "wholesale" role from using coupons on the site.
PHP
1
star
42

percentchange

Percent Change Calculator
HTML
1
star
43

woocommerce-friendbuy

Plugin allows easy integration between Friendbuy and WooCommerce.
PHP
1
star
44

edd-facebook-analytics

Adds Facebook tracking to your website for conversion metrics and ad re-marketing.
JavaScript
1
star
45

MeasureVW.js

Simple developer tool for measuring elements in vw units.
JavaScript
1
star
46

fallback-languages

Better translation loading in WordPress.
PHP
1
star