You use the register_post_type() function to create new post types for a site. It's simple to use and gives plugin developers a lot of flexibility when creating post types.

<?php
register_post_type( $post_type, $args );
?>

The register_post_type() function returns the post type object and accepts two parameters.

WordPress enables many different arguments for the $args parameter, each with its own unique functionality that helps define how your post type will work within the WordPress environment. The following descriptions give you a basic understanding of each.

Now that you've reviewed the arguments of the register_post_type() function, it's time to create your first post type, which is the theme of this chapter.

The first step is to create a new plugin file called boj-music-collection-post-types.php to hold your new plugin called "Music Collection Post Types." Using the following code, you register a post type called music_album.

<?php
/*
Plugin Name: Music Collection Post Types
Plugin URI: http://example.com
Description: Creates the music_album post type.
Version: 0.1
Author: WROX
Author URI: http://wrox.com
*/

/* Set up the post types. */
add_action( 'init', 'boj_music_collection_register_post_types' );

/* Registers post types. */
function boj_music_collection_register_post_types() {

    /* Set up the arguments for the 'music_album' post type. */
    $album_args = array(
        'public' => true,
        'query_var' => 'music_album',
        'rewrite' => array(
            'slug' => 'music/albums',
            'with_front' => false,
        ),
        'supports' => array(
            'title',
            'thumbnail'
        ),
        'labels' => array(
            'name' => 'Albums',
            'singular_name' => 'Album',
            'add_new' => 'Add New Album',
            'add_new_item' => 'Add New Album',
            'edit_item' => 'Edit Album',
            'new_item' => 'New Album',
            'view_item' => 'View Album',
            'search_items' => 'Search Albums',
            'not_found' => 'No Albums Found',

'not_found_in_trash' => 'No Albums Found In Trash'
        ),
    );

    /* Register the music album post type. */
    register_post_type( 'music_album', $album_args );
}

?>

Code snippet boj-music-collection-post-types.php

