A package that makes creating WordPress settings pages a breeze.

Overview

Code Snippet

WP Settings

This package aims to make it easier to create settings pages for WordPress plugins. Typically, you would use the Settings API or write something custom. While the Settings API works, there is still quite a lot to set up. You still need to write the HTML for your options for example. And it gets quite complicated if you want to add tabs and tab-sections. See this comparison.

Installation

composer require jeffreyvanrossum/wp-settings

Usage

Basic example

use Jeffreyvr\WPSettings\WPSettings;

$settings = new WPSettings(__('My Plugin Settings'));

$tab = $settings->add_tab(__( 'General', 'textdomain'));

$section = $tab->add_section('MailChimp');

$section->add_option('text', [
    'name' => 'mailchimp_api_key',
    'label' => __('API Key', 'textdomain')
]);

$settings->make();

Creating the settings instance

$settings = new WPSettings(__('My Plugin Settings'));

By default, the page slug is created by sanitizing the title. You may pass a specific slug as the second parameter of the constructor.

Other methods for this class:

$settings->set_capability('manage_options');
$settings->set_option_name('my_plugin_options');
$settings->set_menu_icon('dashicons-admin-generic');
$settings->set_menu_position(5);
$settings->set_menu_parent_slug('options-general.php');

Tabs

Tabs are only displayed when there is more then one.

$settings->add_tab(__( 'General', 'textdomain'));

Sections

You can call the add_section method from an instance of Tab. You can also call it from the WPSettings instance. It will then be added to the last created Tab.

$tab->add_section('Section 1');

If you want sections to be displayed as submenu-items, you can do:

$tab->add_section('Section 1', ['as_link' => true]);

Note that this only has an effect when you have more then one as_link section.

Options

To add an option, you either call the add_option method from an instance of Section. You may also call add_option from the WPSettings instance. The option will then be added to the last created section.

Text

$section->add_option('text', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
]);

Textarea

$section->add_option('textarea', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
]);

Select

$section->add_option('select', [
    'name' => 'option_1',
    'label' => __( 'Option 1', 'textdomain' ),
    'options' => [
        'value_1' => 'Label 1',
        'value_2' => 'Label 2'
    ]
]);

Select Multiple

$section->add_option('select-multiple', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain'),
    'options' => [
        'value_1' => 'Label 1',
        'value_2' => 'Label 2'
    ]
] );

WP Editor

$section->add_option('wp-editor', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
] );

Code Editor

$section->add_option('code-editor', [
    'name' => 'option_1',
    'label' => __('Option 1', 'textdomain')
] );

Color

Will be implemented later.

Media

Will be implemented later.

Validation

You are able to validate an option. You may pass a callback and a feedback message. You can pass multiple validation rules.

$section->add_option('text', [
    'name' => 'mailchimp_api_key',
    'label' => __('API Key', 'textdomain'),
    'validate' => [
        [
            'feedback' => __('Your API key is too short.', 'textdomain'),
            'callback' => function($value) {
                return strlen($value) > 35;
            }
        ]
    ]
]);

Sanitization

You may pass a sanitization callback.

$section->add_option('text', [
    'name' => 'mailchimp_api_key',
    'label' => __('API Key', 'textdomain'),
    'santitize' => function($value) {
        return sanitize_key($value);
    }
]);

Adding a custom option type

To add an custom option type, you can use the wp_settings_option_type_map filter.

add_filter('wp_settings_option_type_map', function($options){
    $options['custom'] = YourCustomOption::class;
    return $options;
});

You will need to create a class for your custom option type.

use Jeffreyvr\WPSettings\Options\OptionAbstract;

class YourCustomOption extends OptionAbstract
{
    public $view = 'custom-option';

    public function render()
    {
        echo 'Your custom option HTML';
    }
}

Once registered, you can then use your option type like so:

$settings->add_option('custom-option', [
    'name' => 'your_option_name',
    'label' => __('Your label')
]);

Contributors

License

MIT. Please see the License File for more information.

You might also like...
A custom WordPress nav walker class to fully implement the Twitter Bootstrap 4.0+ navigation style (v3-branch available for Bootstrap 3) in a custom theme using the WordPress built in menu manager.

WP Bootstrap Navwalker This code in the main repo branch is undergoing a big shakeup to bring it in line with recent standards and to merge and test t

A curated list of Awesome WordPress Theme, Plugins and Framework development Resources and WordPress Communities.

Awesome WordPress A curated list of Awesome WordPress Theme, Plugins and Framework development Resources and WordPress Communities. Inspired by bayand

The Pronamic WordPress Basecone plugin allows you to connect your WordPress installation to Basecone.

Pronamic WordPress Basecone The Pronamic WordPress Basecone plugin allows you to connect your WordPress installation to Basecone. Table of contents Au

Twenty Twenty-Two, the default WordPress theme that will launch with WordPress 5.9.
Twenty Twenty-Two, the default WordPress theme that will launch with WordPress 5.9.

Twenty Twenty-Two Welcome to the development repository for the default theme that will launch with WordPress 5.9. About Twenty Twenty-Two is designed

Easy handle APlayer on WordPress. A shortcode for WordPress to using APlayer.

