Build a WordPress Theme Options Page With Carbon Fields

What’s Carbon Fields?

Carbon Fields is a free WordPress library developed by 2create. It helps WordPress theme and plugin builders create further fields for submit varieties, navigation menus, widgets, and so forth., and even register customized Gutenberg blocks with out touching JavaScript. 

As we’ll see, alongside the best way, it comes with varied fields like checkboxes, repeaters (complicated), texts, and so forth. 

So, at this level, if you wish to observe this tutorial, first set up Composer, then set up Carbon Fields by working this command:

1

composer require htmlburger/carbon-fields

What’s a WordPress Theme Choices Web page?

A theme choices web page is an admin web page, positioned outdoors the default WordPress pages, the place builders retailer international settings which have an effect on the performance of their WordPress web site or plugin.

For instance, there is likely to be choices for managing issues like:

• Header conduct—whether or not it ought to be sticky or not.
• Typography settings—the worldwide font dimension, the worldwide font, the colours of the headings, and so forth.  

Carbon Fields Underscore

The info are often saved within the *_options desk and accessible on any web site web page.

It’s price noting that the Carbon Fields library mechanically prefixes all fields with an underscore when saved within the database (e.g. the footer_text area turns into _footer_text).

Implementation

For this demonstration, we’ll create an options page that may maintain info for the header structure, footer structure, contact data, and social channels of a demo web site. 

Please notice that the principle focus will likely be to create the web page construction within the admin and solely present the fields on the entrance finish with out including any types. All of the theme recordsdata will likely be accessible on this GitHub repo.

As standard, I’ll work with my customized Playground theme—I’ll depart it as barebone as doable and solely add the required performance for the Carbon Fields.

With that in thoughts, following the docs, I’ll add this code contained in the capabilities.php:

1

use Carbon_FieldsContainer;

2

use Carbon_FieldsSubject;

3

4

operate crb_attach_theme_options() {

5

    Container::make( 'theme_options', __( 'Theme Settings', 'playground' ) )

6

    ->set_page_menu_position( 4 )

7

    ->set_icon( 'dashicons-admin-settings' )

8

    ->add_tab(

9

        __( 'Header', 'playground' ),

10

        array(...),

11

    )

12

    ->add_tab(

13

        __( 'Contact', 'playground' ),

14

        array(...)

15

    )

16

    ->add_tab(

17

        __( 'Socials', 'playground' ),

18

        array(...)

19

    )

20

    ->add_tab(

21

        __( 'Footer', 'playground' ),

22

        array(...)

23

    );

24

}

25

add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' );

26

27

operate crb_load() {

28

    require_once( 'vendor/autoload.php' );

29

    Carbon_FieldsCarbon_Fields::boot();

30

}

31

add_action( 'after_setup_theme', 'crb_load' );

This code will wrap all of the fields inside a container and create a brand new menu merchandise known as Theme Settings beneath the Dashboard menu merchandise. In fact, you possibly can customise the merchandise’s location and the rendered icon.

Plus, the add_tab technique will give a greater group, because it’ll group all our choices web page fields into 4 tabbed sections. 

Let’s now have a more in-depth take a look at these tabs!

Header Tab

The header tab will embrace fields associated to the header performance. Extra particularly:

• A checkbox area will handle whether or not a ribbon will seem above the principle header.
• Three fields (one rich text and two color fields) will set the ribbon’s look. Nevertheless, these will seem and be practical provided that the earlier checkbox area is chosen.
• A header scripts area will permit us to embed the Font Superior 6 icon library within the head tag. We’ll use that library for printing the social icons—we’ll get again to it in an upcoming part.

We’ll create all of the fields via the make technique like this:

1

Subject::make( 'header_scripts', 'header_scripts', __( 'Header Scripts', 'playground' ) ),

2

Subject::make( 'rich_text', 'header_ribbon', __( 'Ribbon', 'playground' ) )

3

->set_conditional_logic(

4

    array(

5

        array(

6

            'area' => 'show_header_ribbon',

7

            'worth' => true,

8

        ),

9

    )

10

),

11

Subject::make( 'shade', 'header_ribbon_text_color', __( 'Ribbon Textual content Shade', 'playground' ) )

12

->set_conditional_logic(

13

    array(

14

        array(

15

            'area' => 'show_header_ribbon',

16

            'worth' => true,

17

        ),

18

    )

19

),

20

Subject::make( 'shade', 'header_ribbon_bg_color', __( 'Ribbon Background Shade', 'playground' ) )

21

->set_conditional_logic(

22

    array(

23

        array(

24

            'area' => 'show_header_ribbon',

25

            'worth' => true,

26

        ),

27

    )

28

),

