coffee2code

Extended Description

Installation

c2c_get_author_custom()

Template Tags

The plugin provides three optional template tags for use in your theme templates.

Functions

• <?php function c2c_get_current_user_custom( $field, $before='', $after='', $none='', $between='', $before_last='' ) ?>
  This allows access to custom fields for the currently logged in user. If the current visitor is NOT logged in, then the $none value is returned.

• <?php function c2c_get_author_custom( $field, $before='', $after='', $none='', $between='', $before_last='' ) ?>
  This allows access to custom fields for the current author (when on the permalink page for a post, page, or in a loop).

• <?php function c2c_get_user_custom( $user_id, $field, $before='', $after='', $none='', $between='', $before_last='' ) ?>
  This allows access to custom fields for any user specified by the $user_id value.

Arguments

• $user_id
  (only for c2c_get_user_custom()) The integer value of the user’s id.

• $field
  The name of the user custom field to display.

• $before
  (optional) The text to display before all field value(s).

• $after
  (optional) The text to display after all field value(s).

• $none
  (optional) The text 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
  (optional) 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) The text to display between the next-to-last and last items listed when multiple occurrences of the custom field exist; $between MUST be set to something other than ” for this to take effect.

Examples

• <?php c2c_get_current_user_custom('first_name'); ?>
  “Scott”