Description Easy handle APlayer on WordPress. A shortcode for WordPress to using APlayer. Support [audio] tag, compatible with AMP. Requirement WordPr

WordPress plugin that lets you use Discourse as the community engine for a WordPress blog

WP Discourse Note: the wp-discourse plugin requires = PHP-5.4.0. The WP Discourse plugin acts as an interface between your WordPress site and your Di

WordPress & TypeScript. Simple starter template for WordPress projects

WordPress & TypeScript. Simple starter template for WordPress projects that want to use TypeScript in combination with @wordpress/scripts

Simple WordPress plugin to learn how to understand WordPress Crons and the Action Scheduler library.

Simple WordPress plugin to learn how to understand WordPress Crons and the Action Scheduler library. Import Jamendo playlists with tracks in WordPress posts.

A PHP client for Wordpress websites that closely implement the XML-RPC WordPress API

Wordpress XML-RPC PHP Client A PHP client for Wordpress websites that closely implement the XML-RPC WordPress API Created by Hieu Le MIT licensed. Cur

Comments
  • Nice work! I've created a simple plugin with this. Any plans on more field types in the future?

    Nice work! I've created a simple plugin with this. Any plans on more field types in the future?

    Hi Jeffrey,

    Greetings from Indonesia! Thank you for creating this awesome package!

    I've just tried it to create a very simple plugin Elegant Scroll Top by reading the documentation and watching your video tutorial.

    Any plans on adding more ready-to-use field types in the future? I like how intuitive this library is and was hoping to see more of what WPSF framework provides also made available in your package... at least the basic ones to begin with, e.g. checkbox (single and multiple), radio box, media upload, etc.

    Have a great weekend!

    Cheers, Bowo

    opened by qriouslad 0
  • Feature Request - Add css class option to add_option method

    Feature Request - Add css class option to add_option method

    First of all, a huge thanks for creating this amazing package. It is tremendously helpful to build quick WP Settings page with simple API and needless to say, it saves tons of time.

    I have a feature request to add css_class option to the add_option method so we can pass built-in classes like regular-text, large-text, all-options and so on or custom css class to input elements. I suggest that the option would have capability to more than one css class separate by space.

    I sincerely you consider this.

    Thank you.

    opened by vikasbhvsr 0
Releases(1.0.0)
Owner
Jeffrey van Rossum
Laravel / WordPress / Vue / PHP
Jeffrey van Rossum
A WordPress plugin to suspend WordPress sites automagically. Simple and lightweight, no annoying ads and fancy settings.

Suspend WP A WordPress plugin to suspend WordPress sites automagically. Simple and lightweight, no annoying ads and fancy settings. ?? Demo (coming so

Waren Gonzaga 3 Nov 15, 2021
A simple platform information plugin for WordPress. Shows you environment variables, PHP settings and more.

A simple platform information plugin for WordPress. Shows you environment variables, PHP settings and more.

New To Vaux 2 Sep 7, 2022
Free WordPress plugin to generate Admin Settings Page.

ClioWP Settings Page ClioWP Setting Page is a free WordPress Plugin which creates a sample Settings Page. This “test” page contains almost any type of

Christos Pontikis 5 Nov 3, 2022
A PHP Class for creating Wordpress Custom Post Types easily

N.B I've released an updated version of the project to a new repository, PostTypes. WP Custom Post Type Class v1.4 A single class to help you build mo

Joe Grainger 412 Nov 25, 2022
Querycase provides a convenient, fluent interface for creating and running database queries in WordPress.

Querycase database for WordPress Dependency-free library to create SQL Queries in WordPress. Explore the documentation → ℹ️ About Querycase Querycase

Alessandro Tesoro 7 Oct 17, 2021
Scaffold plugin for creating and managing Blocks, Block Patterns, Block Styles and Block Editor Sidebars in the WordPress Block Editor (aka Gutenberg).

WordPress Block Editor Scaffold This project is a template repo for developing WordPress Blocks, Block Patterns, Block Styles and Block Editor Sidebar

Rareview 6 Aug 2, 2022
Base classes for creating WordPress shortcodes.

WDS Shortcodes Contributors: WebDevStudios, jtsternberg, JayWood Donate link: http://webdevstudios.com Tags: shortcode button, shortcodes, cmb2, utili

WebDevStudios 26 Jun 19, 2020
Adds Settings to the Custom Post Type UI plugin to show Post Types in WPGraphQL

DEPRECATION NOTICE ?? Custom Post Type UI v1.9.0 introduced formal support for WPGraphQL!!! ?? With that, this plugin is being deprecated and will no

WPGraphQL 77 Aug 3, 2022
Makes WP GraphQL's authetication "just work". It does this by customizing the CORS headers.

WP GraphQL CORS The primary purpose of this plugin is to make the WP GraphQL plugin authentication "just work". It does this by allowing you set the C

Funkhaus 86 Jan 5, 2023
Laravel Blog Package. Easiest way to add a blog to your Laravel website. A package which adds wordpress functionality to your website and is compatible with laravel 8.

Laravel Blog Have you worked with Wordpress? Developers call this package wordpress-like laravel blog. Contact us for any customization: contact@binsh

Binshops 279 Dec 28, 2022