ClassicPress Plugin Development: Create Submenu on Custom Top Level Menu

ClassicPress PluginsThis 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 added a custom top level menu for your plugin, you can add submenu items. This is done using the add_submenu_page function:

add_submenu_page(string $parent_slug, string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', int $position = null)

Click to show/hide

$parent_slug (string) (Required) The slug name for the parent menu (or the file name of a standard WordPress admin page). $page_title (string) (Required) The text to be displayed in the title tags of the page when the menu is selected. $menu_title (string) (Required) The text to be used for the menu. $capability (string) (Required) The capability required for this menu to be displayed to the user. $menu_slug (string) (Required) The slug name to refer to this menu by. Should be unique for this menu and only include lowercase alphanumeric, dashes, and underscores characters to be compatible with sanitize_key(). $function (callable) (Optional) The function to be called to output the content for this page. Default value: '' $position (int) (Optional) The position in the menu order this item should appear. Default value: null

The below example is extracted from my To Twitter plugin which adds a submenu to the azrcrv-m menu item:

add_action('admin_menu', 'azrcrv_tt_create_admin_menu');

/**
 * Add to menu.
 *
 * @since 1.0.0
 *
 */
function azrcrv_tt_create_admin_menu(){
				
	add_submenu_page(
				'azrcrv-tt'
				,__('Send Tweet', 'to-twitter')
				,__('Send Tweet', 'to-twitter')
				,'manage_options'
				,'azrcrv-tt-smt'
				,'azrcrv_tt_display_send_manual_tweet');
				
}

This will add a second sublevel menu to the custom top level menu which takes the user to a different options page.

To add a custom top level menu to a network admin dashboard, change the admin_menu tag in the add_action function call to network_admin_menu.

Click to show/hide the ClassicPress Plugin Development Series Index

ClassicPress Plugin Development: Create Custom Top Level Menu

ClassicPress PluginsThis 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.

While it is most common to add an option spage for a plugin to the Settings or Security top level menu, it is possible to create a custom top level menu.

A top level menu can be created using the add_menu_page function:

add_menu_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', string $icon_url = '', int $position = null)

Click to show/hide

$page_title (string) (Required) The text to be displayed in the title tags of the page when the menu is selected. $menu_title (string) (Required) The text to be used for the menu. $capability (string) (Required) The capability required for this menu to be displayed to the user. $menu_slug (string) (Required) The slug name to refer to this menu by. Should be unique for this menu page and only include lowercase alphanumeric, dashes, and underscores characters to be compatible with sanitize_key(). $function (callable) (Optional) The function to be called to output the content for this page. Default value: '' $icon_url (string) (Optional) The URL to the icon to be used for this menu.
  • Pass a base64-encoded SVG using a data URI, which will be coloured to match the color scheme. This should begin with 'data:image/svg+xml;base64,'.
  • Pass the name of a Dashicons helper class to use a font icon, e.g. 'dashicons-chart-pie'.
  • Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS.
  • Default value: ''

Below is an example of a custom top level menu from my To Twitter plugin:

add_action('admin_menu', 'azrcrv_tt_create_admin_menu');

/**
 * Add to menu.
 *
 * @since 1.0.0
 *
 */
function azrcrv_tt_create_admin_menu(){

    add_menu_page(
				__('To Twitter', 'to-twitter')
				,__('To Twitter','to-twitter')
				,'manage_options'
				,'azrcrv-tt'
				,'azrcrv_tt_display_options'
				,'dashicons-twitter'
				, 50);
				
}

The top level menu automatically has a sublevel menu of the same name added; I’ll show how to rename this in the next post of this series.

To add a custom top level menu to a network admin dashboard, change the admin_menu tag in the add_action function call to network_admin_menu.

Click to show/hide the ClassicPress Plugin Development Series Index

ClassicPress Plugin Development: Add Plugin Options Page to Security Main Menu

ClassicPress PluginsThis 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, it is usual to create an options page to allow users to configure the plugin. The most common way of making the plugin options page available to users is to add it to the Settings menu in the admin dashboard; however, ClassicPress has a Security menu available which allows security plugins to be separated from the other settings on a site. This Security menu does not exist in WordPress so if you’re writing a plugin to be compatible with both ClassicPress and WordPress you will need to manage this when adding the options page.

This is done using the add_security_page function available with ClassicPress.

add_security_page(string $page_title, string $menu_title, string $menu_slug, callable $function = '')

Parameters

$page_title (string) (Required) The text to be displayed in the title tags of the page when the menu is selected. $menu_title (string) (Required) The text to be used for the menu. $menu_slug (string) (Required) The slug name to refer to this menu by (should be unique for this menu); must match an active plugin or mu-plugin slug.. $function (callable) (Optional) The function to be called to output the content for this page. Default value: ''

Return

(string|false) The resulting page's hook_suffix, or false if the user does not have the capability required.

The function above is made accessible using the add_action function along with a admin_menu tag.

The below is an example, including check for the security menu being available, of an options page using my vendor prefix of azrcrv and a plugin identifer of XXXX:

add_action('admin_menu', 'azrcrv_XXXX_add_options_page');

function azrcrv_XXXX_add_options_page() {
	if (function_exists('add_security_page')){
		add_security_page( 
			esc_html__('XXXX Options', 'text-domain'),
			esc_html__('XXXX', 'text-domain'),
			dirname(plugin_basename(__FILE__ )),
			'azrcrv_XXXX_display_options_page'
		);
	}else{
		// add options in WordPress compatible way; possibly using the add_options_page function.
	}
}

If the menu being added is for a network, rather than individual site, the $tag would be network_admin_menu instead of admin_menu.

When an options page is added to the Security menu, a plugin action link is automatically added:

Security plugin action link example

Click to show/hide the ClassicPress Plugin Development Series Index

ClassicPress Plugin Development: Add Plugin Options Page to Settings Main Menu

ClassicPress PluginsThis 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, it is usual to create an options page to allow users to configure the plugin. The most common way of making the plugin options page available to users is to add it to the Settings menu in the admin dashboard.

This is done using the add_options_page function available with ClassicPress.

add_options_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', int $position = null)

Parameters

$page_title (string) (Required) The text to be displayed in the title tags of the page when the menu is selected. $menu_title (string) (Required) The text to be used for the menu. $capability (string) (Required) The capability required for this menu to be displayed to the user. $menu_slug (string) (Required) The slug name to refer to this menu by (should be unique for this menu). $function (callable) (Optional) The function to be called to output the content for this page. Default value: '' $position (int) (Optional) The position in the menu order this item should appear. Default value: null

Return

(string|false) The resulting page's hook_suffix, or false if the user does not have the capability required.

The function above is made accessible using the add_action function along with a admin_menu tag.

The below is an example of an options page using my vendor prefix of azrcrv and a plugin identifer of XXXX:

add_action('admin_menu', 'azrcrv_XXXX_add_options_page');

function azrcrv_XXXX_add_options_page() {
    add_options_page( 
        esc_html__('XXXX Options', 'text-domain'),
        esc_html__('XXXX', 'text-domain'),
        'manage_options',
        dirname(plugin_basename(__FILE__ )),
        'azrcrv_XXXX_display_options_page'
    );
}

If the menu being added is for a network, rather than individual site, the $tag would be network_admin_menu instead of admin_menu.

Click to show/hide the ClassicPress Plugin Development Series Index

ClassicPress Plugin Development: Create a Plugin Action Link

ClassicPress PluginsThis 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 with an settings page, it is quite common to add a link to the settings page on the Plugins page; these links are known as plugin action links. This is an example from my URL Shortener plugin:

URL Shortener action link

The plugin action link can be added by using the add_filter function:

add_filter(string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1)

The $tag to use is plugin_action_links, the $function_to_add is the function you need to write to add the link and the accepted_args is 2

Below is an example of the filter using the plugin_action_links tag to add the link to the URL Shortener plugin’s settings page:

add_filter('plugin_action_links', 'azrcrv_urls_add_plugin_action_link', 10, 2);

The azrcrv_urls_add_plugin_action_link function called by the filter is:

/**
 * Add URL Shortener action link on plugins page.
 *
 * @since 1.0.0
 *
 */
function azrcrv_urls_add_plugin_action_link($links, $file){
	static $this_plugin;

	if (!$this_plugin){
		$this_plugin = plugin_basename(__FILE__);
	}

	if ($file == $this_plugin){
		$settings_link = '<a href="'.admin_url('admin.php?page=azrcrv-urls').'">'.esc_html__('Settings' ,'url-shortener').'</a>';
		array_unshift($links, $settings_link);
	}

	return $links;
}

The highlighted section is the menu_slug for the settings page.

Click to show/hide the ClassicPress Plugin Development Series Index

ClassicPress Plugin Development: Best Practice for Loading Styles and Scripts

ClassicPress PluginsThis 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 few posts, I have covered how to register and enqueue scripts and styles. In the posts on loading the admin styles and scripts I mentioned a check to only load the styles and scripts when the loaded page was the settings page for the plugin.

This is the best practice approach for developing plugins for ClassicPress; only load a script or style when it is needed. This is best practice for both scripts and styles on the front-end as well as the back-end admin dashboard.

Click to show/hide the ClassicPress Plugin Development Series Index

ClassicPress Plugin Development: Loading Back-End Scripts

ClassicPress PluginsThis 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.

jQuery itself is automatically loaded by ClassicPress so we don’t need to do anything to load this ourselves in a plugin; it is just our own jQuery script which we need to register and enqueue. There is two ways in which scripts can be loaded in a plugin; I will cover them both, but will note first of all that I typically use the second approach; there is an argument that the first approach is the “correct” one.

The first thing to do when you are loading a script is to register it. This is done using the wp_register_script function which ClassicPress provides.

Continue reading “ClassicPress Plugin Development: Loading Back-End Scripts”

ClassicPress Plugin Development: Loading Front-End Scripts

ClassicPress PluginsThis 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.

jQuery itself is automatically loaded by ClassicPress so we don’t need to do anything to load this ourselves in a plugin; it is just our own jQuery script which we need to register and enqueue. There is two ways in which scripts can be loaded in a plugin; I will cover them both, but will note first of all that I typically use the second approach; there is an argument that the first approach is the “correct” one.

The first thing to do when you are loading a script is to register it. This is done using the wp_register_script function which ClassicPress provides.

Continue reading “ClassicPress Plugin Development: Loading Front-End Scripts”

ClassicPress Plugin Development: Loading Back-End Stylesheets

ClassicPress PluginsThis 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.

All of the plugins I have written have a settings page in the admin dashboard, either for settings to be configured or for instructions on how to use the plugin. I often have an admin stylesheet which needs to be loaded on the settings page. There is two ways in which stylesheets can be loaded in a plugin; I will cover them both, but will note first of all that I typically use the second approach. There is an argument that the first approach is the “correct” one.

The first thing to do when you are loading a stylesheet is to register it. This is done using the wp_register_style function which ClassicPress provides.

Continue reading “ClassicPress Plugin Development: Loading Back-End Stylesheets”

ClassicPress Plugin Development: Loading Front-End Stylesheets

ClassicPress PluginsThis 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.

Virtually all of the plugins I have written have output to the front end of a site, usually through use of shortcodes. As there is front end output, I have needed to create a stylesheet which means the plugin needs to load it. There is two ways in which stylesheets can be loaded in a plugin; I will cover them both, but will note first of all that I typically use the second approach. There is an argument that the first approach is the “correct” one.

The first thing to do when you are loading a stylesheet is to register it. This is done using the wp_register_style function which ClassicPress provides.

Continue reading “ClassicPress Plugin Development: Loading Front-End Stylesheets”