Category: Development

This post is part of the ClassicPress Plugin Development series in which I am going to look at both best practice for developing plugins and how I approach some requirements as well as some of the functions I commonly use.

Once you have an options page created, you need to create the process to save the options when the user changes them.

The example I am using in this post is from my Remove Revisions plugin which uses a PHP namespace.

namespace azurecurve\RemoveRevisions;

Continue reading “ClassicPress Plugin Development: Save an Options Page”

This post is part of the ClassicPress Plugin Development series in which I am going to look at both best practice for developing plugins and how I approach some requirements as well as some of the functions I commonly use.

Anything more than a very simple plugin will hae options which the site administrator will need to be able to change. this means an options page which is added to the settings menu. ClassicPress does have a settings API which can be used; however, I do not use this API as I’ve previously found it to be overly complex and difficult to use, so I roll my own settings pages.

The example in this post are from my Remove Revisions plugin which uses a namespace:

namespace azurecurve\RemoveRevisions;

As I am using a namespace the options page was added in a function simply called display_options; if a namespace wasn’t in use, I’d have used a vedor/plugin prefix and called the function azrcrv_rr_display_options.

The example takes advantage of the page title from the settings menu (which I covered in the last post as well as loading options, which can be done
with defaults or with with multilevel defaults.

Below is a sample of the display_options from Remove Revisions with the controls removed, leaving behind the basic framework of the page, with the header, load of options and then the form with submit button:

/**
 * Display Settings page.
 *
 * @since 1.0.0
 *
 */
function display_options(){

	if (!current_user_can('manage_options')){
        wp_die(esc_html__('You do not have sufficient permissions to access this page.', 'remove-revisions'));
    }
	
	// Retrieve plugin configuration options from database
	$options = get_option_with_defaults('azrcrv-rr');	
	
	?>
	
	<div id="azrcrv-rr-general" class="wrap">
		
		<h1>
			<?php
				esc_html_e(get_admin_page_title());
			?>
		</h1>
		
		<form method="post" action="admin-post.php">
			
			<input type="hidden" name="action" value="azrcrv_rr_save_options" />
			<input name="page_options" type="hidden" value="enable-cron" />
			
			<?php
				//
				wp_nonce_field('azrcrv-rr', 'azrcrv-rr-nonce');
			?>
			
			/*
				your options here
			*/
			
			<input type="submit" name="btn_save" value="<?php esc_html_e('Save Settings', 'remove-revisions'); ?>" class="button-primary"/>
		</form>
	</div>
	<?php
	
}

The hidden input action and the wp_nonce_field is used for the save of the options, which I’ll cover in the next post in this series.

This post is part of the ClassicPress Plugin Development series in which I am going to look at both best practice for developing plugins and how I approach some requirements as well as some of the functions I commonly use.

Over the last couple of posts in this series, I’ve discussed how options can be loaded and saved, loaded with defaults and loaded with multilevel defaults. Over the next couple of pages, I’m going to show how an options page can be created and the options saved, but first a quick post on how the options page title can be populated.

I’ve seen a lot of plugins where the options page title has been a string which has been echoed. However, when the options page is added to the settings main menu, the first parameter is the page title. So instead of echoing a new string, we can use the get_admin_page_title function to get the title set when the options page was added to the menu.

<h1>
	<?php
		esc_html_e(get_admin_page_title());
	?>
</h1>

As you can see from the example code, above, the call to get_admin_page_title has been wrapped with a esc_html_e to echo and escape the page title.

This post is part of the ClassicPress Plugin Development series in which I am going to look at both best practice for developing plugins and how I approach some requirements as well as some of the functions I commonly use.

Over the last couple of posts, I’ve taken a look at saving and loading options and how to load options with defaults. The defaults in the last post was a single dimension array, but you can also do the same with multi dimensional arrays using a ustom recursive parse of the arrays.

The below is an example of loading options with multi dimensional defaults from my Widget Announcements plugin:

/**
 * Get options including defaults.
 *
 * @since 1.1.0
 *
 */
function azrcrv_wa_get_option($option_name){
 
	$defaults = array(
						'widget' => array(
											'width' => 300,
											'height' => 300,
										),
						'to-twitter' => array(
												'integrate' => 0,
												'tweet' => 0,
												'retweet' => 0,
												'retweet-prefix' => 'ICYMI:',
												'tweet-format' => '%t %h',
												'tweet-time' => '10:00',
												'retweet-time' => '16:00',
												'use-featured-image' => 1,
											),
						'toggle-showhide' => array(
												'integrate' => 0,
											),
					);

	$options = get_option($option_name, $defaults);

	$options = azrcrv_wa_recursive_parse_args($options, $defaults);

	return $options;

}

/**
 * Recursively parse options to merge with defaults.
 *
 * @since 1.1.0
 *
 */
function azrcrv_wa_recursive_parse_args( $args, $defaults ) {
	$new_args = (array) $defaults;

	foreach ( $args as $key => $value ) {
		if ( is_array( $value ) && isset( $new_args[ $key ] ) ) {
			$new_args[ $key ] = azrcrv_wa_recursive_parse_args( $value, $new_args[ $key ] );
		}
		else {
			$new_args[ $key ] = $value;
		}
	}

	return $new_args;
}

This post is part of the ClassicPress Plugin Development series in which I am going to look at both best practice for developing plugins and how I approach some requirements as well as some of the functions I commonly use.

In the last post I covered saving and loading options in a ClassicPress plugin. When you create a plugin with options you will want to provide defaults to be used before the user makes any changes to the settings; this both allows for basic operation of the plugin and avoids unset option errors.

The get_option function does allow for defaults to be passed, but this will only work if there are no options; it will not work effectively if new options are added to the plugin. This can be handled using the wp_parse_args function which merges user defined arguments into defaults array.

wp_parse_args( string|array|object $args, array $defaults = array() )
Parameters
$args (string|array|object) (Required)  Value to merge with $defaults.

$defaults (array) (Optional) Array that serves as the defaults.
Default value: array()
Return
(array) Merged user defined values with defaults.

The below is an example of loading options with defaults from my Comment Validator plugin:

/**
 * Get options including defaults.
 *
 * @since 1.2.0
 *
 */
function azrcrv_cv_get_option($option_name){
 
	$defaults = array(
						'min_length' => 10,
						'max_length' => 500,
						'mod_length' => 250,
						'prevent_unreg_using_reg_name' => 1,
						'use_network' => 1,
					);

	$options = get_option($option_name, $defaults);

	$options = wp_parse_args($options, $defaults);

	return $options;

}

The above example works when the default options is single level. If the options are multilevel, these need to be handled differently; I will cover this in the next post in this series.

This post is part of the ClassicPress Plugin Development series in which I am going to look at both best practice for developing plugins and how I approach some requirements as well as some of the functions I commonly use.

When developing a plugin, most of them will have settings which need to be saved ad recalled. There are functions available in ClassicPress which you can use to do this:

get_option

update_option

If your plugin contains multiple options, then best practice would be to store these in an array within one option rather than each option stored individually.

The get_option is used to load options from the database:

get_option( string $option, mixed $default = false )
Parameters
$option (string) (Required) Name of option to retrieve. Expected to not be SQL-escaped.

$default (mixed) (Optional) Default value to return if the option does not exist.
Default value: false
Return
(mixed) Value set for the option.

The below is an example of loading options from my SMTP plugin:

$options = get_option( 'azrcrv-smtp' );

The update_option function is used to save options:

update_option( string $option, mixed $value, string|bool $autoload = null )
Parameters
$option (string) (Required) Option name. Expected to not be SQL-escaped.

$value (mixed) (Required) Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.

$autoload (string|bool) (Optional) Whether to load the option when ClassicPress starts up. For existing options, $autoload can only be updated using update_option() if $value is also changed. Accepts 'yes'|true to enable or 'no'|false to disable. For non-existent options, the default value is 'yes'.
Default value: null
Return
(bool) False if value was not updated and true if value was updated.

The below is an example of saving options from my SMTP plugin:

update_option( 'azrcrv-smtp', $options );