WP Biographia

外掛說明

This plugin allows you to add a customisable biography to posts, to RSS feeds, to pages, to archives and to each post on your blog’s landing page as well as via a widget in your sidebar. It integrates out of the box with the information that can be provided in each user’s profile and supports custom post types. Display of the Biography Box can be hidden on a global or per user basis for posts, pages and custom post types as well as on a per category basis.

Settings and options include:

1. Choose when to display a Biography Box; on the front page, in archives, on individual posts, pages, or any other custom post type and in RSS feeds.
2. Choose the border style and background colour of the Biography Box
3. Choose the amount of user profile information displayed in the Biography Box
4. Choose the avatar image size
5. Choose to display the Biography Box at the top or the bottom of content (universally)
6. Choose to hide the display of the Biography Box for pages, posts and posts/pages on a per user basis
7. Choose whether to display the Biography Box in the sidebar of your blog.

The plugin expands and enhances the Contact Info section of your user profile, adding support for Twitter, Facebook, LinkedIn, Google+, Delicious, Flickr, Picasa, Vimeo, YouTube and Reddit profile links as well as Yahoo! Messenger, AIM, Windows Live Messenger and Jabber/Google Talk instant messaging profiles. Your Contact Info links can then be displayed as part of the Biography Box, either as plain text links or as icon links. Further contact links can easily be added to the Biography Box by using the wp_biographia_contact_info and wp_biographia_link_items filters.

The position of the Biography Box can be controlled by the plugin’s supported settings and options, or manually via the plugin’s shortcode ([wp_biographia]) (see the Shortcode Support And Usage section for more information) or via template tags in your theme’s template files (see the Template Tags section for more information).

The position and content of the Biography Box, including adding support for new contact links, changing the content of the Biography Box when displayed via the shortcode, the format of the contact links and the overall format of the Biography Box can be modified by the plugin’s filters. See the Filter Support And Usage section for more information.

The plugin also supports displaying a reduced version of the Biography Box via a sidebar widget and provides a shorter, more terse, biography in the user’s Profile to prevent the full length biography text taking up too much space on the sidebar.

Shortcode Support And Usage

WP Biographia supports a single shortcode, [wp_biographia]. Adding this shortcode to the content of a post or page or into a theme template as content, expands the shortcode and replaces it with a Biography Box.

The shortcode also supports multiple attributes which allow you to customise the way in which the shortcode is expanded into the Biography Box:

• the mode attribute
• the user attribute
• the author attribute (deprecated)
• the role attribute
• the order attribute
• the prefix attribute
• the name attribute
• the type attribute

The “mode” Attribute

In raw mode, which is the default (specified as [wp_biographia mode="raw"] or simply as [wp_biographia]), the plugin inserts the Biography Box in you’ve asked for it, you’ve got it mode.

Or to put it another way, the plugin will honour the settings that you specify under Dashboard / Settings/ WP Biographia for Biography Box Style Settings and for Biography Box Content Settings but will ignore the Biography Box Display Settings and Biography Box Per User Settings.

In configured mode, specified as [wp_biographia mode="configured"], the plugin inserts the Biography Box and will honour all the settings under Dashboard / Settings / WP Biographia with the exception of Display On Front Page, Display On Individual Post, Display On Post Archives and Display On Individual Pages, as well as their equivalents for any custom post types you may have created.

The thinking behind this is that you probably want to honour post or page exclusions and per user exclusions, but by using the shortcode in your posts, you want to be in control of how and where the Biography Box is displayed.

The “user” Attribute

If the user attribute is omitted, which is the default, the shortcode assumes it’s being used within the WordPress Loop and will display the Biography Box once for the current post’s, page’s or custom post type’s user.

Specifying a user’s login name as the user attribute overrides this behaviour and allows multi-user sites to use the plugin to create a contributors page, where you use the shortcode as [wp_biographia user="login-name"] once for each of your site’s users that you want to appear, replacing "login-name" with a valid login name for one of your users.

You call also use the user attribute in wildcard mode, specifying the user’s login name as * as [wp_biographia user="*"]; this will then loop over all of the users that have logins on your site, displaying the Biography Box once for each user, ordered alphabetically by login name.

Specifying an invalid login name ([wp_biographia user="idontexist"]) will result in no Biography Box being displayed. Specifying an empty login name ([wp_biographia user=""]) will cause the user attribute to be ignored and may result in undefined behaviour, such as a partially populated Biography Box being displayed as the shortcode is being used outside of the Loop and thus no user information is made available to the plugin by WordPress.

The “author” Attribute

The author attribute is now deprecated in favour of the user attribute introduced in v3.2.0 of the plugin. If the author attribute is used and no user attribute is present, the author attribute will act in the same way as the user attribute, described above. If both the user and author attributes are present, the author attribute will be ignored in favour of the user attribute.

