A Path Less Taken

Adding Options to Your WordPress Theme

Not everyone is a programmer. Even worse, not everyone wants to edit PHP and CSS files to change the behavior of their WordPress blog. Yes, I had trouble accepting this too, but it’s going to be ok. With WordPress Options we have a great way to give users of our theme the ability to change content and behavior without having to edit any raw theme files.

What we are about to do is some pure PHP programming. If you are not comfortable with PHP or programming in general then you may want to skip options. If you are comfortable then let’s get started! The first thing we need to do is create a new file in our theme directory named functions.php. Once it’s created let’s open the file for editing. We will need to put the PHP opening and closing tags into the file. They are <?php and ?>. Next we enter the following code.

1
2
3
4

if (is_admin ()) {
	add_action ('admin_menu', 'Welcome_Theme') ;
	add_action ('admin_init', 'registerWelcomeThemeSettings') ;
}

The is_admin () function is a function that will return true if the user is a logged in administrator of the WordPress blog and false otherwise. The add_action () function lets us add functionality to WordPress. The first parameter tells WordPress what kind of action we want to add. The second parameter is the name of the function that will be called by that action. In our example we are adding a menu item under WordPress Administration >> Settings and we are registering our Option settings during the WordPress admin_init action. Next let’s create a function that initializes the 3 Options we are adding to our theme.

6
7
8
9
10
11
12
13
14
15
16
17
18
19

function initWelcomeThemeOptions () {
	/* Welcome Copyright Date */
	if (! get_option ("welcome_copyright_date")) {
		add_option ("welcome_copyright_date", "2009") ;
	}
	/* Welcome Copyright Owner */
	if (! get_option ("welcome_copyright_owner")) {
		add_option ("welcome_copyright_owner", "John Q. Public") ;
	}
	/* Welcome Blog Author */
	if (! get_option ("welcome_blog_author")) {
		add_option ("welcome_blog_author", "Your Name Here") ;
	}
}

The get_option () function will return the value for that option from the WordPress database if it is found or false otherwise. If false is returned then the add_option () function is called to add that option to the database and give the new option the default value. The first parameter is the name WordPress will use for the option and the second parameter is the default value of the option. The only parameter that get_option () takes is the name of the option.

Next we need to create the two functions that we defined in the two add_action () function calls above. Here is the code for these two functions.

21
22
23
24
25
26
27
28
29
30

function registerWelcomeThemeSettings () {
	register_setting ('welcome-theme', 'welcome_copyright_date') ;
	register_setting ('welcome-theme', 'welcome_copyright_owner') ;
	register_setting ('welcome-theme', 'welcome_blog_author') ;
}
 
function Welcome_Theme () {
	initWelcomeThemeOptions () ;
	add_options_page ('Welcome Theme Options', 'Welcome Theme', 8, 'welcome-theme', 'welcome_theme_options') ;
}

The register function is registering the 3 options with WordPress during the admin_init action. The other function calls our initialization function and then add_options_page (). add_options_page () takes a number of parameters. These are in order:

• The name of the options page.
• The name of the menu item under Settings to open the options page.
• The number 8, I have no idea, but it worked. Do your homework!
• The group name for the three options we are adding.
• The function that is called to display the options page.

Next we define the function that displays the options page. Mine is provided below.

32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

function welcome_theme_options () {
	print "<div class=\"wrap\">" ;
	print "<h2>Welcome Theme Options</h2>" ;
	print "<form method=\"post\" action=\"options.php\">" ;
	wp_nonce_field ('update-options') ;		// Checks to see if user can update options and redirects post back to the options page (this form).
	print "<table class=\"form-table\">" ;
 
	/* Welcome Theme Copyright Date Option */
	print "<tr valign=\"top\"><th scope=\"row\">Copyright Date</th><td><input type=\"text\" name=\"welcome_copyright_date\" value=\"" ;
	$temp = get_option ("welcome_copyright_date") ;
	if (! $temp) {
		print "2009\" /></td>" ;
	}
	else {
		print $temp . "\" /></td>" ;
	}
 
	/* Welcome Theme Copyright Owner Option */
	print "<tr valign=\"top\"><th scope=\"row\">Copyright Owner</th><td><input type=\"text\" name=\"welcome_copyright_owner\" value=\"" ;
	$temp = get_option ("welcome_copyright_owner") ;
	if (! $temp) {
		print "John Q. Public\" /></td>" ;
	}
	else {
		print $temp . "\" /></td>" ;
	}
 
	/* Welcome Theme Blog Author */
	print "<tr valign=\"top\"><th scope=\"row\">Blog Author</th><td><input type=\"text\" name=\"welcome_blog_author\" value=\"" ;
	$temp = get_option ("welcome_blog_author") ;
	if (! $temp) {
		print "James J. Legendre\" /></td>" ;
	}
	else {
		print $temp . "\" /></td>" ;
	}
 
	print "</table>" ;
	print "<input type=\"hidden\" name=\"action\" value=\"update\" />" ;
 
	/* Comma separated list of all the options that should be written to the database each time the page is saved. */
	print "<input type=\"hidden\" name=\"page_options\" value=\"welcome_copyright_date,welcome_copyright_owner,welcome_blog_author\" />" ;
 
	settings_fields ('welcome-theme') ;
 
	/* The submit button and closing tags for the form and div. */
	print "<p class=\"submit\">" ;
	print "<input type=\"submit\" class=\"button-primary\" value=\"" ;
	/* _e is used here according to the Wordpress documentation (http://codex.wordpress.org/Creating_Options_Pages) to handle translation of the text. */
	_e ('Save Changes') ;
	print "\" />" ;
	print "</form>" ;	
	print "</div><!-- close wrap -->" ;
}

I think this function is pretty easy to follow. The main thing you need to note is the page_options hidden input and the settings_fields () function call must be included in side the options form for it to work properly. Once we have this we can save and close the file. For the three options I chose I then went to my footer.php file for our theme and edited the content to look like this.

1
2
3
4
5
6
7
8

	<div id="footer">
		<p>Copyright &copy; <?php print get_option ('welcome_copyright_date') ; ?> <?php print get_option ('welcome_copyright_owner') ; ?>, All Rights Reserved | Welcome theme by <a href="http://www.legendrefamily.org/blog/"><?php print get_option ('welcome_blog_author') ; ?></a> | powered by <a href="http://wordpress.org">Wordpress</a>.</p>
		<p><a href="feed:<?php bloginfo('rss2_url'); ?>">Entries RSS</a> | <a href="feed:<?php bloginfo('comments_rss2_url'); ?>">Comments RSS</a> | <?php wp_register('',''); ?></p>
	</div><!-- close footer -->
</div> <!-- Main Container Ends -->
<?php wp_footer(); ?>
</body>
</html>

You can see that I replaced the hard coded values with the get_option () function calls. Once you have updated and saved the footer.php file you should log into your blog as the administrator and go to the Administration >> Settings >> Welcome Theme menu option. There you will see a form to change the 3 options we defined. Change them to whatever value you like and click the Save Changes button. Then log out and browse to your blog site. You should see the new values you entered displayed in the footer of your blog.

Below is a list of the 3 reference links I used when preparing this sample. You can read these if you need more details.

1. http://codex.wordpress.org/Adding_Administration_Menus
2. http://codex.wordpress.org/Creating_Options_Pages
3. http://codex.wordpress.org/Function_Reference/get_option

In the next post we will talk about wrapping this all up (packaging our theme for distribution) and some other final thoughts.