Plugin: Get Custom Field Values

This plugin has been updated! Comments to this post are now closed. For the latest download, documentation, and link for posting new comments related to this plugin, visit the plugin’s new homepage at:
coffee2code.com/wp-plugins/get-custom-field-values
Name:
Get Custom Field Values
Author:
Scott Reilly
Version:
2.1
Last updated:
26 March 2005
Description:

Easily retrieve and control the display of any custom field values/meta data for posts, inside or outside “the loop”. The power of custom fields gives this plugin the potential to be dozens of plugins all rolled into one.

Notes:

This is a simple plugin that allows you to harness the power of custom fields/meta data. You can define $before and/or $after text/HTML to bookend your results. If no matching custom field by the name defined in $field was found, nothing gets displayed (including no $before and $after) (unless $none is defined, in which case the $none text gets used as if it was the match). If multiple same-named custom fields for a post are defined,only the first will be retrieved unless $between is defined, in which case all are returned, with the $between text/HTML joining them). If $before_last is defined along with $between, then the text/HTML in $before_last is used prior to the last item in the list (i.e. if you want to add an “and” before the last item). Head down to the Tip & Examples section to see how this plugin can be cast in dozens of different ways.

Installation:
  1. Download the file get-custom.zip and unzip it into your wp-content/plugins/ directory.
    -OR-
    Copy and paste the the code ( get-custom.phps ) into a file called get-custom.php, and put that file into your wp-content/plugins/ directory.
  2. Optional: Add filters for ‘the_meta’ to filter custom field data (see the end of the file for commented out samples you may wish to include) *NEW*: Add per-meta filters by hooking ‘the_meta_$field’
  3. Activate the plugin from your WordPress admin ‘Plugins’ page.
  4. Give a post a custom field with a value.
  5. Use the function c2c_get_custom somewhere inside “the loop” and/or use the function c2c_get_recent_custom outside “the loop”; use ‘echo’ to display the contents of the custom field; or use as an argument to another function
Functions:

function c2c_get_custom ($field, $before='', $after='', $none='', $between='', $before_last='')

  • $field : This is the name of the custom field you wish to display
  • $before : The text/HTML to display before all field value(s)
  • $after : The text/HTML to display after all field value(s)
  • $none : The text/HTML to display in place of the field value should no field value exists; if defined as ” and no field value exists, then nothing (including no $before and $after) gets displayed
  • $between : The text/HTML to display between multiple occurrences of the custom field; if defined as ”, then only the first instance will be used
  • $before_last : The text to display between the next-to-last and last items listed when multiple occurrences of the custom field; $between MUST be set to something other than ” for this to take effect

function c2c_get_recent_custom ($field, $before='', $after='', $none='', $between='', $before_last=', ', $limit=1, $unique=false, $order='DESC', $include_static=true, $show_pass_post=false)

  • $field : This is the name of the custom field you wish to display
  • $before : The text/HTML to display before all field value(s)
  • $after : The text/HTML to display after all field value(s)
  • $none : The text/HTML to display in place of the field value should no field value exists; if defined as ” and no field value exists, then nothing (including no $before and $after) gets displayed
  • $between : The text/HTML to display between multiple occurrences of the custom field; if defined as ”, then only the first instance will be used
  • $before_last : The text to display between the next-to-last and last items listed when multiple occurrences of the custom field; $between MUST be set to something other than ” for this to take effect
  • $limit : The number of recent custom field values you want returned; default is 1
  • $unique : Boolean value (either ‘true’ or ‘false’) to indicate if only the latest instance of $field should be considered, and subsequent occurances of $field would be skipped in the search; default is ‘false’
  • $order : The order the results should be returned, either ascending/increasing (‘ASC’) or descending/decreasing (‘DESC’); default is ‘DESC’
  • $include_static : Boolean (‘true’ or ‘false’) to indicate if static posts (i.e. “pages) should be included when retrieving recent custom values; default is ‘true’
  • $show_pass_post : Boolean value (either ‘true’ or ‘false’) to indicate if passworded posts should be considered in the search; default is ‘false’
