ACF Pro

In this article, we’ll cover some usage examples of how you can utilize ACF Pro within your X or Pro powered site. We’ll mainly be focusing on how to use ACF Pro and so may skip over some finer details.

  1. Getting Started
  2. What are the Field Groups
  3. Adding the Fields
  4. Displaying the Fields
  5. Cornerstone/Content Builder Integration
  6. Summary
  7. Further Reading

ACF Pro is one of the most powerful tools available for WordPress that both developers and non-developers love! Allowing you to create custom fields for any post type with a vast array of display options.

Getting Started

Go to Pro > Validation or X > Validation for X then look for ACF Pro. Click Install.

Image

Once installed, the Install button will change and say Activate. Click that button and it will activate the plugin. You will then see the status change to Installed and Activated.

On the WordPress dashboard navigation, you should now see the ACF Pro menu item like this:

Image

Go ahead and click on the Custom Fields menu item. This will take you to the main overview of ACF Pro.

What are the Field Groups

The first thing you'll see on the main ACF Pro overview is Field Groups these field groups are what ACF uses to group fields you create for use in your theme, child theme, template or plugin.

Image

As you can see we already have a field group that we've set up earlier, let's explore that to see what's going on and how we can utilize ACF to add an About Author meta box to our single post template.

Here's our basic field group layout:

Image

There's a lot going on here so let's split it down one by one. First, we have our rules, these are the basic rules of how our fields in this specific field group will display. For example in the field group we've created, we have it checked to show this field group if the post type is equal to post. Which means if, for example, you are on a portfolio item the field group won't be displayed.

We could expand on the field group display rule and add multiple other conditions, how you add these conditions is an important part of ACF Pro. There are two options both and as well as Add Rule Group.

Image

Option 1 AND allows you to add an additional rule in addition to the first rule that must be matched with the first one to display the field group. This is both useful and powerful with ACF. In this example say if we had a magazine style website. We may not want our Author field group to display in all categories, just our regular blog. So if we had a category called blog in ACF Pro we can then set Post Taxonomy is equal to Blog.

With that set our field group would then look like this:

Image

This now means that our Field Group will only show if the post type is a post and if the post taxonomy is Blog. If only one of these conditions is matched it means the Field Group won't display.

But what about if you wanted it to show if either of those conditions was matched?

Option 2: Add Rule Group allows you to add an additional rule group to the Field Group this is an OR conditional rather than an And conditional, meaning that if either condition A or condition B is met display the Field Group where both Field Group rules don't have to be met to display the field group. So if we set this value to Post Taxonomy is equal to Blog our Field Group would then look like this:

Image

This now means that our Field Group will display if either the post type is a post or if the post taxonomy is set to Blog. Which means if you had the blog taxonomy on another post type the Field Group would still display, whereas with option 1 it wouldn't have displayed as both conditions had to be matched.

Field Group displays are an extremely powerful part of ACF Pro and allow you to achieve near limitless display options.

The remaining options for the Field Group settings are:

  • Status
  • Style
  • Position
  • Label Placement
  • Instruction Placement
  • Order No.
  • Description
  • Hide on Screen
Image

What's important to note about all these options is that they are for the Field Group within the wp-admin Not how the Field Group will display in your theme.

For example, if you set the position to Normal (after content) your Fields within the Field Group will then display at the bottom of the page/post you've configured your Field Group to show on. Like this:

Image

However, if we change that to show at the side, our fields within the Field Display group will then show at the side like this:

Image

Once you're happy with your Field Group, go ahead and save it.

Adding the Fields

On your Field Group click on Add Field:

Image

You'll then see a range of Field options like this:

Image

As you can see there are a variety of options you can fill in for each field, the options will change depending on the field type you have selected, so make sure you have selected the Field Type before filling in the Field Options.

First of all give your field a name, for the purpose of this article as we've already mentioned, we're adding an About Author section to our blog posts.

The Field Label will be the name of the field as it appears on the edit page of the post type that your Field Group is set to display for.

The Field Name is what you will use in your theme, child theme, template or plugin to retrieve the field value so don't make it something too complex. In this case, we've gone for about_author, it can have underscores or dashes but no spaces are allowed.

Field Type, there is a huge range of options from a simple text area to Wysiwyg editors and much much more.

Field Instructions, these are the instructions shown to your other admins, editors, authors and anyone else who has access to the edit of the post type your field group is set to display for.

