Admin Pages with Genesis

One of the best new features of Genesis 1.8 (and there are many) is a tool for making admin pages. These are needed if you’re building a plugin or a complex theme with site-wide settings that need to be managed.

I recently built an Event Manager theme for promoting an event, and on our Event Theme Settings page we had fields for event date and location, so these could be used throughout the site and pulled from a single source.

This code is pretty technical, but it is 100x easier than making admin pages without Genesis. See this 10 page tutorial by Chip Bennett for instructions on making them without Genesis’ help.

You should only use this method if you’re building a Genesis theme or a Genesis-specific plugin. If you build a plugin for public distribution, make sure you put some checks in place to ensure the user is running Genesis (take a look at the AgentPress plugin code as an example).

Here’s the steps:

1. Specify the page information. This includes the page’s name and default values for your fields.
2. Create the sanitization filters. These keep the page secure by ensuring the right type of data are entered.
3. Set up the help tab, a very useful feature that was improved in WordPress 3.3.
4. Add your metaboxes to the page.
5. Build your metaboxes.
6. Finally, add the new admin page to the backend.

Specify the page information

First, it’s best to keep all this code in its own file so your theme is easy to browse. I like to create a “lib” folder in my child theme where I store everything. In my example, I created /lib/admin/child-theme-settings.php, then added this to my functions.php to include it:

Now inside your child-theme-settings.php file, place the following:

This is a lot of code, so I’ll walk through it:

• I start out with some page-specific documentation that describes what this page is (always a good practice).
• Then there’s the documentation for our new class, Child_Theme_Settings
• We create our new class by extending the existing Genesis_Admin_Boxes class
• First thing in our new class is the __construct() method (functions inside of classes are called methods). This is what sets everything up.
• We create an unique page ID for this page. I’m calling mine ‘child’, but you could call yours whatever you’d like. I recommend naming it the same as your child theme since it will contain your child-theme-specific settings.
• Next we specify some information about the menu item. It’s a child of the ‘genesis’ page, we give it a page title and a menu title.
• Then we create the $page_ops variable which lets you customize some page settings. I’ve left the defaults in there and commented them out so you can see. Uncomment a line and then modify it to change the default.
• Then we define the settings field. All the settings on this page will be grouped together. If you create a field called address you can get to it like this: $address = genesis_get_option( 'option_name', 'child-settings' );
• Finally, we create the admin page by adding all the variables together in the create() method.
• I’ve also added the sanitation action (in __construct() method) and sanitization_filters() method to create the sanitization filters, which we’ll do in the next step.

Before we move on, a few quick notes about classes. Everything inside the class should use the __construct() method for hooking to appropriate actions/filters. Classes are their own namespace, so you can name the methods whatever you’d like. Unlike standard functions where you always need to prefix, you don’t have to worry about any other function having the same name. And finally, when hooking methods to actions make sure you use array( $this, 'method_name' ) instead of just 'method_name'.

Create the sanitization filters

Sanitization is about ensuring the data collected is the type of data you expect. By limiting a checkbox to a 0 or 1, a title to no html… you’re able to prevent code you didn’t expect (whether malicious or not) from altering the way your theme/plugin works.

See my previous post on Genesis options for more details on sanitization filters.

I’m planning to have two fields on this page – phone and address – so I’ll register those as no_html. Update your sanitization_filters() method like this:

Help Tab

While not required, it’s a good idea to put instructions and other useful information in the help tab. If you’d like to have a help tab, simply create a help() method in your class.

Here’s a screenshot of the help tab in my Event Theme. I don’t usually provide this much information, but the client plans to sell the theme so we wanted to provide as much information as possible.

To create a help tab, add this method inside your Child_Theme_Settings class ( so before the last } ).

Provide an unique ID for the tab, then give it a title (shown on the left) and HTML content (shown on the right). For multiple tabs, simply repeat the $screen->add_help_tab() method inside your help() method.

Add your metaboxes

We’ll now create a method inside our class called metaboxes(). For each metabox we’d like to add to our page, we’ll write a simple one line of code to add_meta_box().

I’ve added a single metabox with an ID of ‘contact-information’, a title of ‘Contact Information’, a callback function (where the actual metabox code is) of contact_information(), I’m putting it on the current page, it goes in the main column (not that there’s any other columns for it) and I want it positioned at the top. For more information on this function, see add_meta_box() in the Codex.

Build your metaboxes

In the previous method we referenced a callback function called contact_information(). Now it’s time to build this.

My metabox, Contact Information, will contain two fields. Phone will be a text field, and Address is a textarea. For examples of more fields, look at the actual Genesis admin pages (/lib/admin/…). And I’ve heard there might be a tool similar to our Custom Metabox Library for making Genesis admin fields (talk with NickTheGeek).

This method also goes inside your Child_Theme_Settings class.

The important thing to note here is the handy methods that are built into the class (examples below are for the field ‘phone’ ).

• $this->get_field_name( 'phone' );
• $this->get_field_id( 'phone' );
• $this->get_field_value( 'phone' );

That’s It!

That’s all it takes to build custom admin pages in Genesis. The code definitely looks complicated, but once you get started it’s pretty easy to modify it to your needs. StudioPress has done all the hard (and repetitive) work for you, so you just have to specify the things that are unique to the page.

Here’s the completed code:

And once you do have your custom admin page up-and-running, you’ll need to access that information. Just use genesis_get_option( [field-name], [settings-field] );.

So in the above example, to access the phone number use: $phone = genesis_get_option( 'phone', 'child-settings' );.