Organize a Form with Sections

Organizing a Form with Sections

We now know it’s fairly easy to create form fields with Admin Page Framework (see Create a Form). What happens if you add many fields in a form in a single page? It will get messy and your users will have a hard time finding the right option to fill in.

If you have published a plugin/theme, you may have seen your user having troubles finding the option to change to get their desired results. One way to solve such a problem is to group fields by section. So you can direct your user by telling them which section that the option the user looking for belongs to.

To create form sections with Admin Page Framework, you just need to tell the framework which field belongs to which section. That’s pretty much it.

Steps

1. Include the library
2. Extend the library class
3. Define the setUp() method
4. Define sections and fields
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, we use APF_CreateForm for the class name.

Define the setUp() method

In the setUp() method, we define the admin pages to be created. 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 sections and fields

To keep things simple, we only add two sections in this tutorial but it’s not limited to two and you can create sections and fields as many as necessary.

To define sections use the addSettingSecions() method and when you use the  addSettingFields() method, tell it which section the field should belong to.

Section Definition Arguments

• section_id – (required, string) the section id.
• page_slug – (optional, string) the page slug that the section belongs to. If the target page slug is set, it can be omitted.
• and more. (for more details check out the documentation page for the method: addSettingSections())

Pass the target page slug to the first parameter and the section definition argument arrays to the rest.

Next add fields to the sections we just added. Pass the target section ID to the first parameter and the field definition array to the rest.  Notice the first field definition array contains empty arrays to create sub-fields. This is used to create multiple fields that share the same field settings with in a field. You can add as many sub-fields as you need.

For the first section,  notice that the second field definition array has the repeatable key set to true. This makes the field repeatable, that is, the user can dynamically add/remove a copy of the field by pressing the add/remove button.

For the second section, we add the checkbox, select, radio, and submit types of fields. The last one has the show_title_column key set to false. This disables the title column of the field row. So the field output starts from the beginning of the row.

Instantiate the extended class

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

Retrieve the saved options

To retrieve the options, we can use the get_option() function. We’ve already covered it in a previous tutorial (see Create a Form). But now we have sections. When a section is set, the framework adds the section dimension to the saved option array and field values will be stored in the section dimension.

So the code to retrieve the option array in this particular tutorial project would be $data = get_option( ‘APF_CreateForm’ );  to retrieve the field value, say, my_text_field of the my_first_section section, you would do something like this.

Alternatively, the framework has the method to retrieve the option data and it reduces the necessity to call the isset() function to check the existence of the key. We’ve covered this also in the previous tutorial but this time, there is the section dimension. So let’s see how the method is used to specify the section and the field.

Notice that the second parameter is an array and it represents the keys of the each dimension.

Code

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