README

Lightweight and simple way to create Plugin and Theme options and also Metaboxes for WordPress. Inspired by OptionTree

Description

WP Option Builder attempts to bridge the gap between WordPress developers, designers and end-users by creating fully responsive option panels and meta boxes with an ease unlike any other plugin. OptionBuilder has many advanced features with well placed hooks and filters to adjust every aspect of the user experience.

Contributing

To contribute or report bugs, please go to the WP Option Builder repository.

Option Types

This is a complete list of all the available option types that come shipped with WP Option Builder.

Background
Border
Box Shadow
Category Checkbox
Category Select
Checkbox
Colorpicker
Colorpicker Opacity
CSS
Custom Post Type Checkbox
Custom Post Type Select
Date Picker
Date Time Picker
Dimension
Gallery
Google Fonts
JavaScript
Link Color
List Item
Measurement
Numeric Slider
On/Off
Page Checkbox
Page Select
Post Checkbox
Post Select
Radio
Radio Image
Select
Sidebar Select
Slider
Social Links
Spacing
Tab
Tag Checkbox
Tag Select
Taxonomy Checkbox
Taxonomy Select
Text
Textarea
Textarea Simple
Textblock
Textblock Titled
Typography
Upload

Installation

composer require ignitekit/wp-option-builder

or without Composer as follows:

require_once '/path/to/wp-option-builder/autoload.php';

How to use

Assuming that you already loaded the library you need instance of the Framework class:

use IgniteKit\WP\OptionBuilder\Framework;
$framework = new Framework();

Then you can register option pages and metaboxes as follows:

Option pages

$settings = array(
	'id'    => 'custom_options',
	'pages' => array(
		array(
			'id'              => 'test_page',
			'parent_slug'     => 'themes.php',
			'page_title'      => __( 'Theme Options', 'your-text-domain' ),
			'menu_title'      => __( 'Theme Options', 'your-text-domain' ),
			'capability'      => 'edit_theme_options',
			'menu_slug'       => 'demo-theme-options',
			'icon_url'        => null,
			'position'        => null,
			'updated_message' => __( 'Options updated!', 'your-text-domain' ),
			'reset_message'   => __( 'Options reset!', 'your-text-domain' ),
			'button_text'     => __( 'Save changes', 'your-text-domain' ),
			'show_buttons'    => true,
			'screen_icon'     => 'options-general',
			'contextual_help' => array(
				'content' => array( array(
						'id'      => 'option_types_help',
						'title'   => __( 'Option Types', 'theme-text-domain' ),
						'content' => '<p>' . __( 'Help content goes here!', 'theme-text-domain' ) . '</p>',
					),
				),
				'sidebar' => '<p>' . __( 'Sidebar content goes here!', 'theme-text-domain' ) . '</p>',
			),
			'sections' => array( array(
				'id'    => 'option_types',
				'title' => __( 'Option Types', 'theme-text-domain' ),
			    ),
			),
			'settings'        => array(
				array(
					'id'           => 'demo_background',
					'label'        => __( 'Background', 'theme-text-domain' ),
					'desc'         => __( 'Some description goes here...', 'theme-text-domain' ),
					'std'          => '',
					'type'         => 'background',
					'section'      => 'option_types',
					'rows'         => '',
					'post_type'    => '',
					'taxonomy'     => '',
					'min_max_step' => '',
					'class'        => '',
					'condition'    => '',
					'operator'     => 'and',
				),
				array(
					'id'           => 'demo_border',
					'label'        => __( 'Border', 'theme-text-domain' ),
					'desc'         => __( 'Some description goes here...', 'theme-text-domain' ),
					'std'          => '',
					'type'         => 'border',
					'section'      => 'option_types',
					'rows'         => '',
					'post_type'    => '',
					'taxonomy'     => '',
					'min_max_step' => '',
					'class'        => '',
					'condition'    => '',
					'operator'     => 'and',
				),
				array(
					'id'           => 'demo_box_shadow',
					'label'        => __( 'Box Shadow', 'theme-text-domain' ),
					'desc'         => __( 'Some description goes here...', 'theme-text-domain' ),
					'std'          => '',
					'type'         => 'box-shadow',
					'section'      => 'option_types',
					'rows'         => '',
					'post_type'    => '',
					'taxonomy'     => '',
					'min_max_step' => '',
					'class'        => '',
					'condition'    => '',
					'operator'     => 'and',
				),
			)
		)
	)
);