• <?php c2c_get_current_user_custom('favorite_colors', 'Favorite colors: '); /* Where the 'favorite_colors' user custom field has been defined with values ?>
  “Favorite colors: blue, gray, green, black, red”

• <?php c2c_get_current_user_custom('favorite_colors', 'Favorite colors: <ul><li>', '</li></ul>', '', '</li><li>'); ?>
  “Favorite colors:

• blue
• gray
• green
• black
• red

“

• <?php echo c2c_get_user_custom(3, 'first_name', 'Hi, ', '. Welcome back.'); // where 3 is the id of the user we want ?>
  “Hi, Scott. Welcome back.”

Filters

The plugin exposes five filters for hooking. Typically, customizations utilizing these hooks would be put into your active theme’s functions.php file, or used by another plugin.

c2c_get_current_user_custom (filter)

The ‘c2c_get_current_user_custom’ hook allows you to use an alternative approach to safely invoke c2c_get_current_user_custom() in such a way that if the plugin were deactivated or deleted, then your calls to the function won’t cause errors in your site.

Arguments:

• same as for c2c_get_current_user_custom()

Example:

Instead of:

<?php $twitter = c2c_get_current_user_custom( 'twitter' ); ?>

Do:

<?php $twitter = apply_filters( 'c2c_get_current_user_custom', 'twitter' ); ?>

c2c_get_author_custom (filter)

The ‘c2c_get_author_custom’ hook allows you to use an alternative approach to safely invoke c2c_get_author_custom() in such a way that if the plugin were deactivated or deleted, then your calls to the function won’t cause errors in your site.

Arguments:

• same as for c2c_get_author_custom()

Example:

Instead of:

<?php $aim = c2c_get_author_custom( 'aim', 'AIM: ' ); ?>

Do:

<?php $aim = apply_filters( 'c2c_get_author_custom', 'aim', 'AIM: ' ); ?>

c2c_get_user_custom (filter)

The ‘c2c_get_user_custom’ hook allows you to use an alternative approach to safely invoke c2c_get_user_custom() in such a way that if the plugin were deactivated or deleted, then your calls to the function won’t cause errors in your site.

Arguments:

• same as for c2c_get_user_custom()

Example:

Instead of:

<?php $address = c2c_get_user_custom( 5, 'address' ); ?>

Do:

<?php $address = apply_filters( 'c2c_get_user_custom', 5, 'address ); ?>

c2c_get_user_custom_field_values_shortcode (filter)

The ‘c2c_get_user_custom_field_values_shortcode’ hook allows you to define an alternative to the default shortcode tag. By default the shortcode tag name used is ‘user_custom_field’. It is recommended you only utilize this filter before making use of the plugin’s shortcode in posts and pages. If you change the shortcode tag name, then any existing shortcodes using an older name will no longer work (unless you employ further coding efforts).

Arguments:

• $shortcode (string)

Example:

// Use a shorter shortcode: i.e. [ucf field="last_name" /]
add_filter( 'c2c_get_user_custom_field_values_shortcode', 'change_c2c_get_user_custom_field_values_shortcode' );
function change_c2c_get_user_custom_field_values_shortcode( $shortcode ) {
    return 'ucf';
}

c2c_get_user_custom-user_field_proxy (filter)

The ‘c2c_get_user_custom-user_field_proxy’ hook allows you to prevent proxying to user object fields if no custom value for the custom field was found for the user. By default, if a user does not have a value for the given custom field, the plugin will compare the field name to the small list of user object fields (i.e. user table fields) to see if it is a valid user field. If so, then the user field value (as opposed to custom field value) is returned.

Arguments:

• $allow_proxy (boolean) Default of true.

Example:

// Prevent user field proxying: i.e. this would not return anything: [user_custom_field field="user_email" user_id="1" /]
add_filter( 'c2c_get_user_custom-user_field_proxy', '__return_false' );

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.

user_custom_field

The only shortcode provided by this plugin is named user_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.

The name of the shortcode can be changed via the filter ‘c2c_get_user_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).

Attributes:

• field : (string) The name of the user custom field key whose value you wish to have displayed.
• this_post : (boolean) Get the custom field value for the author of the post containing this shortcode? Takes precedence over user_id attribute. Specify 1 (for true) or 0 for false. Default is 0.
• user_id : (integer) ID of user whose custom field’s value you want to display. Leave blank to search for the custom field for the currently logged in user. Use 0 to indicate it should only work on the permalink page for a page/post.
• 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 nickname for current post’s author

[user_custom_field field="nickname" this_post="1" /]

• Get AIM account name for a specific user

[user_custom_field field="aim" user_id="2" /]

• Wrap post author’s bio in markup, but only if the author has a bio.

[user_custom_field field="description" before="My bio:" /]

Frequently Asked Questions

Q. How do I assign users custom fields so that I can retrieve them using this plugin?
A. The user profile page within WordPress provides inputs for a handful of user custom fields (first_name, last_name, aim, yim, jabber, description, etc). However, you’re probably more interested in creating your own user custom fields. In that case, you’ll have to use another plugin to store custom fields for users, or directly use WordPress functions manually.

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. Clicking it slides down a panel of options. In the “Show on screen” section, uncheck the checkbox labeled “Get User Custom Field Values – Shortcode”. This must be done separately for posts and for pages if you want the shortcode builder disabled for both sections.

Release Log

2.6

• Attempt to return user object field value if no custom fields values found and field name matches user object field name
• Add filter ‘c2c_get_user_custom-user_field_proxy’ to prevent accessing user object fields
• Trim user inputs for widget (and intval user_id) during validation
• Note compatibility through WP 3.3
• Add link to plugin directory page to readme.txt
• Update copyright date (2012)

2.5.1

• Fix fatal shortcode bug by updating widget framework to v005 to make a protected class variable public
• Return immediately in c2c_get_user_custom() if value of $field is empty string
• Update widget version to 003

2.5

• Use get_user_meta() if defined (WP3.0+), rather than direct SQL query
• Use real functions rather than create_function() to register widget and shortcode
• Re-implemented widget, basing it on widget framework v004
• Document shortcode
• Rename widget class from ‘GetUserCustomWidget’ to ‘c2c_GetUserCustomWidget’
• Add filter ‘c2c_get_user_custom_field_values_shortcode’ to allow changing shortcode name
• Rename shortcode class from ‘GetUserCustomFieldValuesShortcode’ to ‘c2c_GetUserCustomFieldValuesShortcode’
• Add screenshots
• Add .pot
• Change extended description
• Minor code formatting changes (spacing)
• Note compatibility through WP 3.2+
• Update copyright date (2011)

2.0 (not publicly released)

• Add hooks ‘c2c_get_current_user_custom’ (filter), ‘c2c_get_author_custom’ (filter), and ‘c2c_get_user_custom’ (filter) to respond to the function of the same name so that users can use the apply_filters() notation for invoking template tags
• Wrap each global function in if(!function_exists()) check
• Remove docs from top of plugin file (all that and more are in readme.txt)
• Note compatibility with WP 2.9+, 3.0+
• Drop compatibility with versions of WP older than 2.8
• Minor tweaks to code formatting (spacing)
• Add Filters, Screenshots, and Upgrade Notice sections to readme.txt
• Add PHPDoc documentation
• Add package info to top of plugin file
• Update copyright date (2010)
• Remove trailing whitespace

1.5 (unreleased)

• Add widget with full support of all capabilities of plugin
• Add shortcode with full support of all capabilities of plugin
• Add c2c_get_author_custom() to access custom fields for the current author (when on the permalink page for a post/page, or in a loop)
• Fix inability to list multiple same-named custom fields that resulted due to changed behavior in WP
• Note compatibility through WP2.8+
• Remove compatibility with versions of WP older than 2.6
• Minor formatting tweaks
• Add Changelog to readme.txt
• Update copyright date

1.0.1

• Minor bugfix

1.0

• Initial release

Copyright & Disclaimer