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 and in the network admin dashboard if you're using multisites.
• 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. Please view the respective pages for adding custom fields to understand how it should be done.

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. You can also read more about autoloading in the readme of wp-autoload. Please aware that you still need to adapt this autoloader to the folder structure of your project.

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

Manual autoloading using composer

If you are using a manual autoloader, but load the package using composer, please use the following set-up:

/**
 * Registers the autoloading\
 */
spl_autoload_register( function($classname) {
    
    // Loads any class placed within the classes folder, and namespaced correctly
    $class      = str_replace( '\\', DIRECTORY_SEPARATOR, str_replace( '_', '-', strtolower($classname) ) );
    $classes    = dirname(__FILE__) .  DIRECTORY_SEPARATOR . 'classes' . DIRECTORY_SEPARATOR . $class . '.php';
    
    // Loads classes from the vendor/makeitworkpress folder using autoloading
    $vendor     = str_replace( 'makeitworkpress' . DIRECTORY_SEPARATOR, '', $class );
    $vendor     = 'makeitworkpress' . DIRECTORY_SEPARATOR . preg_replace( '/\//', '/src/', $vendor, 1 ); // Replace the first slash for the src folder
    $vendors    = dirname(__FILE__) .  DIRECTORY_SEPARATOR . 'vendor' . DIRECTORY_SEPARATOR . $vendor . '.php';

    // Check if the files exist
    if( file_exists($classes) ) {
        require_once( $classes );
    } elseif( file_exists($vendors) ) {
        require_once( $vendors );    
    }
   
} );

Your composer.json placed in the root of your project should look at least like this:

{
    "name": "vendor/package",
    "description": "Your description",
    "repositories": [              
        {
            "type": "vcs",
            "url": "https://github.com/makeitworkpress/wp-custom-fields.git"
        }             
    ],
    "require": {
        "php": ">=5.3",
        "makeitworkpress/wp-custom-fields": "dev-master"
    },
    "license": "GPL",
    "homepage": "https://github.com/name/repo/",
    "authors": [ 
        {
            "name": "Author Name",
            "email": "hello@name.domain",
            "homepage": "https://name.domain"

        } 
    ]          
}

You can install and update packages from repositories in composer using the composer update --prefer-dist command in your command-line, obviously being in the right 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( ['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 meta boxes. 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 meta box 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' );