29

Subject::make( 'checkbox', 'show_header_ribbon', __( 'Present Ribbon (Prime Header)?', 'playground' ) )->set_option_value( 'sure' ),

Then, wherever we need to show them, we’ll use the carbon_get_theme_option technique and cross as an argument the sector title like this:

1

<?php 

2

$show_header_ribbon = carbon_get_theme_option( 'show_header_ribbon' );

3

?>

4

5

<header class="site-header">

6

    <nav>

7

        <?php 

8

        if ( $show_header_ribbon ) : 

9

            $header_ribbon            = carbon_get_theme_option( 'header_ribbon' );

10

            $header_ribbon_text_color = carbon_get_theme_option( 'header_ribbon_text_color' ) ? carbon_get_theme_option( 'header_ribbon_text_color' ) : '#000';

11

            $header_ribbon_bg_color   = carbon_get_theme_option( 'header_ribbon_bg_color' ) ? carbon_get_theme_option( 'header_ribbon_bg_color' ) : 'clear';

12

            ?>

13

            <div class="header-top" fashion="shade: <?php echo esc_attr( $header_ribbon_text_color ); ?>; background: <?php echo esc_attr( $header_ribbon_bg_color ); ?>">

14

                <?php echo wp_kses_post( $header_ribbon ); ?>

15

            </div>

16

        <?php endif; ?>

17

        <div class="header-bottom">A pleasant header right here</div>

18

    </nav>

19

</header>

Contact Tab

The contact tab will embrace contact-related fields that will likely be current throughout completely different web page sections (e.g. on the header, footer, contact pages, sidebars, and so forth.). Extra particularly, there will likely be:

• A textarea area for including the corporate handle. 
• A textual content area for linking to a Google Maps location.
• A textual content area for including the corporate telephone.
• A textual content area for including the corporate mail.
• A select area with dynamic choices for permitting customers to select the suitable Contact Form 7 (CF7) kind as a publication kind.

Think about that our web site comprises the next types:

We should always make all of them accessible to the admin customers. However right here’s the problem: we received’t hardcode them however as an alternative make all of the choices of the choose area dynamic.

To perform this, we’ll outline the customized get_all_forms operate and cross it as a parameter of the add_options technique of our choose area. This operate will return all the location types in an array format. 

Right here’s how we create the fields of this tab:

1

Subject::make( 'textarea', 'handle', __( 'Deal with', 'playground' ) ),

2

Subject::make( 'textual content', 'address_directions', __( 'Deal with Instructions', 'playground' ) )->set_attribute( 'sort', 'url' ),

3

Subject::make( 'textual content', 'telephone', __( 'Cellphone', 'playground' ) )->set_attribute( 'sort', 'tel' ),

4

Subject::make( 'textual content', 'e mail', __( 'E-mail', 'playground' ) )->set_attribute( 'sort', 'e mail' ),

5

Subject::make( 'choose', 'newsletter_form', __( 'Choose Publication Type', 'playground' ) )

6

->add_options( 'get_all_forms' ), // or set

And right here’s the get_all_forms() declaration:

1

operate get_all_forms() {

2

    $all_forms_array = array();

3

    $all_forms       = get_posts(

4

        array(

5

            'post_type'      => 'wpcf7_contact_form',

6

            'posts_per_page' => -1,

7

        )

8

    );

9

10

    foreach ( $all_forms as $kind ) :

11

        $all_forms_array[ $form->ID ] = esc_html( $kind->post_title );

12

    endforeach;

13

    return $all_forms_array;

14

}

Subsequent, we output the fields within the location we wish like this:

1

<?php 

2

$handle         = carbon_get_theme_option( 'handle' );

3

$instructions      = carbon_get_theme_option( 'address_directions' );

4

$telephone           = carbon_get_theme_option( 'telephone' );

5

$e mail           = carbon_get_theme_option( 'e mail' );

6

$newsletter_form = carbon_get_theme_option( 'newsletter_form' );

7

?>

8

9

<handle>

10

    <?php echo wp_kses_post( $handle ); ?>

11

    <a href="<?php echo esc_url( $instructions ); ?>" goal="_blank">

12

        <?php esc_html_e( 'See Map', 'playground' ); ?>

13

    </a>

14

    <a href="<?php echo esc_url( 'tel:' . $telephone ); ?>">

15

        <?php echo esc_html( $telephone ); ?>

16

    </a>

17

    <a href="<?php echo esc_url( 'mailto:' . $e mail ); ?>">

18

        <?php echo esc_html( $e mail ); ?>

19

    </a>

20

</handle>