In other words, if you use the shortcode and supply both the author and user attributes, such as [wp_biographia author="foo" user="bar"], the Biography Box will be displayed for the user bar, not the user foo. Likewise, [wp_biographia user="*" author="foo"] will display the Biography Box in wildcard mode, not for the user foo.

Support for the author attribute will be likely be removed in a future release of the plugin to avoid confusion over the author and user attributes.

The “role” Attribute

Valid only when used in conjunction with the user attribute in wildcard mode, the role attribute allows you to filter the users that have user accounts on your blog according to their WordPress Role. The role attribute takes one or more comma separated arguments which define the WordPress role(s); at the time of writing, these can be one of:

• administrator
• editor
• author
• contributor
• subscriber

For example, if you want to display the Biography Box for all users of your blog who have a role of author you can use the role attribute plus the author attribute in wildcard mode to do this, along the lines of [wp_biographia user="*" role="author"]. If you want to display the Biography Box for all users with a role of author or contributor, you can specify both roles, along the lines of [wp_biographia user="*" role="author,contributor"].

Specifying an invalid role ([wp_biographia user="*" role="foo"]) will result in no Biography Box being displayed. Specifying the role attribute without the user attribute in wildcard mode will have no effect.

The “order” Attribute

Valid only when used in conjunction with the user attribute in wildcard mode, the order attribute allows you to specify the display order for the users that have user accounts on your blog. The order attribute takes a single argument which defines the sorting order; at the time of writing, this can be one of:

• account-name (the default)
• first-name
• last-name
• nickname
• display-name
• login-id

For example, if you want to display the Biography Box for all users of your blog ordered according to their last name you can use the order attribute plus the author attribute in wildcard mode to do this, along the lines of [wp_biographia user="*" order="last-name"].

Specifying an invalid role ([wp_biographia user="*" order="foo"]) will result in the default account name sort order being used. Specifying the order attribute without the user attribute in wildcard mode will have no effect.

It’s important to note that the in order to successfully sort by first-name or by last-name, the First Name and/or Last Name fields must be populated in each user’s Profile; by default, these fields are not populated during the creation of a user’s WordPress account. The sorting of the user accounts when the order attribute is specified uses natural order string comparison, which means than an empty First Name or Last Name will appear before a First Name or Last Name which actually contains a value. If your WordPress site doesn’t have these name fields populated in your user’s Profiles, you may not see the sorting results you expect.

The “prefix” Attribute

If the prefix attribute is omitted, which is the default, the Biography Box will be displayed with Biography Prefix text configured in Settings/ WP Biographuia / Biography Box Content Settings before the user’s name. This can be overridden by using the prefix attribute, along the lines of [wp_biographia prefix="All About"].

The “name” Attribute

If the name attribute is omitted, which is the default, the Biography Box will be displayed with the user’s name as configured by User’s Name in Settings / WP Biographia /Biography Box Content Settings. This can be overriden by supplying one of the following for the name attribute’s argument:

• account-name
• first-last-name
• nickname
• display-name
• none

The “type” Attribute

If the type attribute is omitted, which is the default, the Biography Box will be displayed with the user’s full biography text, taken from the Biographical Info field in the user’s profile. If the type attribute is specified with a value of full, this is equivalent to the default behaviour. If the type attribute is specified with a value of excerpt, the Biographical Excerpt field in the user’s profile will be used instead, providing the user has filled out this field in their profile. Specifying an invalid type attribute value ([wp_biographia type="foo"]) will result in the default behaviour of the full biography being used.

Filter Support And Usage

WP Biographia supports multiple filters, which are described in more detail below. The plugin’s filters allow you to:

• change the default set of installation settings and options at plugin activation time
• modify and/or enhance the set of contact information fields the plugin adds to the user’s profile
• modify and/or enhance the contact links that are added to the Biography Box by the plugin
• modify the position of the Biography Box to before or after the post content returned by the_content() and/or the_excerpt()
• hide the display of the Biography Box entirely under user-defined circumstances
• modify and/or enhance the Biography Box that is produced by the [wp_biographia] shortcode
• modify and/or enhance the format and content of the contact links that are added to the Biography Box by the plugin
• modify and/or enhance the Biography Box that is produced for an RSS feed
• modify and/or enhance the entirety of the Biography Box

wp_biographia_default_settings

Applied to the default set of plugin settings and options. Note that this filter is called once, upon plugin activation, when there are no WP Biographia settings/options existing in the database.

Example: Add the date and time that the plugin was first activated

add_filter ('wp_biographia_default_settings', 'add_activation_timestamp');

