Advanced Custom Fields (ACF) - 3ev/wordpress-core GitHub Wiki

Wordpress Core comes built in with integration with the excellent Advanced Custom Fields plugin. This allows you to easily fetch custom field data from any of the built in model classes and use it in your templates.

###The field() method

The Tev\Post\Model\AbstractPost model includes a method called field(). This method accepts a single parameter, which is the name or key of the custom field.

The method returns an instance of Tev\Field\Model\AbstractField. The type of field object returned depends on the custom field's configuration. For a full list of the possible field types, see here.

###Field models

Every field model has a getValue() method (also aliased as val() for convenience). This will typically return a string representation of the field data, which can be echo'd directly in your templates, although this can vary depending on the field type so please ensure you read the documentation.

Some field models provide extra functionality. For example, the DateField contains methods to format the date, as well as fetching the date as a Carbon instance. The ImageField provides methods for accessing the URLs to the underlying image at different sizes.

####Echo'ing field objects directly

For convenience in your templates, each field provides a __toString() method. This will typically return the result of getValue(), meaning that you can echo your field directly.

So, the following three expressions are equivalent:

<?php while (have_posts()): $p = tev_post_factory(); ?>

    <p>
        <?php // Call getValue() to get the field's content ?>
        <?php echo $p->field('mycustombasicfield')->getValue(); ?>
    </p>

    <p>
        <?php // val() is a shorter alias of getValue() ?>
        <?php echo $p->field('mycustombasicfield')->val(); ?>
    </p>

    <p>
        <?php // Echo'ing the field directly makes use of __toString() to get the field's content ?>
        <?php echo $p->field('mycustombasicfield'); ?>
    </p>

<?php endwhile; ?>

Again, some fields have different __toString() representations, so please ensure you refer to the API docs.

If field data for an entity could not be loaded from the database, a Tev\Field\Model\NullField instance will be returned. Calling getValue() on this field will return null. This can be useful for checking the existence of a field before working with its data. For example:

<?php while (have_posts()): $p = tev_post_factory(); ?>

    <?php if ($p->field('mycustombasicfield')->val() !== null): ?>
        <p>
            <?php echo $p->field('mycustombasicfield')->getValue(); ?>
        </p>
    <?php endif; ?>

<?php endwhile; ?>

###Repeaters and Flexible Content

Wordpress Core provides an intuitive and fluid API for working with Repeater and Flexible Content fields. You can simply iterate over the field data using any looping construct.

For example, let's say our post has a Repeater field (myrepeater) which contains a title, content and a Flexible Content field (myflexcontent) that has two layouts; layoutone and layouttwo. Our template might look like this:

<?php while (have_posts()): $p = tev_post_factory(); ?>

    <?php // Iterate over the repeater field rows ?>

    <?php foreach ($p->field('myrepeater') as $repeaterFields): // $repeaterFields is an instance of Tev\Field\Util\FieldGroup ?>
        
        <h2><?php echo $repeaterFields->field('title'); ?></h2>
        
        <p><?php echo $repeaterFields->field('content'); ?></p>
        
        <?php // Iterate over the flexible content field rows ?>

        <?php foreach ($repeaterFields->field('myflexcontent') as $flexContent): // $flexContent is an instance of Tev\Field\Util\LayoutFieldGroup ?>

            <?php switch ($flexContent->layout()): ?>
                <?php case 'layoutone': ?>
                    <?php echo $flexContent->field('layoutonetitle'); ?>
                    <?php break; ?>

                <?php case 'layouttwo': ?>
                    <?php echo $flexContent->field('layouttwotitle'); ?>
                    <?php break; ?>
            <?php endswitch; ?>

        <?php endforeach; ?>

    <?php endforeach; ?>

<?php endwhile; ?>

As you can see, this quite a complex data structure but the Wordpress Core API makes it easy to work with in your templates.