21

22

<div>

23

    <?php echo do_shortcode( '[contact-form-7 id="' . esc_attr( $newsletter_form ) . '"]' ); ?>

24

</div>

Socials Tab

The socials tab will embrace a complex area for including an infinite variety of socials. Every social can have three textual content fields:

• A textual content area for the social title (e.g. Fb).
• A textual content area for the social URL.
• A textual content area for putting Font Superior lessons (e.g. Facebook classes). 

For these of you coming from the ACF world, the complicated area is equal to ACF’s repeater area.

Right here’s how we create the complicated area by way of code:

1

<?php 

2

Subject::make( 'complicated', 'socials' )

3

->set_layout( 'tabbed-horizontal' )

4

->add_fields(

5

    array(

6

        Subject::make( 'textual content', 'social_title', __( 'Social Title', 'playground' ) ),

7

        Subject::make( 'textual content', 'social_url', __( 'Social URL', 'playground' ) )->set_attribute( 'sort', 'url' ),

8

        Subject::make( 'textual content', 'social_icon', __( 'Social Icon', 'playground' ) )

9

        ->set_attribute( 'placeholder', 'Add a category from the Font Superior library' ),

10

    )

11

),

And right here’s how we print their information wherever we wish:

1

<?php 

2

$socials = carbon_get_theme_option( 'socials' );

3

?>

4

5

<ul>

6

    <?php

7

    foreach ( $socials as $social ) :

8

        //https://github.com/WordPress/WordPress-Coding-Requirements/points/1029

9

        /* translators: %s: social channel */

10

        $title = sprintf( __( 'Discover us on %s', 'playground' ), $social['social_title'] );

11

        ?>

12

        <li>

13

            <a href="<?php echo esc_url( $social['social_url'] ); ?>" aria-label="<?php echo esc_attr( $title ); ?>" title="<?php echo esc_attr( $title ); ?>" goal="_blank">

14

                <i class="<?php echo esc_attr( $social['social_icon'] ); ?>" aria-hidden="true"></i>

15

            </a>

16

        </li>

17

    <?php endforeach; ?>

18

</ul>

Footer Tab

Just like the header tab, the footer tab will embrace fields associated to the footer performance. Extra particularly:

• A textual content area will output the footer textual content.
• Two shade fields will set the footer’s foreground and background colours.

As standard, we create them with the make technique:

1

Subject::make( 'rich_text', 'footer_text', __( 'Footer Textual content', 'playground' ) ),

2

Subject::make( 'shade', 'footer_text_color', __( 'Footer Textual content Shade', 'playground' ) ),

3

Subject::make( 'shade', 'footer_bg_color', __( 'Footer Background Shade', 'playground' ) ),

And we show them within the goal file:

1

<?php 

2

$footer_text       = carbon_get_theme_option( 'footer_text' );

3

$footer_text_color = carbon_get_theme_option( 'footer_text_color' ) ? carbon_get_theme_option( 'footer_text_color' ) : '#000';

4

$footer_bg_color   = carbon_get_theme_option( 'footer_bg_color' ) ? carbon_get_theme_option( 'footer_bg_color' ) : 'clear';

5

?>

6

7

<footer class="site-footer" fashion="shade: <?php echo esc_attr( $footer_text_color ); ?>; background: <?php echo esc_attr( $footer_bg_color ); ?>">

8

    <div class="container">

9

        <?php echo wp_kses_post( $footer_text ); ?>

10

    </div>

11

</footer>

Conclusion

On this tutorial, we went via the Carbon Fields WordPress customized fields toolkit and explored a lot of its area varieties by constructing a Theme Choices web page. I hope you now have sufficient materials to determine whether or not this library can fit your wants to your subsequent WordPress challenge. 

In brief, go along with it if:

• You need one thing free and aren’t an enormous fan of extending the WordPress Customizer.
• You’ll be able to work with out an administration interface.
• You construct a plugin/theme that requires a small variety of fields.

Alternatively, you may need second ideas of utilizing it if:

• You don’t have an issue paying for a WordPress plugin that gives extra sort choices and structure styling like ACF PRO.
• You like to handle your fields via a UI and really feel overwhelmed managing them via code.
• Apart from not obligatory, should you’re constructing a multilingual web site/plugin, you may need to choose options which are formally supported by the interpretation device you select. For instance, though Carbon Fields appears to work positive with WPML in line with their docs and my native exams, this device isn’t officially compatible with WPML.  

However with none doubt, it is a useful device that each WordPress developer ought to attempt at the very least as soon as. What about you? Have you ever ever used that? Tell us on X!

As at all times, thanks lots for studying!