New template "tag": get_custom_field()

[filosofo]

It would be helpful to have a way to retrieve a custom field value that is somewhat agnostic of current context.

Current way to do this

In the header (i.e., before the Loop), one has to access the currently-queried object to get a custom value, with something like this:

$value = get_post_meta($GLOBALS['wp_query']->get_queried_object_id(), 'field', true);

In the Loop:
$value = get_post_meta(get_the_ID(), 'field', true);

And, lots of tutorials out there tell people to do things like the following, with varying degrees of success (depending on variable scope):

$value = get_post_meta($id, 'field', true);

or

$value = get_post_meta($post->ID, 'field', true);

My proposed function (or "template tag")

mixed get_custom_field ( string $fieldname [, int $post_id ] )

$value = get_custom_field('field');

It picks the current object like so:

Passed post object ID?
    /       \
   yes      no 
    |        |
   use it    |
             |
          within Loop?
            /       \
          yes        no
           |          |
        use current   |
         Loop ID      |
                      |
                    currently queried
                    object is singular?
                    /           \
                   yes           no
                    |             | 
                use its ID      ID = 0

This makes a lot of sense. A friend was asking how to do this earlier, and I went through the same thought process as above when explaining it. +1

Patch is still a thing of beauty.

Not convinced about the naming of this.

It really irks me that we call post meta by two different names and promoting that more here is not good IMHO.

Can we not just extend get_post_meta() to have this behaviour if passed a 0 id?

I don't really care about the name, so please suggest one. However, they're called "Custom Fields" on the post edit page, so it seems like the reasonable name to me. The name of the db table the actual data is stored in is irrelevant to the person using the API, right?

I think changing get_post_meta to accept 0 as an argument like that is going to have serious backwards-compatibility issues, because get_post_meta should fail when given an invalid ID. And then they still have to add "true" to make sure they get a string.

My general idea is to make the lives of template designers easier.

I don't care what we call it, but it's a very nifty function.

get_post_meta_field()?

Replying to nacin:

I don't care what we call it, but it's a very nifty function.

Got to agree with you there! :)

This is possibly a nifty idea.

But it is past the time for introducing new apis in 3.1

We should consider this for 3.2 though

How about we make a WP_Post class, with a custom_field() method:

echo $post->custom_field( 'key' );

Of course, it could be extended with other methods too.

Replying to scribu:

How about we make a WP_Post class, with a custom_field() method:

echo $post->custom_field( 'key' );

Of course, it could be extended with other methods too.

+1