Get Custom Field Values

Screenshots

This plugin provides a powerful widget, shortcode (with shortcode builder tool), and template tags for easily retrieving and displaying custom field values for posts or pages. The power of custom fields gives this plugin the potential to be dozens of plugins all rolled into one. This plugin allows you to harness the power of custom fields/meta data. Use the “Get Custom Field” widget, the [custom_field] shortcode (which has a post editor sidebar widget to help you build the shortcode), or one of six template tags to retrieve and display custom fields. Find a custom field for the current post, a specified post, a recent post, or randomly. And for the custom field values found by the plugin, you may optionally specify text or HTML to appear before and after the results. If nothing is found, then nothing is display (unless you define text to appear when no results are found). If multiple results are found, only the first will be displayed unless you specify a string to be used to join the results together (such as “,”), in which case all will be returned. Visit the Examples section to see how this plugin can be cast in dozens of different ways. There are six template tags provided by this plugin. Here they are, with an explanation of when they are appropriate for use: c2c_get_custom() : Use this inside “the loop” to retrieve a custom field value for a post c2c_get_current_custom() : This is only available on the permalink post template (single.php) and page template (page.php). Can be used inside or outside “the loop”. Useful for using custom field to define text you want to include on a post or page’s header, footer, or sidebar. c2c_get_post_custom() : Useful when you know the ID of the post whose custom field value you want. c2c_get_random_custom() : Retrieve the value of a random instance of the specified custom field key, as long as the field is associated with a published posted, non-passworded post (you can modify a setting in the plugin file to search passworded posts as well). c2c_get_random_post_custom() : Retrieves the value of random custom field(s) from a post when you know the ID of the post you’re interested in. c2c_get_recent_custom() : Retrieves the most recent (according to the associated post’s publish date) value of the specified custom field. You can filter the custom field values that the plugin would display. Add filters for ‘the_meta‘ to filter custom field data (see the end of the code file for commented out samples you may wish to include). You can also add per-meta filters by hooking ‘the_meta_$sanitized_field‘. $sanitized_field is a clean version of the value of $field where everything but alphanumeric and underscore characters have been removed. So to filter the value of the “Related Posts” custom field, you would need to add a filter for ‘the_meta_RelatedPosts‘. Links: Plugin Homepage | Plugin Directory Page | Author Homepage Template Tags The plugin provides six optional template tags for use in your theme templates. Functions <?php function c2c_get_custom( $field, $before='', $after='', $none='', $between='', $before_last='' ) ?> Template tag for use inside “the loop” and applies to the currently listed post. <?php function c2c_get_current_custom( $field, $before='', $after='', $none='', $between='', $before_last='' ) ?> Template tag for use on permalink (aka single) page templates for posts and pages. <?php function c2c_get_post_custom( $post_id, $field, $before='', $after='', $none='', $between='', $before_last='' ) ?> Template tag for use when you know the ID of the post you’re interested in. <?php function c2c_get_random_custom( $field, $before='', $after='', $none='', $limit=1, $between='', $before_last='' ) ?> Template tag for use to retrieve a random custom field value. <?php function c2c_get_random_post_custom( $post_id, $field, $limit=1, $before='', $after='', $none='', $between='', $before_last='' ) ?> Template tag for use to retrieve random custom field value(s) from a post when you know the ID of the post you’re interested in. <?php function c2c_get_recent_custom( $field, $before='', $after='', $none='', $between=', ', $before_last='', $limit=1, $unique=false, $order='DESC', $include_pages=true, $show_pass_post=false ) ?> Template tag for use outside “the loop” and applies for custom fields regardless of post. Arguments $post_id Required argument (only used in c2c_get_post_custom()). The ID of the post from which the custom field should be obtained. $field Required argument. The custom field key of interest. $before Optional argument. The text to display before all the custom field value(s), if any are present (defaults to ”). $after Optional argument. The text to display after all the custom field value(s), if any are present (defaults to ”) $none Optional argument. The text to display in place of the field value should no field values exist; if defined as ” and no field value exists, then nothing (including no $before and $after) gets displayed. $between Optional argument. The text to display between multiple occurrences of the custom field; if defined as ”, then only the first instance will be used. $before_last Optional argument. 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. Arguments that only apply to c2c_get_recent_custom(): $limit Optional argument. The limit to the number of custom fields to retrieve. (also used by c2c_get_random_custom and c2c_get_random_post_custom()) $unique Optional argument. Boolean (‘true’ or ‘false’) to indicate if each custom field value in the results should be unique. $order Optional argument. Indicates if the results should be sorted in chronological order (‘ASC’) (the earliest custom field value listed first), or reverse chronological order (‘DESC’) (the most recent custom field value listed first). $include_pages Optional argument. Boolean (‘true’ or ‘false’) to indicate if pages should be included when retrieving recent custom values; default is ‘true’. $show_pass_post Optional argument. Boolean (‘true’ or ‘false’) to indicate if password protected posts should be included when retrieving recent custom values; default is ‘false’. Examples <?php echo c2c_get_custom('mymood'); ?> // with this simple invocation, you can echo the value of any metadata field <?php echo c2c_get_custom('mymood', 'Today's moods: ', '', ', '); ?> <?php echo c2c_get_recent_custom('mymood', 'Most recent mood: '); ?> <?php echo c2c_get_custom('mymood', '(Current mood: ', ')', ''); ?> <?php echo c2c_get_custom('mylisten', 'Listening to : ', '', 'No one at the moment.'); ?> <?php echo c2c_get_custom('myread', 'I\'ve been reading ', ', if you must know.', 'nothing'); ?> <?php echo c2c_get_custom('todays_link', '<a class="tlink" href="', '" >Today\'s Link</a>'); ?> <?php echo c2c_get_current_custom('meta_description', '<meta name="description" content="', '" />' ); ?> <?php echo c2c_get_post_custom($post->ID, 'Price: ', ' (non-refundable)'); ?> <?php echo c2c_get_random_custom('featured_image', '<img src="/wp-content/images/', '" />'); ?> <?php echo c2c_get_random_post_custom($post->ID, 'quote', 1, 'Quote: <em>', '</em>'); ?> <?php echo c2c_get_custom('related_offsite_links', 'Here\'s a list of offsite links related to this post:<ol><li><a href="', '">Related</a></li></ol>', '', '">Related</a></li><li><a href="'); ?> <?php echo c2c_get_custom('more_pictures', 'Pictures I\'ve taken today:<br /><div class="more_pictures"><img alt="[photo]" src="', '" /></div>', '', '" /> : <img alt="[photo]" src="'); ?> Custom ‘more…’ link text, by replacing <?php the_content(); ?> in index.php with this: <?php the_content(c2c_get_custom('more', '<span class="morelink">', '</span>', '(more...)')); ?> Shortcode This plugin provides one shortcode that can be used within the body of a post or page. The shortcode is accompanied by a shortcode builder (see Screenshots) that presents a form for easily creating a shortcode. However, here’s the documentation for the shortcode and its supported attributes. The name of the shortcode can be changed via the filter ‘c2c_get_custom_field_values_shortcode’ (though making this customization is only recommended for before your first use of the shortcode, since changing to a new name will cause the shortcodes previously defined using the older name to no longer work). custom_field The only shortcode provided by this plugin is named custom_field. It is a self-closing tag, meaning that it is not meant to encapsulate text. Except for ‘field’, all attributes are optional, though you’ll likely need to provide a couple to achieve your desired result. Attributes: field : (string) The name of the custom field key whose value you wish to have displayed. id : (string) The text to use as the ‘id’ attribute for a ‘span’ tag that wraps the output class : (string) The text to use as the ‘class’ attribute for a ‘span’ tag that wraps the output this_post : (boolean) Get the custom field value for the post containing this shortcode? Takes precedence over post_id attribute. Specify 1 (for true) or 0 for false. Default is 0. post_id : (integer) ID of post whose custom field’s value you want to display. Leave blank to search for the custom field in any post. Use 0 to indicate it should only work on the permalink page for a page/post. random : (boolean) Pick random value? Specify 1 (for true) or 0 for false. Default is 0. limit : (integer) The number of custom field items to list. Only applies if Post ID is empty and “Pick random value?” is unchecked. Use 0 to indicate no limit. Default is 0. before : (string) Text to display before the custom field. after : (string) Text to display after the custom field. none : (string) Text to display if no matching custom field is found (or it has no value). Leave this blank if you don’t want anything to display when no match is found. between : (string) Text to display between custom field items if more than one are being shown. Default is ‘, ‘. before_last : (string) Text to display between the second to last and last custom field items if more than one are being shown. Examples: Get list of sizes for the current post [custom_field field=”size” limit=”0″ between=”, ” this_post=”1″ /] Get random random quote [custom_field field=”quote” limit=”1″ random=”1″ /] Get 3 most recent books read [custom_field field=”book” limit=”3″ before=”Recently read books: ” /]