Options panel struggles continue - day 4

Things aren't going so well creating an options panel.  Today I learned that the method I've been using to create an options panel is outdated and that there's a settings api that I could be using instead: http://codex.wordpress.org/Settings_API

When going through the tutorial (in my last post) I started picking up on this bit by bit.  So for the rest of this post I'm taking down some notes on this settings api as I work my way through this tutorial series: http://wp.tutsplus.com/series/the-complete-guide-to-the-wordpress-settings-api/
btw I'm starting the options panel from scratch now (but keeping theme-options.php) in a new file (better-options.php).

So yea, this api is supposed to facilitate the processes of:

• introducing menus
• option pages
• saving (I'm looking forward to this lol)
• validating
• retrieving user input

You should use the api because it's secure and properly manages (my mistake).

There are three main components of the api:

1. Fields - single inputs (options) that you'll see on menu pages like textboxes, radio buttons, selects, etc.  They hold the value that gets put in the db.
2. Sections - are used for grouping (usually related) fields.  Normally used so each section is its own menu page.
3. Settings get registered after you've defined your fields and sections.

Creating a section uses the add_settings_section function I learned about before: http://codex.wordpress.org/Function_Reference/add_settings_section

add_settings_section(ID, Title, Callback, Page);

• ID - identifier for the section.  The value is used in registering the field within each section and can be named anything (keep it meaningful).
• Title - a value displayed at the top of the page as an (h1 or h3 or something).
• Callback - the name of the function where the code for displaying certain elements for the section will go.
• Page - this value tellswp which page your options are displayed on.

This is a reference for some page keys:

• General, “general”
• Writing, “writing”
• Reading, “reading”
• Discussion, “discussion”
• Media, “media”
• Privacy, “privacy”
• Permalinks, “permalink”

The add_settings_field function gets used to ad fields: http://codex.wordpress.org/Function_Reference/add_settings_field

add_settings_field(ID, Title, Callback, Page, Section, Arguments);

• ID - ID of the field and used in saving and retrieving the value (keep it meaningful).
• Title - value that turns into the title of the field option on the page.
• Callback - Same as in section.
• Page - identifies which page the option should be on and can be added to an existing page rather than a section that's already been defined.
• Section - the ID of the section you created earlier when registering sections.  (optional param)
• Arguments - array of arguments that get brought to the callback func.  (optional param)

Now after you add some sections and fields they still will not save.  Why?  Because they weren't registered with the register_setting function yet: http://codex.wordpress.org/Function_Reference/register_setting

register_setting(Option Group, Option Name, Callback);

• Option Group - Name of the group of options.  This will be and existing group of options in wp or an ID that we made when we created our section.  (required)
• Option Name - The ID of the field we're registering.  If registering multiple fields, you'd have to call this function multiple times.  (required)
• Callback - Same as section and field.  (optional)

Now to use these options you created, the get_option function comes into play: http://codex.wordpress.org/Function_Reference/get_option

get_option(Option ID, Default Option);

• Option ID - the ID of the field that you want the value of. (required)
• Default Option - the value if the option returns nothing (like if it didn't exist in the db).  (optional)

Well that's all I'm going through for today.  By applying all this knowledge (and the little programming skill I have), I've come up with this as my functions file: http://pastebin.com/ZkGkiMVP

I've also applied these options to my themes header file: http://pastebin.com/FzBUbxF9

So this is what this code looks like:

At the end of the day, I'm happy to finally be getting somewhere with the options panel without having to copy and paste massive amounts of code.  With this settings api, I actually understand what's going on now so tonight I can go to sleep a little less pissed off than usual ;)