Toolbox of the Smart WordPress Developer: Vafpress

Remember the times when we needed to create Options pages for our themes? Of course you do, because we still need them! When the Customizer of WordPress falls short in handling you're theme's functionality, you'll need to create an extra Options page to serve a better experience for your users.

While it's always an option to create these Options panels from scratch, it's better to use the already-invented wheels. In this part of the "Toolbox of the Smart WordPress Developer" series, we're going to go through Vafpress, a solid WordPress theme options framework for your next theme project.

When the Customizer Isn't Enough

Time for some controversy: I don't think the Customizer is ready for themes—yet.

Even though I admit that the Customizer is simply an awesome tool, I can also see that it just isn't qualified to serve all the functionality of even a simple multi-purpose theme. I know, I know, multi-purpose themes are soulless, capitalist themes that ruin the world of WordPress... or are they? I mean, I admit that it would be better if single-purpose themes were more popular, but can we ignore the fact that multi-purpose themes are the very first choice of most design agencies, freelancers and even newbie WordPress users who want to build a website for their businesses?

At the end of the day, we have to ask ourselves in order to understand the need for theme option frameworks against the Customizer: WordPress for WordPress's sake, or WordPress for people's sake? While I support WordPress becoming more and more standardized in various aspects, I also think that we can't ignore the demands of the user community of WordPress. After all, if we developers ignored users' demands, WordPress wouldn't have grown as big as it is now.

Plus, I don't think the Customizer would be enough for single-purpose themes either (yet). We don't even have a standardized and centralized way to build content parts (like sliders, menus and such) yet, and whatever you say against this, WordPress users do (and will always) need a single interface to control their themes.

I'm keeping this section short, because the topic is Vafpress as a WordPress developer tool and I can talk about "the Customizer versus theme option frameworks" for another thousand words. But don't let me cutting it short keep you from commenting: I'd love to hear your take on this!

Using Vafpress With Your Theme

Needless to say at this point, but it's customary to open up each section with a simple introduction: Vafpress is a theme options framework. And a very good one, I should say. Created by Vafour, an Indonesian web development team, Vafpress claims that building a WordPress theme has never been easier and faster.

Simply download Vafpress from its official download page or its GitHub repository, and let's quickly get to the good parts.

Getting to Know the Control Fields of Vafpress

As of the day that I'm writing this tutorial, Vafpress has 19 control fields divided into two categories called "Fields" and "Multifields".

textbox: Generates a text input.
textarea: Generates a textarea field.
toggle: Generates a yes/no toggle.
slider: Generates a range slider.
upload: Generates an upload field using WordPress Media Manager.
color: Generates a color picker.
date: Generates a date picker.
codeeditor: Generates a code editor.
wpeditor: Generates a WYSIWYG editor.
fontawesome: Generates an icon picker using Font Awesome.
notebox: Generates a field that you can use to inform your theme's users.
html: Allows you to display custom HTML code.
select: Generates a simple <select> field.
multiselect: Generates a multiple dropdown menu.
checkbox: Generates a group of checkboxes.
checkimage: Generates a group of selectable images, working like checkboxes.
radiobutton: Generates a group of radio buttons.
radioimage: Generates a group of selectable images, working like radio boxes.
sorter: Generates a sortable multiselect field.

It wouldn't feel right if I didn't finish this section without an example—let's do a single, simple one. The following lines of code create a Color Picker field:

<?php

'fields' => array(
	array(
		'type'			=> 'color',
		'name'			=> 'example_color_picker',
		'label'			=> 'Color Picker',
		'description'	=> 'Set a color for your headings here!',
		'default'		=> 'rgba(255,255,255,.75)',
		'format'		=> 'hex',
	),
	array(
		// another field
	),
)

?>

Creating Options Pages and Filling Them With Control Fields

This part might be tricky at first, but it has a smooth learning curve.

The options panel that we can create with Vafpress consists of a couple of building blocks:

Fields—we've just gone over these.
Sections keep the control fields.
Menus or submenus keep the sections.
The options page builder builds the options panel.

Let's start off by seeing the construction of the "options page builder":

<?php