Required, whether the field itself should be required to be filled in or not, if the field is set to required and isn't filled in an error will be shown on trying to publish/update. As we don't want an empty author bio on our page we're going to set this to required.

Default Value Here you can an enter a default value to be used when creating a new post.

If you select the Wysiwyg option, you'll see a couple of other options.

With these options, you can select if with the Wysiwyg editor if both the Visual and Text options should be available or just one or the other along with if you want to show the media upload buttons for your custom field.

Once you're happy with everything click on Update/Save.

Displaying the Fields

Now you have a field added and a field group created, but what about actually outputting the field value within the theme? As we've created an about author field we want it to display above the Leave a Comment section of our single post template on our selected Stack Ethos.

Before we get started with adding our field first we need to make sure we have a child theme ready. If you don't already have a child theme on your website you can download one here.

Now with your FTP or SFTP program such as Coda, Filezilla, Cyberduck etc log in via FTP/SFTP and navigate to wp-content/themes/x-child and create the following folder at this exact path:

framework/views/ethos/wp-single.php

This is the template that is responsible for outputting the single post template of the Ethos stack. Copy the contents of that file from the parent theme at wp-content/themes/x/framework/views/ethos/wp-single.php. The code should look like this:

<?php

// =============================================================================
// VIEWS/ETHOS/WP-SINGLE.PHP
// -----------------------------------------------------------------------------
// Single post output for Ethos.
// =============================================================================

$fullwidth = get_post_meta( get_the_ID(), '_x_post_layout', true );

?>

<?php get_header(); ?>

  <div class="x-container max width main">
    <div class="offset cf">
      <div class="<?php x_main_content_class(); ?>" role="main">

        <?php while ( have_posts() ) : the_post(); ?>
          <?php x_get_view( 'ethos', 'content', get_post_format() ); ?>
          <?php x_get_view( 'global', '_comments-template' ); ?>
        <?php endwhile; ?>

      </div>

      <?php if ( $fullwidth != 'on' ) : ?>
        <?php get_sidebar(); ?>
      <?php endif; ?>

    </div>
  </div>

<?php get_footer(); ?>

Before this line:

<?php the_field('about_author'); ?>

Add the code to retrieve the value from ACF Pro for the custom field which is:

<?php

// =============================================================================
// VIEWS/ETHOS/WP-SINGLE.PHP
// -----------------------------------------------------------------------------
// Single post output for Ethos.
// =============================================================================

$fullwidth = get_post_meta( get_the_ID(), '_x_post_layout', true );

?>

<?php get_header(); ?>

  <div class="x-container max width main">
    <div class="offset cf">
      <div class="<?php x_main_content_class(); ?>" role="main">

        <?php while ( have_posts() ) : the_post(); ?>
          <?php x_get_view( 'ethos', 'content', get_post_format() ); ?>
            <?php the_field('about_author'); ?>

          <?php x_get_view( 'global', '_comments-template' ); ?>
        <?php endwhile; ?>

      </div>

      <?php if ( $fullwidth != 'on' ) : ?>
        <?php get_sidebar(); ?>
      <?php endif; ?>

    </div>
  </div>

<?php get_footer(); ?>

Note you don't need the paragraph tags there they just give us some extra styling with spacing rather than being all bunched together, this is also a basic implementation and you could add a range of additional styles and markup, the only limit is your imagination.

This leaves the total file looking like this (in our child theme).

Now we've added the code to display our field lets go and add a value to display, open up any post and fill in the author details box with the content you want. Save the post and visit it on the front-end. You should see the new custom field you created displayed like this:

Image

Congrats! You've successfully created a custom field group, added a custom field and got the custom field displaying by using a child theme and the get_field function of ACF Pro. You can find out more about the get_field function here.

Cornerstone/Content Builder Integration

We've included a basic ACF Pro integration with Cornerstone which allows you to use a shortcode within your pages and posts created with Cornerstone to automatically pull through the value of your ACF Pro custom field without having to modify template files.

You'd use:

{{acf:field_name}}

Within your Cornerstone content where field_name is the name of your field as shown in the ACF Pro field edit screen. Please note, this is a basic integration and will only support text-based fields. For example, it won't output a gallery. Also, use the WYSIWYG type field with caution - WordPress's visual editor automatically adds tags, which can break element markup causing display issues.

Summary

Well done! Now you know how to easily add custom fields to your WordPress site using ACF Pro that comes with your X and Pro install.

Further Reading

To learn more about ACF Pro check out the official documentation here.

See something inaccurate? Let us know