Create a Setting Form

Creating a Setting Form

Now we’ve learnt how to create an admin page in the previous tutorial. Next, let’s create a form so that your users can store options. This is very simple as well.

Steps

  1. Include the library
  2. Extend the library class
  3. Define the setUp() method
  4. In the setUp method, define the form elements.
  5. Instantiate the extended class
  6. Retrieve the saved options

Screenshot

Creating a Setting Form

Include the library

The library file needs to be loaded.

Extend the library class

This time, let’s use APF_AddFields for the class name.

Define the setUp() method

In the setUp() method, we define the admin pages to create. For that, we need to decide:

  1. the root page.
  2. the sub page title.
  3. the sub page slug.

We’ve covered this already in the previous tutorial.

Define the form elements

Now it’s time to decide what kind of form elements to create.

We are going to define the form in the load_{page slug} callback method which is triggered when the page starts loading. Although it is possible to define the form in the setUp() method, since the load_{…} callback method Is only triggered when the registered page loads, it saves some overhead compared to defining the form in the setUp() method which is triggered in all the admin pages.

To define the form, we need to tell the framework to create form fields by passing field definition array to the  addSettingFields() method. Though there are required keys to remember for the field definition arrays.

Field Definition Arguments

  • field_id – ( required, string ) the field ID. Avoid using non-alphabetic characters except underscore and numbers.
  • type – ( required, string ) the type of the field. The supported types are listed below.
  • and more. (for more details check out the documentation page for the addSettingFields().)

Okay, so let’s try creating very simple ones, a text input field, a text area field, and a submit button.

In the above code, there may be unfamiliar array arguments for you such as title, description, and default. The title argument will set the field title. The description argument sets the field description that will be placed below the input field. And the default argument sets the default value which is applied when no data is set by the user. There are lots of other keys that allow you to  customize the fields. So check out the demo plugin and the documentation for more examples.

Instantiate the extended class

Finally, we instantiate the class. Unless it is instantiated, it will do nothing.

Retrieve the saved options

So far the framework does everything for you, creating the page, the form, and saving the user input. But how do we get the stored user input?

For that, use the get_option() function as the framework stores the data as an serialized array into the options database table. What about the option key then? The framework by default uses the class name as the option key. So your code in this particular tutorial project will be $data = get_option( ‘APF_AddFields’ );.  The $data variable will hold an array of options with the keys of form field IDs or section IDs depending on how you construct the form fields.

For example, if you need to retrieve the value of the field whose id is my_text_field, do something like, the following.

The option key to pass to the get_option() function can be changed with one of the parameters of the class constructor when you instantiate the class. For more details, check out the __construct() method of the manual.

Alternatively, you may use the AdminPageFramework::getOption() static method. This method reduces the necessity of calling the isset() method to check if an array key is set. The first parameter accepts the option key like the get_option() function. The second parameter takes the array key. The third parameter is for the default value when no value is set to the given key. So you use it like this.

Code

Try the code below and post comments if you get a problem.

7 thoughts on “Create a Setting Form”

  1. Hi,

    Outstanding work!!

    I want to know if it is possible to save data to a custom table.

    Thanks in advance.

    1. Hi,

      The framework does not have any methods to handle custom tables.

      If you have to do it, you can do so in the validation callback method. The first parameter receives the user inputs. You can store them by using your own functions. In order to prevent the framework from saving user inputs in the options table, pass an empty string to the class constructor parameter that specifies the option key. Passing an empty key will tell the framework not to save data.

      Then hook into options_{instantiated class name} filter and in its callback method, retrieve your user’s data of the structure of an associative array and then return it back so that your custom table data will be reflected. The options data structure (associative array) should follow the structure of the framework. You want to check it in the validation callback and dump the user inputs.

  2. Hi Michael,

    thank you very much for this framework and tutorial, it has been very useful.
    I’m created a form to save some custom theme settings, for example to save the categories which will be displayed in the homepage. How do I get the values saved in this form so to use them in a WP_query in my home template?
    I’ll be very grateful if you could help me solve this.

    1. Use the get_option() function. The option key is the extended class name by default unless you set it in the class constructor. See how it retrieves the option values in this tutorial in the do_my_first_forms() method. You can do the same thing in the front-end except using the class specific methods.

Leave a Reply

Your email address will not be published. Required fields are marked *