function add_activation_timestamp ($options) {
    // options = array (option name => option value)
    $options['plugin_activation_timestamp'] = date (DATE_ATOM);

    return $options;
}

wp_biographia_contact_info

Applied to the default set of contact information fields that are added to an user’s profile by the plugin. Note that in order to add and display a new contact link to the Biography Box, the contact link must be added to the value returned by the wp_biographia_link_items filter as well as the value returned by this filter.

Example: Add Pinterest as a supported contact information field

add_filter ('wp_biographia_contact_info', 'add_pinterest_support');

function add_pinterest_support ($contacts) {
    // contacts = array (field => array (field => field-name, contactmethod => description))
    $contacts['pinterest'] = array (
        'field' => 'pinterest',
        'contactmethod' => __('Pinterest')
    );

    return $contacts;
}

wp_biographia_link_items

Applied to the default set of contact links that are added to the Biography Box by the plugin. Note that in order to add and display a new contact link, the contact information field must be added to the value returned by the wp_biographia_contact_info filter as well as the value returned by this filter. Note that $icon_dir_url will by default contain the URL of the images directory within the plugin directory, which will look something like /wp-content/plugins/wp-biographia/images/ (the trailing slash is important). If an alternate icon directory has been specified in the plugin’s settings and options, then $icon_dir_url will contain this alternate, configured, directory URL. If the icon you want to add for a new contact link doesn’t reside in the directory URL mentioned previously, you’ll need to set $icon_dir_url to point to your own custom location.

Example: Add Pinterest as a supported contact link in the Biography Box

add_filter ('wp_biographia_link_items', 'add_pinterest_link', 2);

function add_pinterest_link ($links, $icon_dir_url) {
    // links = array (field => array (link_title => title, link_text => text, link_icon => URL)
    $links['pinterest'] = array (
        'link_title' => __('Pinterest'),
        'link_text' => __('Pinterest'),
        'link_icon' => $icon_dir_url . 'pinterest.png'
        );

        return $links;
}

wp_biographia_pattern

Applied to the format string used to position the Biography Box before the post content or after the post content that is returned by the_content() and/or the_excerpt().

Example: Insert a header between post content and Biography Box

add_filter ('wp_biographia_pattern', 'insert_biography_header');

function insert_biography_header ($pattern) {
    return '%1$s<p class="biography-header">About The User</p>%2$s';
}

wp_biographia_pre

Allows display of the Biography Box to be hidden under user-defined circumstances. This only affects the display of the Biography Box that is configured via the plugin’s admin screen or via the shortcode in configured mode.

Example: Hide the Biography Box

add_filter ('wp_biographia_pre', 'hide_biography_box');

function hide_biography_box ($flag) {
    return true;
}

wp_biographia_shortcode

Applied to the current instance of the Biography Box that is produced via the [wp_biographia] shortcode.

Example: Apply shortcode specific CSS to the Biography Box

add_filter ('wp_biographia_links', 'add_shortcode_css', 10, 2);

function add_shortcode_css ($content, $params) {
    // params = array (mode => shortcode-mode, user => author-id, prefix => prefix-string,
                        name => name-option)

    return '<div class="custom-shortcode-css">' . $content . '</div>';
}

wp_biographia_content_title

Applied to the title of the Biography Box.

Example: Override the name prefix for all uses of the Biography Box.

add_filter ('wp_biographia_content_title', 'override_name_prefix', 10, 3);
function override_name_prefix ($content, $name_prefix, $formatted_name) {
    return 'This is ' . $formatted_name;
}

wp_biographia_links

Applied to the formatted set of contact links for the current instance of the Biography Box.

Example: Replace the default text link separator character (the pipe symbol “|”) with a dash (“-“).

add_filter ('wp_biographia_links', 'replace_link_separator', 10, 3);

function replace_link_separator ($content, $links, $params) {
    // links = array (link-item)
    // params = array (glue => separator-string, class => link-item-css-class-name,
    //                  prefix => links-prefix-html, postfix => links-postfix-html)

    return str_replace ($params['glue'], ' - ', $content);
}

Example: Wrap the formatted content links in an additional HTML div.

add_filter ('wp_biographia_links', 'wrap_links', 10, 3);

function wrap_links ($content, $links, $params) {
    // links = array (link-item)
    // params = array (glue => separator-string, class => link-item-css-class-name,
    //                  prefix => links-prefix-html, postfix => links-postfix-html)

    $new_prefix = '<div class="custom-link-class">' . $params['prefix'];
    $new_postfix = $params['postfix'] . '</div>';

    return $new_prefix . implode ($params['glue'], $links) . $new_postfix;
}

wp_biographia_link_item

Applied to each active contact link, in the order in which they are processed by the plugin.