$framework->register_settings( array( $settings ) ); // Note: $settings one group option pages, you can add multiple groups of pages.

Retrieving options

To retrieve options for the above settings, locate the settings key, in our case custom_options.

// Make settings instance
$settings = get_option('custom_options');

// To access demo_background setting
$demo_bg = isset($settings['demo_background']) ? $settings['demo_background'] : ''; // or simply $settings['demo_background'].

Metaboxes

$framework->register_metabox( array(
	'id'       => 'demo_meta_box',
	'title'    => __( 'Demo Meta Box', 'theme-text-domain' ),
	'desc'     => '',
	'pages'    => array( 'post' ),
	'context'  => 'normal',
	'priority' => 'high',
	'fields'   => array(
		array(
			'label' => __( 'Conditions', 'theme-text-domain' ),
			'id'    => 'demo_conditions',
			'type'  => 'tab',
		),
		array(
			'label' => __( 'Show Gallery', 'theme-text-domain' ),
			'id'    => 'demo_show_gallery',
			'type'  => 'on-off',
			'desc'  => sprintf( __( 'Shows the Gallery when set to %s.', 'theme-text-domain' ), '<code>on</code>' ),
			'std'   => 'off',
		),
		array(
			'label'     => '',
			'id'        => 'demo_textblock',
			'type'      => 'textblock',
			'desc'      => __( 'Congratulations, you created a gallery!', 'theme-text-domain' ),
			'operator'  => 'and',
			'condition' => 'demo_show_gallery:is(on),demo_gallery:not()',
		),
		array(
			'label'     => __( 'Gallery', 'theme-text-domain' ),
			'id'        => 'demo_gallery',
			'type'      => 'gallery',
			'desc'      => sprintf( __( 'This is a Gallery option type. It displays when %s.', 'theme-text-domain' ), '<code>demo_show_gallery:is(on)</code>' ),
			'condition' => 'demo_show_gallery:is(on)',
		),
		array(
			'label' => __( 'More Options', 'theme-text-domain' ),
			'id'    => 'demo_more_options',
			'type'  => 'tab',
		),
		array(
			'label' => __( 'Text', 'theme-text-domain' ),
			'id'    => 'demo_text',
			'type'  => 'text',
			'desc'  => __( 'This is a demo Text field.', 'theme-text-domain' ),
		),
		array(
			'label' => __( 'Textarea', 'theme-text-domain' ),
			'id'    => 'demo_textarea',
			'type'  => 'textarea',
			'desc'  => __( 'This is a demo Textarea field.', 'theme-text-domain' ),
		),
	),
) );

Retrieving metabox settings

To retrieve the metabox settings, use get_post_meta() function as follows.

$value = get_post_meta($post_id, 'demo_text', true);

If you are using 'save_mode' => 'array' in the metabox settings, then all the settings will be stored into one meta row as serialized array. This appraoch is good if you want better performance. The data will be accessible with one mysql query instead of separate for each field.

To retrieve with this kind of save_mode, call the get_post_meta() function on the metabox id as follows:

$data = get_post_meta($post_id, 'demo_meta_box', true);
$value = $data['demo_text'];

More details

License

Copyright (C) 2021 Darko Gjorgjijoski (https://darkog.com)

This file is part of WP Option Builder

WP Option Builder is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

WP Option Builder is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with WP Option Builder. If not, see <https://www.gnu.org/licenses/>.

ignitekit / wp-option-builder

Maintainers

Details