# Fields Object

Fields are the lowest level object within Redux. They constitute the type of fields that appear in any given section. Though individual fields may have custom arguments, they all share a common set of default arguments.

# Default Arguments

Name Type Required Description.
id string true The unique identifier of a field. MUST be unique to the opt_name except when used by the metaboxes API.
type string true Denotes the field type. If the field type does not exist a warning will be displayed.
title string The title of the field that will be displayed.
subtitle string Subtitle of the option placed beneath the title.
desc string Text to appear under the field title. HTML is permitted.
default string Default value for the field.
class string Appends any number of classes to the field's class attribute.
customizer_only bool A flag to set this field to customizer_only display. This argument will override the customizer_only setting at the sections level as well as the global arguments level.
output bool A flag to set all enable CSS output for any fields that support this argument.
compiler bool A flag to set the compiler hook to fire if this field's value is changed. This can override the compiler setting at the sections level.
disabled bool false Flag to set disabling on the field.
hints array Array of attributes that sets the hints object to display an animated window with more details about this field.

Fields are blocks of arrays that represent the individual options within a specific options panel, set via a section array. The section array contains an argument titled fields, which accepts an array, or several blocks of arrays, separated by commas.  This is where all field arrays are place.  A basic example is shown below. For specific examples, please consult the sample-config.php (opens new window) file that comes with the Redux package.

# Setting Fields(s)

There are two methods to set a field in Redux. The only difference between these two declarations is one is singular while the other is plural.

WARNING

If the section you are attaching to doesn't exist, that field will never show. It's much easier to use Redux::set_section() instead to define a section with embedded fields all at once.

# Redux::set_field()

Used to declare a single field and attach to an existing section.

Arguments to pass in order of declaration

Name Type Description
opt_name string Your unique opt_name
field array A singular field array
section_id string Section ID to add this field to. Must previously exist.
Redux::set_field( 
    'OPT_NAME', 
    'SECTION_ID', 
    array(
        'id'    => 'opt-text',   
        'type'  => 'text',
        'title' => 'A sample text box',
    ) 
);

# Redux::set_fields()

Similar to ::set_field(), but used to set an unlimited number of fields at once.

Arguments to pass in order of declaration

Name Type Description
opt_name string Your unique opt_name
fields array Array of fields arrays
section_id string Section ID to add this field to

This method allows for multiple sections to be added at once. Keep in mind a single section may be set, as seen below. Remember to wrap the section in an array.

Redux::set_fields( 
    'OPT_NAME', 
    'SECTION_ID', 
    array(
        array(
            'id'    => 'opt-text1',   
            'type'  => 'text',
            'title' => 'A sample text box1'
        ),
        array(
            'id'    => 'opt-text2',   
            'type'  => 'text',
            'title' => 'A sample text box2'
        )
    ) 
);

# Field Helper Functions

A number of helper functions have been baked into the Redux API to support modifying a field before it gets rendered. These functions have specific use cases and are seldom employed by the typical developer, but they are useful when needed.

TIP

Execution order is important. Fetching a field before it's been called within your code will fail. If you believe a field should exist, ensure it's not in an early loading hook when working with that field.

# 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

Fetching a section object is easily achieved. This may be useful in checking the section array by ID. Returns false if the section cannot be identified.

$section = Redux::get_section( 'OPT_NAME', 'SECTION_ID' );

# Redux::get_sections()

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 a section removal by ID. Updated a field as follows:

$section = Redux::get_section( 'OPT_NAME', 'SECTION_ID' );
$section['title'] = esc_html__( 'A New Section Title', 'redux-framework' );
Redux::set_section( 'OPT_NAME', $section );