oberonlai/wp-option

Adding option page for WordPress.

Maintainers

Details

github.com/oberonlai/wp-option

Homepage

Source

Issues

Installs: 55

Dependents: 0

Suggesters: 0

Security: 0

Stars: 7

Watchers: 1

Forks: 2

Open Issues: 0

v1.0.5 2021-11-27 03:02 UTC

Requires

  • php: >=7.2

MIT 59945dbfb544abb89eca8345aabcb0910e9b9777

This package is auto-updated.

Last update: 2024-04-27 08:22:25 UTC

README

Simple WordPress class for settings api modifed from boo-settings-helper

Requirements

Installation

Install with composer

Run the following in your terminal to install with Composer.

$ composer require oberonlai/wp-option

WP Option PSR-4 autoloading and can be used with the Composer's autoloader. Below is a basic example of getting started, though your setup may be different depending on how you are using Composer.

require __DIR__ . '/vendor/autoload.php';

use ODS\Option;

$prefix = 'plugin-prefix';

$books = new Option( $prefix );

See Composer's basic usage guide for details on working with Composer and autoloading.

Basic Usage

Below is a basic example of setting up a simple option page.

// Require the Composer autoloader.
require __DIR__ . '/vendor/autoload.php';

// Import PostTypes.
use ODS\Option;

$config = new Option( 'plugin-prefix' );
$config->addMenu();
$config->addTab();
$config->addText();
$config->register(); // Don't forget this.

Usage

To create a option, first instantiate an instance of Option. The class takes one argument, which is an plugin prefix. All of the options' name will add this prefix.

$config = new Option( 'plugin-prefix' );

After instantiating the above option, you have to add settings menu and tab.

Menu

Firstly, we need to add admin menu to our admin page.

$config->addMenu(
	array(
		'page_title' => __( 'Plugin Name Settings', 'plugin-name' ),
		'menu_title' => __( 'Plugin Name', 'plugin-name' ),
		'capability' => 'manage_options',
		'slug'       => 'plugin-name',
		'icon'       => 'dashicons-performance',
		'position'   => 10,
		'submenu'    => true,
		'parent'     => 'edit.php?post_type=event',
	)
);

You have to set option to true if you want to add menu under the settings menu.

$config->addMenu(
	array(
		'page_title' => __( 'Plugin Name Settings', 'plugin-name' ),
		'menu_title' => __( 'Plugin Name', 'plugin-name' ),
		'capability' => 'manage_options',
		'slug'       => 'plugin-name',
		'option'     => true
	)
);

Tab

You have to add one tab at least. The fields are placed in tab.

$config->addTab(
	array(
		array(
			'id'    => 'general_section',
			'title' => __( 'General Settings', 'plugin-name' ),
			'desc'  => __( 'These are general settings for Plugin Name', 'plugin-name' ),
		),
		array(
			'id'    => 'advance_section',
			'title' => __( 'Advanced Settings', 'plugin-name' ),
			'desc'  => __( 'These are advance settings for Plugin Name', 'plugin-name' )
		)
	)
);

Avaiable fields

Fields list

  • Text
  • URL
  • Number
  • Color
  • Textarea
  • Radio Button
  • Select
  • HTML
  • Checkbox
  • Multi Select
  • Related
  • Password
  • File
  • Media Upload

Common params of fields:

  • id - (string) Field ID. Use get_option( $plugin-prefix. 'field_id' ) to get value.
  • label - (string) Field name.
  • desc - (string) Field description.
  • placeholder - (string) Field placeholder.
  • default - (string) Select, checkbox, radio default option.
  • options - (array) Select, radio, multicheck options.
  • callback - (callback) Function name to be used to render field.
  • sanitize_callback (callback) Function name to be used for sanitization
  • show_in_rest - (Boolean) Show in REST API.
  • class - (string) - Field css class name. Separate more classes with space.
  • size - (string) - Field size. Options for small, regular, and large.
