Configuration

better-wordpress makes theme configuration easy.

Getting Started

Unlike the traditional WordPress method of defining your theme options programmatically in the functions.php file, better-wordpress opts for a simpler, more centralized approach.

With better-wordpress, options like custom post types, menu locations, options pages, and more can be configured from a single array in the config.php file.

By default, your config.php file will look something like this:

config.php
<?php

return [
    // how many words should the wordpress excerpt be
    "excerpt-length" => 100,

    // optionally append this css classname to the body_class for guests
    "guest-class" => "null",

    // register your individual menu locations
    "menu-locations" => [
        "main-nav" => "Main Navigation",
        "footer-nav" => "Footer Navigation",
    ],

    // here is where you can define your custom post types
    "custom-post-types" => [
        [
            "slug" => "thing",
            "icon" => "dashicons-tide",
            "options" => [
                "supports" => ['title', 'editor', 'thumbnail', 'comments']
            ]
        ],
    ],

    // optionally adjust a couple of attributes for handlebars here
    "handlebars" => [

        // if you need to register additional Handlebars Helpers, register them here
        "additional-helpers" => [],

        // adjust the extension for your handlebars template files, .tpl by default
        // "template-extension" => "tpl",
    ],

    // enable individual wordpress features here
    "enable" => [
        "post-thumbnails",
        "menus",
    ],

    // disable individual wordpress features here
    "disable" => [
        "editor",
    ],
];
The default config.php that comes with better-wordpress.

If you ever need to reset your config.php file, recall that this example lives in the vendor/open-function-computers-llc folder of your project.

Custom Post types

One of the most convenient features of better-wordpress is the ability to define custom post types without ever leaving the configuration array.

For example, if I wanted to make a custom “Album” post type for my music blog:

config.php
"custom-post-types" => [
    [
        "slug" => "album",
        "icon" => "dashicons-album",
        "taxonomies" => ['genre'],
    ],
],
Declaring a simple custom post type. List of Dashicons.

In this configuration, a new custom post type with the name “Album” will be created, along with a “Genre” taxonomy if it doesn’t already exist.

A more in-depth configuration would look like this, wherein custom labels are specified and various options are set.

config.php
"custom-post-types" => [
    [
        "slug" => "album",
        "icon" => "dashicons-album",
        "taxonomies" => ['genre'],
        "options" => [
            "has_archive" => 'albums',
            "show_in_nav_menus" => true,
            "supports" => ['title', 'editor', 'thumbnail'],
            "labels" => [
                'name' => _x('Albums', 'Post Type General Name', 'text_domain'),
                'singular_name' => _x('Albums', 'Post Type Singular Name', 'text_domain'),
            ]
        ]
    ],
],
A more advanced custom post type.

If the options parameters look familiar that’s because it’s the same array that gets passed into register_post_type(...) when creating a custom post type the WP way!

Check out the custom-post-types docs for all the options as well as an even more advanced example.

Creating Multiple Post Types

Creating multiple custom post types is simple, just make sure they have unique slugs!

config.php
"custom-post-types" => [
    [
        "slug" => "album",
        "icon" => "dashicons-album",
        "taxonomies" => ['genre'],
        "options" => [...]
    ],
    [
        "slug" => "event",
        "icon" => "dashicons-megaphone",
        "options" => [...]
    ],
],
Declaring multiple custom post types

Another common thing that theme developers need to configure are menu locations, and luckily better-wordpress has got that covered too.

config.php
"menu-locations" => [
    "main-nav" => "Main Navigation",
    "footer-nav" => "Footer Navigation",
],
Declaring menu locations

This configuration will result in your “Menus” > “Manage Locations” page looking like this:

That was easy! See the menu-locations docs for more.

Options Pages

Advanced Custom Fields Pro is required to use this option.

Adding ACF option pages with better-wordpress is dead simple, all it takes is a string!

config.php
"options-pages" => [
    "Home Page",
    "Nav / Footer"
],
Declaring options pages

And just like that, we have two options pages in our sidebar:

Check out the options-pages docs for more.

All Configuration Options

KeyTypeDescription
excerpt-lengthintegerHow many words the WordPress excerpt should be
guest-classstringA class to append to the body_class list for unauthenticated users. Set to "null" to disable.
menu-locationsarrayRegister individual menu locations
options-pagesarrayA list of ACF options pages to add
custom-post-typesarrayDefines custom post types
handlebarsarrayConfigure handlebars helpers and template extension
enablearrayA list of WordPress features to enable
disablearrayA list of WordPress features to disable
tiny-mce-additionsarrayTinyMCE style configuration options