This creates a new top-level menu item in the WordPress admin called Albums, as shown in Figure 11-1. The new menu item also has two submenu items: Albums and Add New Album. The former links to a page that lists the albums (after they're created) in the order that they've been published. The latter adds a new page for publishing new albums.

Figure 11.1. FIGURE 11-1

This function displays the title of the post. It displays something only if a title is given for the post. For example, if your plugin doesn't set title in the supports argument for register_post_type(), you wouldn't use this function to display a title. It accepts three parameters.

<?php
the_title( $before, $after, $echo );
?>

This function enables you to display the content written in the post editor by the user. For it to display any content, post content must be written. Also, the editor value needs to be added to the supports array for $args in register_post_type() for users to add content. If this is not set, you probably won't need this function.

<?php
the_content( $more_link_text, $stripteaser );
?>

<?php
the_excerpt();
?>

<?php
the_permalink();
?>

The post_type_exists() function checks whether the post type has been registered with WordPress. It accepts a single parameter of $post_type, which should be a string representing the post type name. It returns true if the post type exists or false if it doesn't exist.

<?php
post_type_exists( $post_type );
?>

Suppose you wanted to display a message depending on whether the music_album post type has been registered. Using the following code, you can perform this task.

<?php

/* If music_album post type is registered. */
if ( post_type_exists( 'music_album' ) ) {

    echo 'The music_album post type has been registered.';
}

/* If the music_album post type is not registered. */
else {

    echo 'The music_album post type has not been registered.';
}

?>

You use the add_post_meta() function to add new post metadata to a specific post, which accepts four parameters.

<?php
add_post_meta( $post_id, $meta_key, $meta_value, $unique );
?>

Now that you know how the parameters work for add_post_meta(), you can insert some metadata to a specific post. Suppose you have a post (album) with the ID of 100 and the user's favorite song from the album is "If Code Could Talk." You would use the following code to update this value.

<?php

add_post_meta( 100, 'favorite_song', 'If Code Could Talk', true );

?>

Setting the $unique parameter to true allows for a single value. If you want to allow for multiple values for the favorite_song meta key, you can set it to false. Suppose you want to add another song called "WordPress Makes Me Happy." You can set both values using two instances of add_post_meta().

<?php

add_post_meta( 100, 'favorite_song', 'If Code Could Talk', false );
add_post_meta( 100, 'favorite_song', 'WordPress Makes Me Happy', false );

?>

The get_post_meta() function retrieves metadata for a specific post and accepts three parameters.

<?php
get_post_meta( $post_id, $meta_key, $single );
?>

Suppose you want to get a single meta value for the favorite_song meta key. You can use the following code to display the message "Favorite song from this album: If Code Could Talk."

<?php

/* Get a single favorite song by the favorite_song meta key. */
$favorite_song = get_post_meta( 100, 'favorite_song', true );

/* Display the meta value. */
echo 'Favorite song from this album: ' . $favorite_song;

?>

You could also display each of the meta values for the favorite_song meta key. Imagine that you want to create a list of all the favorite songs.

<?php

/* Get all meta values for the favorite_song meta key. */
$favorite_songs = get_post_meta( 100, 'favorite_song', false );

/* Open an unordered list. */
echo '<ul class="favorite-songs">';

/* Loop through each meta value. */
foreach ( $favorite_songs as $song ) {

    /* Display the individual meta value. */
    echo '<li>' . $song . '</li>';
}

/* Close the unordered list. */
echo '</ul>';

?>

The update_post_meta() function exists to update previous metadata for a specific post or to add new metadata if it is not already set. This function accepts four parameters.

<?php
update_post_meta( $post_id, $meta_key, $meta_value, $prev_value );
?>

If you want to update an existing meta value, use the update_post_meta() function. For example, if you want to change the favorite_song value of "If Code Could Talk" to a new value, "WP Blues," you can use the following code to do this.

<?php

update_post_meta( 100, 'favorite_song', 'WP Blues', 'If Code Could Talk' );

?>

Alternatively, you can overwrite all meta values for the favorite_song meta key by not adding the $prev_value parameter. In the next example, you overwrite all previous values with the value of WP Blues.

<?php

update_post_meta( 100, 'favorite_song', 'WP Blues' );

?>

The delete_post_meta() function enables you to delete metadata for a specific post, and it accepts three parameters.

<?php
delete_post_meta( $post_id, $meta_key, $meta_value );
?>

If you wanted to delete a single value for the favorite_song meta key, you need to make sure the $meta_value parameter is set. In this case, you delete the "If Code Could Talk" meta value by setting it as the $meta_value parameter.

<?php

delete_post_meta( 100, 'favorite_song', 'If Code Could Talk' );

?>

The preceding usage of delete_post_meta() deletes a single meta value. If you want to delete all the meta values for the favorite_song meta key for this post, leave the $meta_value parameter empty.

<?php

delete_post_meta( 100, 'favorite_song' );

?>

In your plugin file, you use the register_taxonomy() function to create a new taxonomy. It accepts three parameters.

<?php
register_taxonomy( $taxonomy, $object_type, $args );
?>

The $args parameter is what enables you to customize your taxonomies. The following descriptions of each argument can give you an understanding of how you can set up taxonomies to your needs.

Now that you've reviewed the register_taxonomy() parameters and arguments in detail, it's time to use that knowledge to create new taxonomies.

In the next example, you create two new taxonomies, album_artist and album_genre, for the "music album" post type that you created in the first part of this chapter. The artist taxonomy is nonhierarchical and the genre taxonomy is hierarchical.

<?php

/* Set up the taxonomies. */
add_action( 'init', 'boj_music_collection_register_taxonomies' );

/* Registers taxonomies. */
function boj_music_collection_register_taxonomies() {

    /* Set up the artist taxonomy arguments. */
    $artist_args = array(

'hierarchical' => false,
        'query_var' => 'album_artist',
        'show_tagcloud' => true,
        'rewrite' => array(
            'slug' => 'music/artists',
            'with_front' => false
        ),
        'labels' => array(
            'name' => 'Artists',
            'singular_name' => 'Artist',
            'edit_item' => 'Edit Artist',
            'update_item' => 'Update Artist',
            'add_new_item' => 'Add New Artist',
            'new_item_name' => 'New Artist Name',
            'all_items' => 'All Artists',
            'search_items' => 'Search Artists',
            'popular_items' => 'Popular Artists',
            'separate_items_with_commas' => 'Separate artists with commas',
            'add_or_remove_items' => 'Add or remove artists',
            'choose_from_most_used' => 'Choose from the most popular artists',
        ),
    );

    /* Set up the genre taxonomy arguments. */
    $genre_args = array(
        'hierarchical' => true,
        'query_var' => 'album_genre',
        'show_tagcloud' => true,
        'rewrite' => array(
            'slug' => 'music/genres',
            'with_front' => false
        ),
        'labels' => array(
            'name' => 'Genres',
            'singular_name' => 'Genre',
            'edit_item' => 'Edit Genre',
            'update_item' => 'Update Genre',
            'add_new_item' => 'Add New Genre',
            'new_item_name' => 'New Genre Name',
            'all_items' => 'All Genres',
            'search_items' => 'Search Genres',
            'parent_item' => 'Parent Genre',
            'parent_item_colon' => 'Parent Genre:',
        ),
    );

    /* Register the album artist taxonomy. */
    register_taxonomy( 'album_artist', array( 'music_album' ), $artist_args );

    /* Register the album genre taxonomy. */
    register_taxonomy( 'album_genre', array( 'music_album' ), $genre_args );
}

?>

Code snippet boj-music-collection-taxonomies.php

After you add the preceding code, you'll be presented with two new submenu items under the Albums menu item in the admin, labeled Artists and Genres. You also have two new meta boxes for assigning artists and genres to individual albums, as shown in Figure 11-5.

Figure 11.5. FIGURE 11-5

This function enables you to set taxonomy to any object type, which will typically be a specific post type. It accepts two parameters and returns true if successful and false if not.

<?php
register_taxonomy_for_object_type( $taxonomy, $object_type );
?>

One example of setting a specific taxonomy to a post type is giving the "page" post type the "post tag" taxonomy, which is usually used for the "post" post type. Using the following code, you can add this taxonomy to it.

<?php

/* Adds the post_tag taxonomy to the page post type. */
register_taxonomy_for_object_type( 'post_tag', 'page' );

?>

The get_taxonomy() function accepts a single parameter of $taxonomy, which should be the name of the taxonomy. It returns the taxonomy object.

<?php
get_taxonomy( $taxonomy );
?>

Suppose you need to display the singular_name label of the album_genre taxonomy that you registered. You'd use the following code to get the taxonomy object and display this label.

<?php

/* Get the genre taxonomy object. */
$genre = get_taxonomy( 'album_genre' );

/* Display the singular name of the genre taxonomy. */
echo $genre->labels->singular_name;

?>

The the_terms() function returns a formatted list of terms for a given taxonomy of a specific post. It accepts five parameters.

<?php
the_terms( $id, $taxonomy, $before, $sep, $after );
?>

The the_terms() function is a wrapper function for get_the_term_list(). The former function displays the list of terms for the taxonomy, and the latter returns them for use in PHP.

Now revisit the custom shortcode you created in the section on custom post types in which you listed posts of the music album post type. This time, use the get_the_term_list() function to add each album's artist(s) and genre(s) to the list.

You can add the following two lines of code to your shortcode function for displaying the album artist(s) and genre(s):

$output .= get_the_term_list( get_the_ID(), 'album_artist', 'Artist: ', ', ', ' ' );

$output .= get_the_term_list( get_the_ID(), 'album_genre', 'Genre: ', ', ', ' ' );

The following is what the code should now look like to display the album_artist and album_genre taxonomy terms:

<?php

add_action( 'init', 'boj_music_album_register_shortcodes' );

function boj_music_album_register_shortcodes() {

    /* Register the [music_albums] shortcode. */

add_shortcode( 'music_albums', 'boj_music_albums_shortcode' );
}

function boj_music_albums_shortcode() {

    /* Query albums from the database. */
    $loop = new WP_Query(
        array(
            'post_type' => 'music_album',
            'orderby' => 'title',
            'order' => 'ASC',
            'posts_per_page' => −1,
        )
    );

    /* Check if any albums were returned. */
    if ( $loop->have_posts() ) {

        /* Open an unordered list. */
        $output = '<ul class="music-collection">';

        /* Loop through the albums (The Loop). */
        while ( $loop->have_posts() ) {

            $loop->the_post();

            /* Display the album title. */
            $output .= the_title(
                '<li><a href="' . get_permalink() . '">',
                '</a></li>',
                false
            );

            /* Insert a line break. */
            $output .= '<br />';

            /* Show the album artist. */
            $output .= get_the_term_list( get_the_ID(), 'album_artist',
                'Artist: ', ', ', ' ' );

            /* Show the album genre. */
            $output .= get_the_term_list( get_the_ID(), 'album_genre',
                'Genre: ', ', ', ' ' );

        }

        /* Close the unordered list. */
        $output .= '</ul>';
    }

    /* If no albums were found. */
    else {
        $output = '<p>No albums have been published.';
    }

    /* Return the music albums list. */

return $output;
}

?>

Code snippet boj-post-type-taxonomy-loop.php

This code can give you a list of items similar to the list shown in Figure 11-6.

Figure 11.6. FIGURE 11-6

The taxonomy_exists() function checks if a taxonomy has been registered with WordPress. It accepts a single parameter of $taxonomy, which should be the name of the taxonomy you're checking.

<?php
taxonomy_exists( $taxonomy );
?>

Suppose you wanted to check if the artist taxonomy you created earlier exists. Using the following code, you can display a custom message based on the return value of the taxonomy_exists() function.

<?php

/* If the album artist taxonomy exists. */
if ( taxonomy_exists( 'album_artist' ) ) {

    echo 'The "artist" taxonomy is registered.';
}

/* If the album artist taxonomy doesn't exist. */
else {

    echo 'The "artist" taxonomy is not registered.';
}

?>

The is_taxonomy_hierarchical() function determines if a given taxonomy is hierarchical. It accepts a single parameter of $taxonomy, which should be the name of the taxonomy.

<?php
is_taxonomy_hierarchical( $taxonomy );
?>

The album genre taxonomy you created is hierarchical, but the album artist taxonomy is not hierarchical. Now create an array of taxonomy names and loop through each, creating a list of messages to determine whether each is hierarchical.

<?php

/* Create an array of custom taxonomies. */
$taxonomies = array(
    'album_artist',
    'album_genre'
);

/* Open an unordered list. */
echo '<ul>';

/* Loop through the array of taxonomies. */
foreach ( $taxonomies as $tax ) {

    /* If the taxonomy is hierarchical. */
    if ( is_taxonomy_hierarchical( $tax ) ) {
        echo '<li>The ' . $tax . ' taxonomy is hierarchical.</li>';
    }

    /* If the taxonomy is non-hierarchical. */
    else {
        echo '<li>The ' . $tax . ' taxonomy is non-hierarchical.</li>';
    }
}

/* Close the unordered list. */
echo '</ul>';

?>

The is_tax() function determines if a site visitor is on a term archive page on the frontend of the site. When using no parameters, it simply checks if the visitor is on any taxonomy archive. However, you may optionally set either parameter for a more specific check.

<?php
is_tax( $taxonomy, $term );
?>

With the next snippet of code, you display up to three different messages depending on which conditions are true. You first check to see if a visitor is on a taxonomy term archive. You then check for a specific taxonomy: genre. Then, you check if the archive page is in the blues genre.

<?php

/* If on a taxonomy term archive page. */
if ( is_tax() ) {
    echo 'You are viewing a term archive.';
}

/* If viewing a term archive for the album genre taxonomy. */
if ( is_tax( 'album_genre' ) ) {
    echo 'You are viewing a term archive for the genre taxonomy.';
}

/* If viewing the blues archive for the album genre taxonomy. */
if ( is_tax( 'album_genre', 'blues' ) ) {
    echo 'You are viewing the blues archive for the genre taxonomy.';
}

?>