Home

Welcome to the wp-custom-fields wiki! We are glad that you are considering to use WP Custom Fields for your next WordPress development project.

The wp custom fields framework is an options framework for WordPress aimed at speeding-up plug-in and theme development.

WP Custom Fields allows you to:

• Add custom options pages in the admin dashboard
• Add custom meta boxes to posts, taxonomies and users
• Add (custom) customizer fields and panels

Options are divided into sections, which are tabbed by default.

WP Custom Fields also allows to output data from some of its fields to CSS styling on the front-end.

 

Installation

Include the src code within your theme or plugin. Load the required files using an autoloader, either manually or through composer. We also have a sample autoloader available at GitHub.

If you are not using an autoloader, you have to manually require all .php files within the src/ and src/fields/ folder.

 

Create an Instance

Before you can add fields, you have to create an instance of the WP_Custom_Fields framework in the following manner:

$fields = MakeitWorkPress\WP_Custom_Fields\Framework::instance();

If you are going to use the location field, you have to add your google maps api key to the instance in the following way:

$fields = MakeitWorkPress\WP_Custom_Fields\Framework::instance( array('google_maps_key' => 'your_google_maps_key') );

More information on modifying this instance can be found on the Instance Page of this wiki.

 

Adding Custom Fields

This is a basic example of adding an option page to our admin dashboard menu using the previous instance.

$fields->add( 'options', array(
    'class'         => 'tabs-left',
    'id'            => 'wp_custom_fields_options',
    'title'         => __('Theme Options', 'textdomain'),
    'capability'    => 'manage_options',
    'menu_title'    => __('Theme Options', 'textdomain'),
    'menu_icon'     => 'dashicons-admin-generic',
    'menu_position'  => 99,
    'location'      => 'menu',
    'sections'      => array(
        array(
            'id'        => 'section_one',
            'title'     => __('Section One', 'textdomain'),
            'icon'      => 'camera_enhance',
            'fields'    => array(              
                array(
                    'columns'       => 'half',
                    'id'            => 'checkbox',
                    'title'         => __('Example Title', 'textdomain'),
                    'description'   => __('Example Description', 'textdomain'),
                    'type'          => 'checkbox',
                    'style'         => 'switcher',
                    'options'       => array(
                        array( 'id' => 'thing_one', 'label' => __('Label One', 'textdomain') ),
                        array( 'id' => 'thing_two', 'label' => __('Label Two', 'textdomain') )
                    )
                )
            )
        )
    )
);

How to add custom metaboxes, option pages or customizer settings is explained on their respective pages in the wiki.

The possible parameters for each section and field are explained in the fields page.

 

Retrieving Stored Values

The custom fields obviously allow storing custom data to the database.

Option Pages

By default, the data is stored the id of the registered set of options, customizer settings or metaboxes. In the above example, the data saved can be retrieved by:

get_option( 'wp_custom_fields_options' );

In the example above, the data returned would be in the following format (if both boxes were not ticked):

[
    'checkbox' => ['thing_one' => false, 'thing_two' => false]
]

Custom Metaboxes

For a metabox, data can be accessed by default through the following example, where 'id_of_your_metaboxes' is the top level id for your registered metaboxes:

get_post_meta( $id, 'id_of_your_metaboxes', true );

More options for accessing metabox data can be found under Adding Custom Metaboxes.

Customizer Settings

For customizer settings, this can be done by default in the following way, where 'id_of_your_customizer_settings' is the top level id for your registered customizer settings:

get_theme_mod( 'id_of_your_customizer_settings' );