array(
	'id'                => 'text_field_id',
	'label'             => __( 'Text Field', 'plugin-name' ), 
	'desc'              => __( 'Some description of my field', 'plugin-name' ),
	'placeholder'       => 'This is Placeholder',
	'default'           => '', 
	'options'           => array(),
	'callback'          => '',
	'sanitize_callback' => '',
	'show_in_rest'      => true,
	'class'             => 'my_custom_css_class',
	'size'              => 'regular',
),

Text

There are three arguments. First is the tab ID, second is text field params, and last is callback function of render field.

$config->addText(
	'general_section',
	array(
		'id'                => 'text_field_id',
		'label'             => __( 'Hello World', 'plugin-name' ),
		'desc'              => __( 'Some description of my field', 'plugin-name' ),
		'placeholder'       => 'This is Placeholder',
		'show_in_rest'      => true,
		'class'             => 'my_custom_css_class',
		'size'              => 'regular',
	),
);

With render callback function:

$config->addText(
	'general_section',
	array(
		'id'    => 'text_field_id',
		'label' => __( 'Hello World', 'plugin-name' ),
	),
	function( $args ) {
		$html  = sprintf(
			'<input 
				class="regular-text"
				type="%1$s"
				name="%2$s"
				value="%3$s"
				placeholder="%4$s"
            	style="border: 3px solid red;"
			/>',
			$args['type'],
			$args['name'],
			$args['value'],
			'Placeholder from callback'
		);
		$html .= '<br/><small>This field is generated with callback parameter</small>';
		echo $html;
		unset( $html );
	}
);

URL

$config->addUrl(
	'general_section',
	array(
		'id'    => 'url_field_id',
		'label' => __( 'URL Field', 'plugin-name' ),
	),
);

Number

$config->addNumber(
	'general_section',
	array(
		'id'          => 'number_field_id',
		'label'       => __( 'Number Input', 'plugin-name' ),
		'placeholder' => __( 'Your Age here', 'plugin-name' ),
		'options'     => array(
			'min'  => 0,
			'max'  => 99,
			'step' => '1',
		),
	),
);

Color

$config->addColor(
	'general_section',
	array(
		'id'    => 'color_field_id',
		'label' => __( 'Color Field', 'plugin-name' ),
	),
);

Textarea

$config->addTextarea(
	'general_section',
	array(
		'id'          => 'textarea_field_id',
		'label'       => __( 'Textarea Input', 'plugin-name' ),
		'desc'        => __( 'Textarea description', 'plugin-name' ),
		'placeholder' => __( 'Textarea placeholder', 'plugin-name' ),
	),
);

Radio Button

$config->addRadio(
	'general_section',
	array(
		'id'      => 'radio_field_id',
		'label'   => __( 'Radio Button', 'plugin-name' ),
		'desc'    => __( 'A radio button', 'plugin-name' ),
		'options' => array(
			'radio_1' => 'Radio 1',
			'radio_2' => 'Radio 2',
			'radio_3' => 'Radio 3',
		),
		'default' => 'radio_2',
	),
);

Select

$config->addSelect(
	'general_section',
	array(
		'id'      => 'select_field_id',
		'label'   => __( 'A Dropdown Select', 'plugin-name' ),
		'desc'    => __( 'Dropdown description', 'plugin-name' ),
		'default' => 'option_2',
		'options' => array(
			'option_1' => 'Option 1',
			'option_2' => 'Option 2',
			'option_3' => 'Option 3',
		),
		'default' => 'option_3',
	),
);

HTML

Add static html in table row.

$config->addHtml(
	'general_section',
	array(
		'id'    => 'html',
		'label' => 'HTML',
		'desc'  => __( 'HTML area description. You can use any <strong>bold</strong> or other HTML elements.', 'plugin-name' ),
	),
);

Checkbox

$config->addCheckbox(
	'general_section',
	array(
		'id'    => 'checkbox_field_id',
		'label' => __( 'Checkbox', 'plugin-name' ),
		'desc'  => __( 'A Checkbox', 'plugin-name' ),
	),
);

