ACF Pro

This article was last updated on the December 21, 2016.

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

Note: This article covers only a small portion of what you can achieve with ACF Pro, make sure you take a look at the official documentation which is linked to in the Documentation section below to explore the full possibilities of this powerful tool.

Getting Started

Make sure you already have ACF Pro installed and then in your wp-admin, you should see the ACF Pro menu item like this:

ACF Pro Menu item

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

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.

ACF Pro Field Groups

As you can see we already have a field group that we’ve setup earlier, let’s explore that to see what’s going on and how we can utliize ACF to add an About Author metabox to our single post template.

Here’s our basic field group layout:

ACF Field Group setup

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 sepcific 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.

And or Add

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 on 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:

Only show if this is matched

This now means that our Field Group will only show if the post type is 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 a 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:

Either condition can be matched for display

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 if 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

What’s important to note about all these option 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:

Field displaying after content

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:

Fields displaying at the side

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

Adding Fields

On your Field Group click on Add Field:

Add Field

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

Field Options

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 are a huge range of options from a simple text area to Wysiwyg editors and much much more.

Field Types

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 your Field

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, Filezila, 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 x_get_view( 'global', '_comments-template' ); ?>

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

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

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 implamention 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).

	
<?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() ); ?>
            <p><?php the_field('about_author'); ?></p>
          <?php x_get_view( 'global', '_comments-template' ); ?>
        <?php endwhile; ?>
        
      </div>

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

    </div>
  </div>

<?php get_footer(); ?>

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:

Custom Field Displaying

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 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 <p> tags, which can break element markup causing display issues.

Documentation

As we mentioned further up, we’re only going to cover how to use ACF Pro and not every option it provides, to learn more about ACF Pro check out the official documentation here.

Bundled Version

Users will frequently inquire about the version of ACF Pro being utilized within X. Because of the way that we are utilizing the plugin with in X, it should be noted that the version of ACF Pro included with the theme is made intentionally for numerous reasons. The following is just a few of the reasons why we do not always utilize the latest version of the ACF Pro plugin:

  • Stability – Newer versions of software do not always equal greater stability. Oftentimes there are undiscovered bugs that are introduced with certain versions and are unknown until the product has been released to the public for some time. The version of the plugin that we bundle with the theme is more or less guaranteed to work without any issues as we take a great deal of time to test all functionality thoroughly before releasing it along with the theme.
  • Release Cycles – While we try to include the latest version of ACF Pro with each release, occasionally the release cycle of the plugin will prevent this from being possible. Essentially, since we have no idea when ACF Pro will be releasing new versions of the plugin, we cannot plan our releases around this. Because of this, if we have already begun the process of finalizing our release and submitting it to ThemeForest for review while ACF Pro is putting out a new version of the plugin, that version of the plugin will not be able to make it into the theme until the next release at the earliest.
  • Not Always Necessary – Some of ACF Pro’s releases have only included simple “bug fixes” without any huge additions or modifications to the rest of the plugin. Because of situations like this, it is up to our discretion whether or not a new release will make it into the theme or not based on the nature of the update.

Because of these reasons (among others), there is no need to register your license for ACF Pro if you happen to have one. In fact, doing so is discouraged in order to prevent any potential conflicts when updating, as previously mentioned. If you happen see a notification in your WordPress admin panel asking you to register ACF Pro upon activation, simply dismiss this notice.

Conclusion

Hopefully the information provided above has helped you to gain a better understanding of what to expect from utilizing ACF Pro within X. Ultimately, there are a few things to take away from this article:

  • ACF Pro is a extremely powerful and flexible plugin that will assist you with creating the perfect website.
  • The version of ACF Pro included with the theme is an unmodified version of the plugin.
  • We do our best to ensure that the version of ACF Pro included with X is as up-to-date as possible; however, this might not always be the case based on the reasons listed in the “Bundled Version” section above, which includes stability, release cycles, and the fact that not all updates are necessary.
  • Any questions concerning the usage of a ACF Pro feature should be directed to the online documentation referenced in the “Documentation” section above.