How to create a Wordpress options page

Question

I've followed this guide precisely: http://codex.wordpress.org/Creating_Options_Pages

However when I do do_settings_fields, it says: Missing argument 2 for do_settings_fields() Even though it says to put only one argument in there.

Strangely, the example given on that very same page says to use do_settings() - which appears to not even be a function!

Something tells me I need to create a 'section' as described here: http://codex.wordpress.org/Function_Reference/add_settings_section

But I'd rather find a quick fix for what I've already done. :)

EDIT I've been messing around with it for the past hour, and discovered several wordpress functions which apparently don't exist.. This is my latest code, which doesn't give me an errors, but also doesn't do anything apart from register the menu page:

<?php
// Register the menu
add_action('admin_menu', 'bang_menu');
function bang_menu() {
    add_menu_page( 'BANG! Dashboard', 'BANG!', 'administrator', 'bang-admin', 'bang_dashboard');
}

// Register settings
add_action('admin_init', 'bang_settings');  
function bang_settings() {
register_setting( 'bang-options-group', 'joinform_api_url' ); // Register the setting
add_settings_section( 'bang_section', 'Joinform configuration', null, 'section_options_page_type' ); // Register the section
add_settings_field( 'api_url', 'API URL', 'field_joinform_api_url', 'section_options_page_type', 'bang_section' ); // Define callback function for setting
}


function field_joinform_api_url() {
    echo 'field here...';
}


function bang_dashboard() {

    echo '
    <div class="wrap">
        <div class="postbox-container metabox-holder">
            <div class="postbox">
                <h3>Joinform configuration</h3>

                <form action="options.php" method="post">';
                settings_fields( 'bang-options-group' );
                do_settings_sections( 'bang_section');
etc...

Answer 1

The first thing that jumps out at me is your use of register_setting():

register_setting( 'bang-options-group', 'joinform_api_url' );

It is missing a critical, third argument: the sanitization callback. While this parameter programmatically is optional, without it, you cannot validate/sanitize/whitelist the data values passed to the DB via your settings form.

Looking further at your code, you seem to be misusing all of the parameters passed to register_setting( $group, $option, $callback ): * $group: an options group name; fairly arbitrary, but must be unique * $option: the name of the option as it exists in the DB table * $callback: sanitization callback

As you're calling it, you're telling WordPress that your option name is joinform_api_url, which is itself actually a callback of some sort.

The next problem I see is with your use of do_settings_sections():

do_settings_sections( 'bang_section');

The correct parameter for this function is the $page parameter of your call to add_settings_section( $id, $title, $callback, $page ):

add_settings_section( 'bang_section', 'Joinform configuration', null, 'section_options_page_type' );

As you can see, you're passing the $id parameter, rather than the $page parameter, to do_settings_sections().

Also, you're passing null for the section callback parameter. Why?

I completely understand how difficult it can be to keep the function parameter correlation straight among all of the Settings API-related functions. As part of my Settings API tutorial, I included a section to help keep track of this correlation. It may be helpful as you step through your implementation.

Finally: I would recommend putting this together one step at a time, rather than trying to cobble it all together, and then trying to troubleshoot. That way, you find out at each step where any potential problem exists, and can resolve it before that problem compounds itself with each additional step.

1. Add settings page to menu
2. Define settings page callback
3. Register setting
4. Add settings sections
5. Add settings fields
6. Define settings sections callbacks
7. Define settings fields callbacks
8. Add sanitization callback

Step through each, one at a time, paying attention to the function-parameter correlation at each step. Ensure that you get expected output before moving to the next step.

Usually, once you've gotten a working example one time using this method, it just "clicks". But is can be incredibly confusing/daunting until you do.