Checkboxes

$config->addCheckboxes(
	'general_section',
	array(
		'id'      => 'multi_field_id',
		'label'   => __( 'Checkboxes', 'plugin-name' ),
		'desc'    => __( 'A checkboxes', 'plugin-name' ),
		'options' => array(
			'multi_1' => 'Multi 1',
			'multi_2' => 'Multi 2',
			'multi_3' => 'Multi 3',
		),
		'default' => array(
			'multi_1' => 'multi_1',
			'multi_3' => 'multi_3',
		),
	),
);

Posts

Add specific post type. The third params is the name of custom post type.

$config->addPost(
	'general_section',
	array(
		'id'      => 'pages_field_id',
		'label'   => __( 'Pages Field Type', 'plugin-name' ),
		'desc'    => __( 'List of Pages', 'plugin-name' ),
	),
	'page' // post type
);

Password

$config->addPassword(
	'general_section',
	array(
		'id'          => 'password_field_id',
		'label'       => __( 'Password Field', 'plugin-name' ),
		'desc'        => __( 'Password description', 'plugin-name' ),
		'placeholder' => __( 'Textarea placeholder', 'plugin-name' ),
	),
);

File Uploader

$config->addFile(
	'general_section',
	array(
		'id'      => 'file_field_id',
		'label'   => __( 'File', 'plugin-name' ),
		'desc'    => __( 'File description', 'plugin-name' ),
		'options' => array(
			'btn' => 'Get it', // upload button text
		),
	),
);

Media Uploader

$config->addMedia(
	'general_section',
	array(
		'id'      => 'media_field_id',
		'label'   => __( 'Media', 'plugin-name' ),
		'desc'    => __( 'Media', 'plugin-name' ),
		'type'    => 'media',
		'options' => array(
			'btn'       => __( 'Get the image', 'plugin-name' ),
			'width'     => 150,
			'max_width' => 150,
		),
	),
);

Render field

You can use callback function when add field to render the field.

$config->addText(
	'general_section',
	array(
		'id'    => 'text_field_id',
		'label' => __( 'Hello World', 'plugin-name' ),
	),
	function( $args ) {
		$html  = sprintf(
			'<input 
				class="regular-text"
				type="%1$s"
				name="%2$s"
				value="%3$s"
				placeholder="%4$s"
            	style="border: 3px solid red;"
			/>',
			$args['type'],
			$args['name'],
			$args['value'],
			'Placeholder from callback'
		);
		$html .= '<br/><small>This field is generated with callback parameter</small>';
		echo $html;
		unset( $html );
	}
);

Add links in plugins list

You can add links below the plugin name in list.

$config->addLink(
	'my-plugin',  // Your plugin's folder and main file name.
	array(
		array(
			'type' => 'default',
			'text' => __( 'Configure', 'plugin-name' ),
		),
		array(
			'type' => 'internal',
			'text' => __( 'Gravity Forms', 'plugin-name' ),
			'url'  => 'admin.php?page=gf_edit_forms',
		),
		array(
			'type' => 'external',
			'text' => __( 'Github Repo', 'plugin-name' ),
			'url'  => 'https://github.com/boospot/boo-settings-helper',
		),
	)
);

Retrive field's value

You can use WordPress get_option() to get value. Don't forget the prefix name of field id. For example::

use ODS\Option;

$config = new Option( 'hello-world-' );
$config->addMenu();
$config->addTab();
$config->addText(
	'general_section',
	array(
		'id'                => 'my_text_field',
		'label'             => __( 'Hello World', 'plugin-name' ),
		'desc'              => __( 'Some description of my field', 'plugin-name' ),
		'placeholder'       => 'This is Placeholder',
		'show_in_rest'      => true,
		'class'             => 'my_custom_css_class',
		'size'              => 'regular',
	),
);

If you want to retrive field value of 'my_text_field', use code below:

$my_text_field_value = get_option( 'hello-world-my_text_field' );