# The Section Object
The primary grouping of fields within Redux is called a section
. Each section is unique and creates a grouping of all
the fields within it. A section contains a fields array and any number of fields. A number of
API methods are provided to set, manipulate, and remove sections before they are rendered to the user.
Table of Contents
# Arguments
Name | Type | Description. |
---|---|---|
id | string | The unique identifier of a section. If not provided, the title field will be used to generate a unique identifier. |
title | string | The title of the section that will appear on the option tab. |
heading | string | Text to appear at the top of the section page. By default the title argument is used as the heading . This can be overriden by using this argument. |
desc | string | Text to appear under the section title. HTML is permitted. |
class | string | Appends any number of classes to the section’s class attribute. |
icon | string | The icon to be displayed next to the section title. This could be a preset Elusive Icon or a URL to an icon of your own. |
icon_type | string | Set to image when using a custom URL to an icon. |
permissions | string | String specifying the capability required to view the section. See Using Permissions. |
fields | array | An array of field arrays contained within this section. |
customizer_only | bool | A flag to set all fields below this section to customizer_only display. This can be overriden at the field level. |
subsection | bool | Flag to denote if this section should appear as a subsection to the previously defined section. |
disabled | bool | Flag to set the disabled state of the section. |
SEE ALSO
# Setting Section(s)
There are two methods to set a section in Redux. The only difference between these two declarations is one is singular while the other is plural.
# Redux::set_section()
Used to declare a single section containing fields.
Arguments to pass in order of declaration
Name | Type | Description |
---|---|---|
opt_name | string | Your unique opt_name |
section | array | A singular section array |
replace | bool | If true , any section with this same ID will be replaced. If false (default), a varied section ID will be generated. |
Redux::set_section( 'OPT_NAME', array(
'title' => 'New Section',
'icon' => 'el-icon-cogs',
'heading' => 'Expanded New Section Title',
'desc' => '<br />This is the section description. HTML is permitted.<br />',
'fields' => array(
array(
'id' => 'opt-text',
'type' => 'text',
'title' => 'A sample text box',
),
),
) );
# Adding a section with the same ID
To reduce errors, if a section already exists with that ID, a new one will be generated to ensure a unique section ID.
# Updating an existing section
If you wish, you can change the default behavior and replace an existing section by passing a new section array with a same section_id, and then passing true for the replacement variable. All data between the two sections will be merged. i.e., you can only update values this way. If you wish to remove values, you will need to use remove_section outlined below.
Redux::set_section(
'OPT_NAME',
array(
'title' => 'New Section',
'icon' => 'el-icon-cogs',
'heading' => 'Expanded New Section Title',
'desc' => '<br />This is the section description. HTML is permitted.<br />',
'fields' => array(
array(
'id' => 'opt-text',
'type' => 'text',
'title' => 'A sample text box',
),
),
),
true
);
# Redux::set_sections()
Similar to ::set_section(), but used to set an unlimited number of sections containing fields at once.
Arguments to pass in order of declaration
Name | Type | Description |
---|---|---|
opt_name | string | Your unique opt_name |
sections | array | Array of section arrays |
This method allows for multiple sections to be added at once. Keep in mind that you can still set a single section, as seen below, but you should remember to wrap the section in an array.
Redux::set_sections(
'OPT_NAME',
array(
array(
'title' => 'New Section',
'icon' => 'el-icon-cogs',
'heading' => 'Expanded New Section Title',
'desc' => '<br />This is the section description. HTML is permitted.<br />',
'fields' => array(
array(
'id' => 'opt-text',
'type' => 'text',
'title' => 'A sample text box',
),
),
)
)
);
# Section Helper Functions
A number of helper functions have been baked into the Redux API to support modifying a section before it gets rendered. These functions have specific use cases and are not often employed by the typical developer, but they are useful when needed.
TIP
Execution order is important here. If you try to fetch a section before it has been called within your code, it will not exist. If you believe a section should exist, make sure you're not in an early loading hook when working with that section.
# Redux::get_section()
Arguments to pass in order of declaration
Name | Type | Description |
---|---|---|
opt_name | string | Your unique opt_name |
section_id | string | Unique id of the section you wish to retrieve |
Say you want to fetch a section object, you can easily do that. This may be useful if you wanted to check the section
array by ID. Returns false
if the section cannot be identified.
$section = Redux::get_section( 'OPT_NAME', 'SECTION_ID' );
# Redux::get_sections()
Now let's say you want to grab all sections for a given opt_name, you can do that too.
Arguments to pass in order of declaration:
Name | Type | Description |
---|---|---|
opt_name | string | Your unique opt_name |
$sections = Redux::get_sections( 'OPT_NAME' );
# Redux::remove_section()
Arguments to pass in order of declaration
Name | Type | Default | Description |
---|---|---|---|
opt_name | string | Your unique opt_name | |
section_id | string | Unique id of the section you wish to retrieve | |
delete_fields | bool | false | If set to true, all fields below will be deleted as well |
This method allows you to remove a section by ID from Redux. It can be useful to update a field as follows:
$section = Redux::get_section( 'OPT_NAME', 'SECTION_ID' );
$section['title'] = esc_html__( 'A New Section Title', 'your-textdomain-here' );
Redux::set_section( 'OPT_NAME', $section );
← Fields