* @copyright Copyright (c) 2007 - 2012, Justin Tadlock
* @link http://justintadlock.com/archives/2007/11/01/wordpress-custom-fields-listing-a-series-of-posts
* @license http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
*/
/* Add support for the 'custom-field-series' extension to posts. */
add_action( 'init', 'custom_field_series_post_type_support' );
/* Register metadata for the custom field series. */
add_action( 'init', 'custom_field_series_register_meta' );
/* Create the meta box on the 'admin_menu' hook. */
add_action( 'admin_menu', 'custom_field_series_admin_setup' );
/**
* Checks for a series of posts by the current post's metadata. The function grabs the meta value for the
* 'Series' meta key and checks if any posts have been given the same value. If posts are found with this
* meta key/value pair, the function adds them to an unordered list.
*
* @since 0.1.0
* @access public
* @param array $args Array of arguments.
*/
function custom_field_series( $args = array() ) {
/* Set $series to an empty string. */
$series = '';
/* Get the current post ID. */
$post_id = get_the_ID();
/* Get the series meta value for the post. */
$meta_value = get_post_meta( $post_id, custom_field_series_meta_key(), true );
/* If a meta value was found, create a list of posts in the series. */
if ( !empty( $meta_value ) ) {
/* Set up the default post query arguments. */
$defaults = array(
'order' => 'DESC',
'orderby' => 'ID',
'include' => '',
'exclude' => '',
'post_type' => 'any',
'numberposts' => -1,
'meta_key' => custom_field_series_meta_key(),
'meta_value' => $meta_value,
'echo' => true
);
/* Allow developers to override the arguments used. */
$args = apply_filters( 'custom_field_series_args', $args );
$args = wp_parse_args( $args, $defaults );
/* Get all posts in the current series. */
$series_posts = get_posts( $args );
/* If posts were found, display them. */
if ( !empty( $series_posts ) ) {
/* Format the series class with the name of the series. */
$class = sanitize_html_class( sanitize_title_with_dashes( $meta_value ) );
/* Create the opening wrapper div, title, and list element. */
$series = '
';
$series .= '
' . apply_filters( 'custom_field_series_title', __( 'Articles in this series', 'custom-field-series' ) ) . '
';
$series .= '
';
/* Loop through the posts. */
foreach ( $series_posts as $serial ) {
/* If the current post in the loop matches the post we're viewing, don't link to it. */
if ( $serial->ID == $post_id )
$series .= '
' . $serial->post_title . '
';
/* Display a link to the post. */
else
$series .= '
';
}
/* Close the unordered list and wrapper div. */
$series .= '
';
}
}
/* Allow developers to overwrite the HTML of the series. */
$series = apply_filters( 'custom_field_series', $series );
/* If $echo is set to true, display the series. */
if ( !empty( $args['echo'] ) )
echo $series;
/* If $echo is not set to true, return the series. */
else
return $series;
}
/**
* Adds post type support of 'custom-field-series' to the 'post' post type. Developers should register support
* for additional post types.
*
* @since 0.4.0
* @access private
* @return void
*/
function custom_field_series_post_type_support() {
add_post_type_support( 'post', 'custom-field-series' );
}
/**
* Registers the custom field series meta key 'Series' for for specific object types and provides a
* function to sanitize the metadata on update.
*
* @since 0.4.0
* @access private
* @return void
*/
function custom_field_series_register_meta() {
register_meta( 'post', custom_field_series_meta_key(), 'custom_field_series_sanitize_meta' );
}
/**
* Callback function for sanitizing meta when add_metadata() or update_metadata() is called by WordPress.
* If a developer wants to set up a custom method for sanitizing the data, they should use the
* "sanitize_{$meta_type}_meta_{$meta_key}" filter hook to do so.
*
* @since 0.4.0
* @param mixed $meta_value The value of the data to sanitize.
* @param string $meta_key The meta key name.
* @param string $meta_type The type of metadata (post, comment, user, etc.)
* @return mixed $meta_value
*/
function custom_field_series_sanitize_meta( $meta_value, $meta_key, $meta_type ) {
return strip_tags( $meta_value );
}
/**
* Returns the meta key used for the 'Series' custom field so that developers can overwrite the key if they
* need to for their project.
*
* @since 0.4.0
* @access public
* @return string The meta key used for the series metadata.
*/
function custom_field_series_meta_key() {
return apply_filters( 'custom_field_series_meta_key', 'Series' );
}
/**
* Admin setup for the custom field series script.
*
* @since 0.4.0
* @access private
* @return void
*/
function custom_field_series_admin_setup() {
/* Load the post meta boxes on the new post and edit post screens. */
add_action( 'load-post.php', 'custom_field_series_load_meta_boxes' );
add_action( 'load-post-new.php', 'custom_field_series_load_meta_boxes' );
}
/**
* Hooks into the 'add_meta_boxes' hook to add the custom field series meta box and the 'save_post' hook
* to save the metadata.
*
* @since 0.4.0
* @access private
* @return void
*/
function custom_field_series_load_meta_boxes() {
/* Add the custom field series meta box on the 'add_meta_boxes' hook. */
add_action( 'add_meta_boxes', 'custom_field_series_create_meta_box', 10, 2 );
/* Saves the post meta box data. */
add_action( 'save_post', 'custom_field_series_meta_box_save', 10, 2 );
}
/**
* Creates the meta box on the post editing screen for the 'post' post type.
*
* @since 0.3.0
* @access private
* @param string $post_type The post type of the current post being edited.
* @param object $post The current post object.
* @return void
*/
function custom_field_series_create_meta_box( $post_type, $post ) {
if ( post_type_supports( $post_type, 'custom-field-series' ) )
add_meta_box( 'custom-field-series', __( 'Series', 'custom-field-series' ), 'custom_field_series_meta_box', $post_type, 'side', 'default' );
}
/**
* Displays the input field with the meta box.
*
* @since 0.3.0
* @access private
* @param object $object The post object currently being edited.
* @param array $box Specific information about the meta box being loaded.
* @return void
*/
function custom_field_series_meta_box( $object, $box ) { ?>