Tips & Examples:

Do you simply want to retrieve the value of a custom field/meta data?

<?php echo c2c_get_custom('mood'); ?>


Want a moods plugin?

<?php echo c2c_get_custom('mood', '(Current mood : ', ')'); ?>

Example results:
[if ‘mood’ is set to ‘happy!’] (Current mood: happy!)
(add filters if you wish to use smilies, etc)


Want a currently reading/currently listening to plugin?

<?php echo c2c_get_custom('reading', 'Currently reading :'); ?>

[if value for ‘reading’ is ‘Cujo’] Currently reading: Cujo

<?php echo c2c_get_custom('reading', 'Currently reading: <i>', '</i>', '', '</i>, <i>'); ?>

[if three ‘reading’ fields were defined, with values ‘Carrie’, ‘Cujo’, and ‘The Shining’]
Currently reading: Carrie, Cujo, The Shining

<?php echo c2c_get_custom('listening', 'Now playing ', ' on my stereo.', 'nothing'); ?>

[if value for ‘listening’ is ‘The Beatles’] Now playing The Beatles on my stereo.
[if no value defined for ‘listening’] Now playing nothing on my stereo.


Want a Post Icon plugin (image to display for the post, not derived from category)?

<?php echo c2c_get_custom('post_icon', '<img alt="post icon" class="posticon" src="/wp-images/posticons/', '.gif" />', 'blank'); ?>

[if value for ‘post_icon’ is ‘wordpress’]
<img alt=”post icon” class=”posticon” src=”/wp-images/posticons/wordpress.gif” />


Want to do per-post customized ‘more’ text? (to override the default “(more…)”) (This example will show the default “(more…)”, which you can of course change, if you don’t define the custom field ‘more’ for a post)

In index.php, look for this function: <?php the_content(); ?>

Replace it with this:

<?php the_content(c2c_get_custom('more', '<span class="more">', '</span>', '(more...)')); ?>

Related Links:
  • WordPress Support Forums announcement of Get Custom Field Values
Release Log:
  • 26 Mar 2005 : v2.1 released —
    • Removed the $filter argument from c2c_get_custom() and c2c_get_recent_custom()
    • Replaced $filter argument with more robust filtering approach: filter every custom field via the action ‘the_meta’, filter specific custom fields via ‘the_meta_$field’
    • Add argument $include_static (defaulted to true) to c2c_get_recent_custom(); static posts (i.e. “pages”) can be optionally excluded from consideration
    • Verified to work for WP 1.5 (and should still work for WP 1.2)
  • 08 Sep 2004 : v2.01 and v.202 release — minor bugfixes
  • 07 Sep 2004 : v2.0 released :
    • Added the new function c2c_get_recent_custom() that allows retrieving custom/meta data from outside “the loop”
    • Better filtering (on meta field itself instead of final output string)
    • Per-call filtering of meta fields
    • Prepended all functions with “c2c_” to avoid potential function name collision with other plugins or future core functions… NOTE: If you are upgrading from an earlier version of the plugin, you’ll need to change your calls from get_custom() to c2c_get_custom()
    • Changes to make the plugin WordPress v1.3 ready (as-yet unverified)
    • Switched to MIT license
  • 22 Jul 2004 : v1.0 released — added argument of $before_last (which, went $between is also defined, will be used to join the next-to-last and last items in a list); added invocation of an action called ‘the_meta’ so that you can do add_filter(‘the_meta’, ‘some_function’) and get custom field values filtered as they are retrieved; to faciliate use of this plugin as the argument to another function, this plugin no longer echoes the value(s) it retrieves (user must prepend ‘echo’ to the call to get_cust())
  • 30 Jun 2004: v0.91 bugfix release
  • 30 Jun 2004: v0.9 released to the public
Copyright & Disclaimer:

Copyright (c) 2004-2005 by Scott Reilly (aka coffee2code)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgements:
N/A

252 thoughts on “Plugin: Get Custom Field Values

Comments are closed.