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

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.