Example: Force all links that point to the current site to open in a new window.

add_filter ('wp_biographia_link_item', 'filter_link_item', 10, 2);

function filter_link_item ($content, $params) {
    // $params = array (
    //      'type' => 'link type (icon|text)',
    //      'format' => 'link format string',
    //      'meta' => 'additional anchor attributes',
    //      'title' => 'link title',
    //      'url' => 'link URL',
    //      'body' => 'link body text',
    //      'link-class' => 'link CSS class name',
    //      'item-class' => 'link item CSS class name (icons only)'
    //  );

    $site_url = site_url ();
    $pos = strpos ($params['url'], $site_url);
    if ($pos !== false) {
        $params['meta'] = 'target="_blank"';
    }

    if ($params['type'] === 'icon') {
        $content = sprintf ($params['format'], $params['url'], $params['meta'], $params['title'], $params['link-class'], $params['body'], $params['item-class']);
    }

    else {
        $content = sprintf ($params['format'], $params['url'], $params['meta'], $params['title'], $params['link-class'], $params['body']);
    }

    return $content;
}

wp_biographia_feed

Applied to the current instance of the Biography Box that is produced via the site’s RSS feed.

Example: Apply RSS feed specific CSS to the Biography Box

add_filter ('wp_biographia_feed', 'add_feed_css');

function add_feed_css ($content) {
    return '<div class="custom-feed-css">' . $content . '</div>';
}

wp_biographia_biography_box

Applied to the entire content of the current instance of the Biography Box.

Example: Remove all WP Biographia CSS classes commencing wp-biographia- and replace them with custom CSS classes that adhere to the plugin’s CSS class naming convention.

add_filter ('wp_biographia_biography_box', 'replace_css_classes', 10, 2);

function replace_css_classes ($biography, $items) {
    $new_content = array ();

    foreach ($items as $item) {
        $new_content[] = str_replace ('wp-biographia-', 'custom-', $item);
    }

    return implode ('', $new_content);
}<h3>Template Tags</h3>

WP Biographia supports two template tags that can be used in your theme’s template files. These are described in more detail below; for a full description of the use of each tag’s argument, see the Shortcode Support And Usage section. The plugin’s tags allow you to:

• produce the Biography Box and assign the HTML for the Biography Box to a string.
• produce the Biography Box and echo the results immediately.

wpb_get_biography_box

Description: Retrieves the Biography Box. This template tags renders the Biography Box and returns it to the caller as a string. To display the Biography Box immediately, use the wpb_the_biography_box template tag.

Usage:

<?php $biography_box = wpb_get_biography_box ($mode, $user, $prefix, $name, $role, $type, $order); ?>

Parameters:

• $mode – (string) (optional) Override the Biography Box mode (raw|configured). Default: raw.
• $user – (string) (optional) Override the source user (login-name|*). Default: the current user’s login name.
• $prefix – (string) (optional) Override the Biography Box title prefix. Default: use the plugin’s settings.
• $name – (string) (optional) Override the selected user’s name format (account-name|first-last-name|nickname|display-name|none). Default: use the plugin’s settings.
• $role – (string) (optional) Override the selected user’s role when used in wildcard mode. Specify one or more of the following, as a comma separated list (administrator|editor|author|contributor|subscriber). Default: none.
• $type – (string) (optional) Override the type of the biography text (full|excerpt). Default: use the plugin’s settings.
• $order – (string) (optional) Override the sort order when used in wildcard mode (account-name|first-name|last-name|nickname|display-name|login-id). Default: account-name.

wpb_the_biography_box

Description: Displays the Biography Box. This template tags renders the Biography Box and displays it immediately. To get the current Biography Box as a string, use the wpb_get_biography_box template tag.

Usage:

<?php wpb_the_biography_box ($mode, $user, $prefix, $name, $role, $type, $order); ?>

Parameters:

• $mode – (string) (optional) Override the Biography Box mode (raw|configured). Default: raw.
• $user – (string) (optional) Override the source user (login-name|*). Default: the current user’s login name.
• $prefix – (string) (optional) Override the Biography Box title prefix. Default: use the plugin’s settings.
• $name – (string) (optional) Override the selected user’s name format (account-name|first-last-name|nickname|display-name|none). Default: use the plugin’s settings.
• $role – (string) (optional) Override the selected user’s role when used in wildcard mode. Specify one or more of the following, as a comma separated list (administrator|editor|author|contributor|subscriber). Default: none.
• $type – (string) (optional) Override the type of the biography text (full|excerpt). Default: use the plugin’s settings.
• $order – (string) (optional) Override the sort order when used in wildcard mode (account-name|first-name|last-name|nickname|display-name|login-id). Default: account-name.