Return True - Coding Tutorials, hints & tips in PHP, jQuery, CSS & HTML

Making a options page for a WordPress plugin isn’t actually that hard. It’s just the page WordPress have on how to do it isn’t exactly the easiest thing to read. So I thought I would show you how I made my options page for The Attached Image. Hopefully it will be easier to understand and help alot of you plugin developers out there.

Decide Where You Should Put It

The first thing that you need to do is add your plugin to one of the WordPress menus. WordPress have a guide on what type of options they think should go where. Here is what they have:

Settings

Displays plugin options that only administrators should view.

Manage

Displays management controls for links, posts, categories, images, etc.

Plugins

Displays controls dealing with plugin management, not configuration options for a plugin itself.

Presentation

Displays controls for manipulation of theme/style files, sidebars, etc.

Write

Displays tools for writing content (posts and pages).

Users

Displays controls for user management.

You can also create a new top-level menu for your plugin if you require a few different option pages. I didn’t so I’m not going to explain how to do that.

Add It To That Menu

Ok, so now you’ve decided which menu you want to put it under. Now we can get started. I am assuming you already have a plugin to add the options page to. If not you can check out my past video tutorial on how to make a basic plugin or you can look out for more on making plugins in the future.

First let’s go for the easy ones. If you have decided you want to put your plugin into options, management or presentation then there are three pre-made WordPress function to make it easy.

For Options

add_options_page(page_title, menu_title, access_level/capability, file, [function]);

For Management

add_management_page(page_title, menu_title, access_level/capability, file, [function]);

For Presentation

add_theme_page(page_title, menu_title, access_level/capability, file, [function]);

Clever, huh? Now you may be thinking what’s all that gibberish inside the functions. Well I’m going to explain that now.

page_title

The text written into the pages title tag.

menu_title

The text written in the WordPress menu.

access_level/capability

The user level required to have access to the options page. Level 8 is generally good for Admin only.

file

A tricky one. The name written in the url when accessing the options page. For example, The Attached Image shows themes.php?page=attachedoptions because I set this to attachedoptions.

function

The function to call to display the options page.

Right I hope that explains those a little.

If you want to add your plugin to any of the other menus in WordPress then you can use the add_submenu_page function. It has all the same parameters as the other three functions, except for one extra at the front. That is the parent parameter. This is the name of the php file WordPress uses to access the menu you want to add to. Here is a list.

• Write: add_submenu_page(‘post-new.php’,…)
• Manage: add_submenu_page(‘edit.php’,…)
• Design: add_submenu_page(‘themes.php’,…)
• Comments: add_submenu_page(‘edit-comments.php’,…)
• Settings: add_submenu_page(‘options-general.php’,…)
• Plugins: add_submenu_page(‘plugins.php’,…)
• Users: add_submenu_page(‘users.php’,…)

You can’t just call one of those functions in your plugin though, it just won’t work. You have to do it in a special way. Like this:

//First use the add_action to add onto the WordPress menu.
add_action('admin_menu', 'att_add_options');
//Make our function to call the WordPress function to add to the correct menu.
function att_add_options() {
	add_theme_page('The Attached Image Options', 'The Attached Image', 8, 'attachedoptions', 'att_options_page');
}

As you can see you define a function and hand it to the add_action function using the admin_menu hook to have it run it. It’s sometimes a little tricky to understand, but it sinks in eventually.

Creating A Options Page

Remember the function given to the last parameter of add_theme_page in our example? Well we make that function and the output creates our options page. To see if all is working all you need to do is use something like this example:

function att_options_page() {
      echo 'Testing. 1, 2, 3. Testing.';
}

If you see that on your options page then your spot on course. If it isn’t working do not pass go, do not collect £200 and go back and check you’ve done everything correctly. Right, got it working? Good.

Saving Those Options

Having an options page is fine, but if you don’t know how to save the options the user picks, it will be no help at all. That’s where this part comes in. I don’t know whether there is a better way to do this, but this way is my way, I like it and it works.

First we assign some variables. I’ll use The Attached Image’s option page as an example, I’ll clip out some of the fields though or this tutorial will become very big, very fast. Let’s look at the first bit:

function att_options_page() {
    // variables for the field and option names
    $opt_name = array('img_size' =>'att_img_size',
			      'css_class' => 'att_css_class',
			      'img_width' => 'att_img_width',
			      'img_height' => 'att_img_height');
    $hidden_field_name = 'att_submit_hidden';

Ok, I use an array to hold both key’s (for easy reference) and the field names I am using for both the form & storage in the database. I just append a little three letter code on the front as not to conflict with any other plugins or options. The hidden field name is used later as a test for form submission.

    // Read in existing option value from database
    $opt_val = array('img_size' => get_option( $opt_name['img_size'] ),
			   'css_class' => get_option( $opt_name['css_class'] ),
			   'img_width' => get_option( $opt_name['img_width'] ),
			   'img_height' => get_option( $opt_name['img_height'] ));

Next we get the values back from the database using the get_option() function, we use the $opt_name array from before so that if any names are changed we don’t have to change a lot of different things. These values are used to re-populate the form so the user can see what options are already selected.