function my_options() {
	
	// initialize the object
	$theme_options = new VP_Option( array(
		// set it to TRUE if you don't want the option values to be saved (in your theme demo, perhaps)
		'is_dev_mode'		   => false,
		// the name for the settings in the database
		'option_key'			=> 'vpt_option',
		// the slug of your options page
		'page_slug'			 => 'vpt_option',
		// path to the template file or the array
		'template'			  => get_template_directory() . '/options-template.php',
		// parent menu page
		'menu_page'			 => 'themes.php',
		// decides whether to automatically name menus or not
		'use_auto_group_naming' => true,
		// show (by default) or hide the "Export/Import" page
		'use_exim_menu'		 => true,
		// minimum user role to view the options panel
		'minimum_role'		  => 'edit_theme_options',
		// type of the layout (fixed by default)
		'layout'				=> 'fixed',
		// title of the options page
		'page_title'			=> __( 'Theme Options', 'vp_textdomain' ),
		// title of the main menu item
		'menu_label'			=> __( 'Theme Options', 'vp_textdomain' ),
	));

}

// hook it to the after_setup_theme action
add_action( 'after_setup_theme', 'my_options' )

?>

A good thing about the "options page builder" is that you can point to a separate file where you keep all your menus (and sections inside the menus, and fields inside the sections). In the example above, we pointed to a template file called options-template.php. Let's see what to fill that file with as well:

<?php

return array(
    'title' => __('Vafpress Option Panel', 'vp_textdomain'),
    'logo'  => '',
	'menus' => array(
		array(
			'title' => __('Special Controls', 'vp_textdomain'),
			'name' => 'menu_2',
			'icon' => '/icon/special.png',
			'controls' => array(
				// ... collection of Sections and or Control Fields ...
			),
		),
	)
);

?>

If you want, you can do some "nested menus" too:

<?php

return array(
    'title' => __('Vafpress Option Panel', 'vp_textdomain'),
    'logo'  => '',
	'menus' => array(
		array(
			'title' => __('Standard HTML Controls', 'vp_textdomain'),
			'name' => 'menu_1',
			'icon' => 'font-awesome:icon-magic',
			'menus' => array(
				array(
					'title' => __('Regular', 'vp_textdomain'),
					'name' => 'submenu_1',
					'icon' => 'font-awesome:icon-th-large',
					'controls' => array(
						// ... collection of Sections and or Control Fields ...
					),
				),
				array(
					'title' => __('Image', 'vp_textdomain'),
					'name' => 'submenu_2',
					'icon' => 'font-awesome:icon-picture',
					'controls' => array(
						// ... collection of Sections and or Control Fields ...
					),
				),
			),
		),
	)
);

?>

And inside the array of the 'controls' arguments, we use something like the following:

<?php

'controls' => array(
    array(
        'title' => __('TextBox and TextArea', 'vp_textdomain'),
        'name' => 'section_1',
        'description' => __('TextBox and TextArea Showcase', 'vp_textdomain'),
        'fields' => array(
            // ... collection of control fields ...
        ),
    ),
)

?>

Again, this could take a little practice at first, but it's a walk in the park once you get used to it.

Achieving Even More With Vafpress

All these features should be enough for a framework like Vafpress, but Vafpress doesn't stop there—it has a couple more tricks up its sleeve:

Theme Boilerplate: Vafpress has a theme boilerplate for people who want to try it out by seeing a live example on their servers.
Metaboxes: Vafpress lets you create metaboxes for post entry screens, so you can provide even more functionality with your theme. Check out the documentation here.
Shortcode Generator: Vafpress has a built-in shortcode generator (documented here), so you can help your users insert your theme's shortcodes with ease.
Dynamic Data Sources: Ever need to populate some of your control fields with existing data? Vafpress lets you do that as well. On this page, you can learn how to bind dynamic data into your "multifields".
Interactions for Control Fields: You might want to create control fields that depend on each other, or bind their values together. With the control fields interaction functionality, it's possible to do both.

Wrapping Up for Today

There's a lot you can achieve with Vafpress—more than we've covered here in this tutorial. Be sure to check out the Vafpress documentation to learn more about it.

What do you think about Vafpress? Do you think that you'll give it a chance in your next theme project? Tell us what you think in the Comments section below. And if you liked the article, don't forget to share it with your friends!

See you in the next part where we'll go over CMB2, a metabox, custom fields, and forms library for WordPress.

HIGHLIGHTS OF THE DAY