Categories

Get Custom Field Values

Author: Scott Reilly
Version: 4.1
First released: 2004-12-21
Last update: 2023-10-10
Compatibility: WP 3.6 – 6.3.3
Download: [ zip ]
Description:

Use widgets, shortcodes, and/or template tags to easily retrieve and display custom field values for posts or pages.

Extended Description

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 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 | GitHub | Author Homepage

Developer Documentation

Developer documentation can be found in DEVELOPER-DOCS.md. That documentation covers the numerous template tags, hooks, and shortcode provided by the plugin.

As an overview, these are the template tags provided the plugin:

  • c2c_get_custom() : Template tag for use inside “the loop” and applies to the currently listed post.
  • c2c_get_current_custom() : Template tag for use on permalink (aka single) page templates for posts and pages.
  • c2c_get_post_custom() : Template tag for use when you know the ID of the post you’re interested in.
  • c2c_get_random_custom() : Template tag for use to retrieve a random custom field value.
  • c2c_get_random_post_custom() : 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.
  • c2c_get_recent_custom() : Template tag for use outside “the loop” and applies for custom fields regardless of post.

These are the hooks provided by the plugin:

  • c2c_get_custom_field_values_shortcode : Filter to customize the name of the plugin’s shortcode.
  • c2c_get_custom_field_values_post_types : Filter to customize the post types that should support the shortcode builder metabox.
  • get_custom_field_values/can_author_use_shortcodes : Filter to customize if post author can make use of the ‘custom_field’ shortcode.
  • get_custom_field_values/show_metabox : Filter to customize if the shortcode builder metabox is shown.

The shortcode provided is [custom-field], which has a number of attributes to customize its behavior and output.

Find out more at the plugin’s WordPress Plugin Repository page.

Screenshots

Click to see full-size image.

  1. Screenshot of the plugin's widget configuration.

    Screenshot of the plugin’s widget configuration.

  2. Screenshot of the plugin's shortcode builder (not available in the block editor, aka Gutenberg).

    Screenshot of the plugin’s shortcode builder (not available in the block editor, aka Gutenberg).

Installation

  1. Install via the built-in WordPress plugin installer. Or install the plugin code inside the plugins directory for your site (typically /wp-content/plugins/).
  2. Optional: Add filters for ‘the_meta’ to filter custom field data (see the end of the plugin file for commented out samples you may wish to include). And/or add per-meta filters by hooking ‘the_meta_$field’
  3. Activate the plugin through the ‘Plugins’ admin menu in WordPress
  4. Give post(s) a custom field with a value.
  5. Optional: Go to the Appearance -> Widgets admin page to create one or more ‘Get Custom Field’ sidebar widgets for your widget-enabled theme.
  6. Optional: Use one of the six template functions provided by this plugin to retrieve the contents of custom fields. You must ‘echo’ the result if you wish to display the value on your site.
  7. Optional: Use the provided shortcode within posts or wherever shortcodes are supported.

Release Log

4.1 (2023-10-08)

  • Hardening: Restrict markup used in widget to safe HTML. Props Satoo Nakano (Patchstack).
  • Change: Ensure show_metabox() only potentially returns true for post screens
  • Change: Add inline documentions for shortcode-related hooks
  • Change: Tweak some formatting in DEVELOPER-DOCS.md
  • Change: Clarify references to shortcode-related hook in DEVELOPER-DOCS.md
  • Change: Note compatibility through WP 6.3+
  • Change: Update copyright date (2023)
  • New: Add .gitignore file
  • Unit tests:
    • Fix: Allow tests to run against current versions of WordPress
    • New: Add composer.json for PHPUnit Polyfill dependency
    • Change: Prevent PHP warnings due to missing core-related generated files
    • Change: In bootstrap, add backcompat for PHPUnit pre-v6.0
    • Fix: Fix tests associated with show_metabox() and add two new tests

4.0.1 (2021-11-05)

  • Change: Further restrict usage of shortcode to only those with ‘unfiltered_html’ capability. Props Erwan.
  • New: Add a few more possible TODO items

4.0 (2021-11-04)

  • Change: Prevent users who can’t publish posts from using the shortcode in posts. Props Francesco Carlucci.
    • Hardens security to prevent potentail information disclosure or XSS by authors with limited privileges
    • New: Add shortcode class function can_author_use_shortcodes()
    • New: Add filter 'get_custom_field_values/can_author_use_shortcodes'
    • Change: Prevent shortcodes created by users who cannot publish posts from being evaulated
    • Change: Prevent display of shortcode builder metabox to users who cannot publish posts
  • New: Add filter 'get_custom_field_values/show_metabox' to customize if shortcode builder metabox is shown
  • New: Add DEVELOPER-DOCS.md and move template tag and shortcode documentation into it
  • Change: Note compatibility through WP 5.8+
  • Change: Update copyright date (2021)
  • Change: Tweak installation instruction
  • Unit tests:
    • Change: Split shortcode-related tests out into their own file
    • Change: Split widget-related tests out into their own file
    • New: Add helper functions to facilitate creating users
      • New: Add create_user() for creating a user and optionally making them the current user
      • New: Add unset_current_user() for unsetting the current user
      • New: Add tearDown() to ensure current user gets unset after each test
    • New: Add unit tests for show_metabox()
    • Change: Reduce likelihood of particular randomization tests from failing due to reasonable possibility of subsequent randomization choosing the same item
    • Change: Add optional arg $make_global (defaulted to false) to create_post_with_meta() to facilitate making the created post global
    • Change: Restructure unit test file structure
      • Change: Move phpunit/bin/ to tests/bin/
      • Change: Move phpunit/bootstrap.php into tests/phpunit/
      • Change: Move tests from phpunit/tests/ to tests/phpunit/tests/
      • Change: In bootstrap, store path to plugin file constant so its value can be used within that file and in test file
      • Change: In bootstrap, check for test installation in more places and exit with error message if not found
      • Change: Remove ‘test-‘ prefix from unit test files
  • New: Add a few more possible TODO items

Copyright & Disclaimer

Copyright © 2004-2024 by Scott Reilly (aka coffee2code)

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Discussion / Support

Have any questions, comments, or suggestions? Please provide them via the plugin’s WordPress.org support forum. I’ll do my best to reply in a timely fashion and help as best I can.

Unfortunately, I cannot provide guaranteed support, nor do I provide support via any other means.

Was this plugin useful useful to you? Consider giving it a rating. If you’re inclined to give it a poor rating, please first post to the support forum to give me a chance to address or explain the situation.

27 replies on “Get Custom Field Values”