Building Modular WordPress Sites with ACF Builder

Here at New Media Campaigns, we often use WordPress as the Content Management System powering the sites we work on.  We try to give our clients as much intuitive control as possible through WordPress. Developers have created nearly an infinite number of plugins promising this flexibility and control -- the catch is finding plugins that actually deliver that promise and work within our infrastructure.  We typically go through an organizational evolution where someone on our team discovers a plugin, experiments with it, introduces it to our team, and if it passes muster, figure out how to responsibly roll it into our default setup (or at least shortlists on our list favorite WordPress plugins).

One of our absolute favorite plugins is Advanced Custom Fields. Using ACF, we create powerful, flexible custom blocks that can be mixed and matched to produce a large number of page layouts on the fly. This setup lets our team take a modular approach to building sites and gives our clients the powerful ability to create different layouts depending on their page-by-page content needs.

However, while it checks the boxes of helping both us and our clients, we ran into an issue with the ACF plugin interface storing all custom field configurations in that single site's database, which places them outside of any version control mechanism. As a standard practice, we build all of our WordPress sites on virtual machines stored in GitLab repositories. These repositories not only provide essential version control but also allow developers to quickly and easily share and collaborate on projects.  So, while providing flexibility for an editor, this plugin runs afoul of a couple of our core development tenets at NMC.

An ideal scenario would allow us to leverage the power of Advanced Custom Fields while maintaining our desired level of version control. ACF has always had the ability to have custom field configurations built out in PHP, but the code is extremely dense and nested, making it slower and harder to update and easily prone to error.

Looking around for a possible solution to let us bake ACF into our core setup, we discovered that the clever folks at Stout Logic came up with a fantastic solution: ACF Builder. Not only could we gain version control over the ACF setup, ACF Builder also simplifies the code it takes to pull that off. Configurations can be extended, allowing for minor variations between templates without writing extra code or duplicating effort.  Configurations can also be re-used across sites quickly, which helps in keeping your admin interface consistent and reliable. The extension properties alone are worth the price of admission  - who doesn't want DRY-er code? And the price of admission is merely a composer install or an autoload include. 

Discussing the power of ACF Builder in the abstract doesn't really illustrate the ease and facility of building configurations, so I've set up an example we write frequently.

Just about every site we build has a customizable page banner with a large hero image. Many sites include an ambient video banner on the homepage, but not on interior pages. To accomplish this using just the ACFPro plugin, you would either need two separate custom field sets identical in every way with the exception of an ambient video upload slot or you would need to include the ambient video uploader on pages where it wouldn't be used.  This setup would definitely lead to user decision errors (trust us) and clutter the editing interface.

Enter our hero: ACF Builder.  Using ACF Builder, a basic banner can be constructed and placed on every page template and then extended to include the ambient video upload slot on only the homepage. Check out the example below.

Basic page banner, present on every page except the homepage: 

$banner = new StoutLogic\AcfBuilder\FieldsBuilder('banner');
$banner
     ->addText('banner_title',['instructions' => 'Leave blank to use page title']);
     ->addText('banner_subtitle',['instructions' => 'Optional, displays over title']);
     ->addImage('full-width_image',['instructions' => '1440 x 400 or larger with same aspect ratio']);
     ->setLocation('post_type', '==', 'page')->and('page_template', '!=', 'template-home.php');

Banner extended to include ambient video on the homepage only:  

$homebanner = new StoutLogic\AcfBuilder\FieldsBuilder('homebanner');
$homebanner
     ->addFields($banner);
     ->addFile('ambient_video_file',['instructions' => 'mp4 format']);
     ->setLocation('page_template', '==', 'template-home.php');  

The code is logical, compact, and easy to read.  From an end-user perspective, the content entry points will look exactly the same using the Builder as using the plugin alone: each post type or page will have a set of custom fields on a that are unique to that item.  

Using ACF Builder, we're able to more speedily, safely, and scalably give clients powerful control of their sites.  We've now rolled it into our default setup, and we encourage you to check it out to take your next WordPress site to the next level!