coffee2code

Extended Description

Installation

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.
• 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

• Get random random quote

• Get 3 most recent books read

Frequently Asked Questions

Q. I added the template tag to my template and the post has the custom field I’m asking for but I don’t see anything about it on the page; what gives?
A. Did you echo the return value of the function, e.g. <?php echo c2c_get_custom('mood', 'My mood: '); ?>

Q. Can I achieve all the functionality allowed by the six template functions using the widget?
A. Except for c2c_get_custom() (which is only available inside “the loop”), yes, by carefully setting the appropriate settings for the widget.

Q. How do I configure the widget to match up with the template functions?
A.

• c2c_get_custom() : not achievable via the widget
• c2c_get_current_custom() : set the “Post ID” field to 0, leave “Pick random value?” unchecked, and set other values as desired.
• c2c_get_post_custom() : set the “Post ID” field to the ID of the post you want to reference and set other values as desired.
• c2c_get_random_custom() : leave “Post ID” blank, check “Pick random value?”, and set other values as desired.
• c2c_get_random_post_custom() : set the “Post ID” field to the ID of the post you want to reference, check “Pick random value?”, and set other values as desired.
• c2c_get_recent_custom() : leave “Post ID” blank, leave “Pick random value?” unchecked, and set other values as desired.

Q. I don’t plan on using the shortcode builder when writing or editing a post or page, so how do I get rid of it?
A. When on the write or edit admin pages for a page or post, find the “Screen Options” link near the upper right-hand corner of the page. Clicking it slides down a panel of options. In the “Show on screen” section, uncheck the checkbox labeled “Get Custom Field Values – Shortcode”. This must be done separately for posts and for pages if you want the shortcode builder disabled for both sections.

Q. Can I move the shortcode builder box because it is way down at the bottom of the right sidebar when I create/edit posts?
A. Yes, any of the boxes on the page when creating/editing posts can be rearranged by dragging and dropping the box name. At the very top of the shortcode builder box the cursor will turn into a four-way array indicating you can click to drag that box. You can move it under the post content box, or higher up on the right side.

Release Log

3.3.2

• Fix bugs in widget preventing proper display of custom field for current post (props Ross Higgins)
• Trim and/or intval widget input fields in validate()
• For shortcode widget’s JS, output via ‘admin_print_footer_scripts’ instead of ‘admin_footer’
• Note compatibility through WP 3.3
• Add ‘Domain Path’ directive to top of main plugin file
• Add link to plugin directory page to readme.txt
• Update copyright date (2012)

3.3.1

• Fix fatal shortcode bug by updating widget framework to v005 to make a protected class variable public
• Update widget version to 003

3.3

• Modify c2c_get_random_custom() to support returning multiple random values (function now accepts additional arguments)
• Rename widget class from ‘GetCustomWidget’ to ‘c2c_GetCustomWidget’
• Enable shortcode support for custom field values
• Update widget framework to v004
• Document shortcode
• Note compatibility through WP 3.2+
• Minor code formatting changes (spacing)
• Minor readme.txt formatting changes
• Add plugin homepage and author links in description in readme.txt
• Add .pot
• Update copyright date (2011)

3.2

• Fix ‘Send to Editor’ for shortcode builder
• (widget) Full re-implementation using C2C_Widget_002
• (widget) Full localization support
• (widget) Fix bug with saving widget
• (shortcode) Output JS in footer instead of head
• Add if(!function_exists()) checks around all functions
• Change description
• Add PHPDoc documentation
• Remove docs from top of plugin file (all that and more are in readme.txt)
• Add package info to top of file
• Note compatibility with WP 3.0+
• Drop compatibility with version of WP older than 2.8
• Minor code reformatting (spacing)
• Add Upgrade Notice section to readme.txt
• Remove trailing whitespace
• Update copyright date
• Update screenshots

3.1

• (Not publicly released.)

3.0.1

• Added additional check to prevent error when running under WP older than 2.8

3.0

• Added widget support (widgetized the plugin)
• Added shortcode support ()
• Added c2c_get_post_custom() : Useful when you know the ID of the post whose custom field value you want.
• Added 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
• Added c2c_get_random_post_custom() : Retrieve the value of a random instance of the specified custom field key for a given
  post
• Added c2c_get_recent_custom() : Retrieves the most recent (according to the associated post’s publish date) value of
  the specified custom field.
• Used $wpdb->prepare() to safeguard queries
• Updated copyright
• Noted compatibility through 2.8+
• Dropped compatibility with versions of WP older than 2.6
• Tweaked description and docs

2.5

• Modified SQL query code for c2c_get_recent_custom() to explicitly look for post_type of ‘post’ and then optionally of ‘page’
• Per-custom field filter name is now made using a sanitized version of the field key
• Minor code reformatting
• Removed pre-WP2.0 compatibility and compatibility checks
• Changed description
• Updated copyright date and version to 2.5
• Added readme.txt
• Tested compatibility with WP 2.3.3 and 2.5

2.1

• 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)

2.02

• Minor bugfix

2.01

• Minor bugfix

2.0

• 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

1.0

• Added argument of $before_last (which, when $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_custom())

0.91

• Minor bugfix

0.9

• Initial release

Copyright & Disclaimer