mgibbs189/custom-field-suite — pull request #235 by chrisvanpatten (2014-11-07 13:08:09+00:00)
Title: Add filters to relationship/user field to allow custom display values

There may be times where the display of a user login name or post title don't provide enough context for end users working with the `user` or `relationship` field types.

This pull request seeks to solve that by making the output of entries in these fields filterable.

The new filters are `cfs_relationship_display` and `cfs_user_display`. (I'm totally open to changing the names.)

## `cfs_relationship_display`

Filter the display output for items in a relationship field

### Arguments

+ `$post_title` (the value of `$post->post_title` for a given post)
+ `$post_id` (the value of `$post->ID` for a given post)

### Usage

Example: displaying a small excerpt of post content with the title

```php
function my_relationship_display( $post_title, $post_id ) {
$display = $post_title;

$post = get_post( $post_id );

if ( ! empty( $post->post_content ) ) {
$content = wp_trim_words( $post->post_content, 5 );
$display .= '
' . $content . '';
}

return $display;
}
add_filter( 'cfs_relationship_display', 'my_relationship_display', 10, 2 );
```

![screen shot 2014-11-07 at 07 52 37](https://cloud.githubusercontent.com/assets/1231306/4953269/a801f02c-667e-11e4-9464-9cabc3b40677.png)

## `cfs_user_display`

Filter the display output for items in a user field

### Arguments

+ `$user_login` (the value of `$user->user_login` for a given user)
+ `$user_id` (the value of `$user->ID` for a given user)

### Usage

Example: displaying a user's first name and email address

```php
function my_user_display( $user_login, $user_id ) {
$user = get_user_by( 'id', $user_id );
return $user->first_name . ' ('. $user->user_email . ')';
}
add_filter( 'cfs_user_display', 'my_user_display', 10, 2 );
```

![screen shot 2014-11-07 at 08 05 34](https://cloud.githubusercontent.com/assets/1231306/4953294/f3fe44b2-667e-11e4-98f9-1f9db1f80349.png)