v1.4

tip

Download this extension

Regular meta

The Custom Fields extension supports meta of three object types:

• Posts
• Users
• Comments

Here are the examples with equivalents in get_****_meta()

{postmeta {post_ID} metakey}
// equivalent of:
// get_post_meta( $post_id, $metakey, true );

{usermeta {user_ID} metakey}
// equivalent of:
// get_user_meta( $user_id, $metakey, true );

{commentmeta {comment_ID} metakey}
// equivalent of:
// get_comment_meta( $comment_id, $metakey, true );

Note that {post_ID} or {user_ID} or {comment_ID} part is the object ID which can be static (like just 365783) or can be a merge tag. If you are using merge tags for this part, like in the examples, please make sure you can see this merge tag in the sidebar. So if you choose the Book updated trigger, the {post_ID} will become {book_ID}.

Advanced Custom Fields meta

Any ACF field value can be retrieved with the regular meta merge tags, but sometimes you'd want to let ACF format the data for you.

Very similar to regular meta you can use it like this:

{acf {post_ID} my_field_slug}
{acf comment_{comment_ID} fieldname}
{acf user_{user_ID} fieldname}
{acf term_{term_ID} fieldname}

Which is an equivalent of:

get_field( $fieldname, $item_id );

note

You can access the first-level array key as well

Giving an example, you can have a field of type User and return format of User array. Your meta will look like this:

Array
(
    [ID] => 1
    [user_firstname] => Panda
    [user_lastname] => Bear
    [nickname] => admin
    [user_nicename] => admin
    [display_name] => Panda Bear
    [user_email] => [email protected]
    [user_url] => 
    [user_registered] => 2019-03-14 10:46:17
    [user_description] => 
    [user_avatar] => <img alt='' src='http://2.gravatar.com/avatar/21c9a0124feee215cb7c5759f7e6670b?s=96&#038;d=mm&#038;r=g' srcset='http://2.gravatar.com/avatar/21c9a0124feee215cb7c5759f7e6670b?s=192&#038;d=mm&#038;r=g 2x' class='avatar avatar-96 photo' height='96' width='96' />
)

To access the user_email key, you just need to do it like this:

{acf {post_ID} user_field:user_email}

Access array keys

Getting the meta often means you need to work with arrays. Deeper levels can be easily accessed with : character.

Let's consider an example, where you have this array in your meta:

Array
(
    [date] => 2019-03-14 10:46:17
    [accepted] => 1
    [email] => '[email protected]'
)

To access the email key you just need to pass the array key after the colon:

{postmeta {post_ID} metakey:email}

This will work with any type of meta.

Multidimensional arrays

But what in case you have a multidimensional array like this?

Array
(
    [user] => Array
    (
        [user_firstname] => Panda
        [user_lastname] => Bear
        [user_email] => [email protected]
    )
)

Easy! Just pass the nested keys after another colon:

{... user_field:user:user_email}

Same story with numeric arrays:

Array
(
    [0] => Array
    (
        [user_firstname] => Panda
        [user_lastname] => Bear
        [user_email] => [email protected]
    )
)

{... user_field:0:user_email}

Pipelines

Sometimes the value in meta is not exactly in a form you'd like. The most common scenario is having a post or user ID saved in the meta while you want to display a post_title or display_name.

Each pipe is processing the value and manipulate its representation. You can think about it like this:

Initial value -> replace -> reshape -> replace -> format

So the initial value of User ID can be replaced with a whole User object and this object can be formatted as JSON.

note

Pipes can be mixed together and each pipe can be used with the array accessors. They work with ACF and regular meta Merge Tags. See the example.

All supported pipelines:

Objects	Manipulators	Formatters
post	first	bool
postmeta	last	join
term	pluck	json
termmeta
user
usermeta

Examples

Post has a related_post field (stored post ID) where another related post can be selected. The related post has a field where owner can be selected and this returns the user ID. To get this user email:

{postmeta {post_ID} related_post|postmeta,owner,true|user:user_email}

Explanation:

• {postmeta {post_ID} related_post - gets the initial value of the related post, post ID is retrieved
• |postmeta,owner,true - related post ID is used to get the meta key owner and true means the single value should be returned. We get the User ID.
• |user:user_email - user ID is used to get the whole user representation. We access the user_email array key to get the email

Limitations

The plugin cannot handle iterators. Ie. if you want to map an array of users. In other words, it's not possible to work on the collections. The subsequent pipes are meant to reduce the data to a single value.