…or: How I Learned to Stop Worrying and Love the Custom Post Type
WG_Custom_Post_Type is a library created to simplify common tasks when developing Custom Post Types (CPT:s) for WordPress.
Along with the basic functions for creating the CPT:s and adding taxonomies and meta boxes, you are handed some methods for playing with hygiene factors at the wp-admin side such as menu icons and contextual help.
- Speed up your WordPress CPT development with a simplified interface
- Say goodbye to all those action and filter callbacks that uglifies your code
- Make the administration more user friendly with icons and help tabs
- Enjoy a chained interface
While trying to make the interface as easy as possible for the developer, our aim is to still keep as close to the WordPress way of doing things as possible. Why you ask? Simple: It's WordPress you walk, and WordPress you shall talk.
-
The library wg-meta-box is used for adding meta boxes.
wg-meta-boxis added as a submodule to this repository, see below on how to initialize it. -
The plugin Multiple Post Thumbnails is used for adding multiple featured images. You need to install and activate the plugin in order to use this functionality.
- Getting started
- Example: Creating your first custom post type
- The Basics
- Customizing the admin screen
- Contextual help using help tabs
- Changelog
- License (MIT)
To get started using this library, either clone it or download the zip and unpack it into the folder of choice.
A recommended place would be to put the library in a lib/-folder within your theme or plugin.
git clone git@github.com:Webbgaraget/wg-custom-post-type.git
If you're interested in adding meta boxes for your CPT (you probably are), initialize the submodule with the following command (ran from the root of the newly cloned git repo)
git submodule update --init
Unpack the zip file where you want the library to reside. Then head on over to wg-meta-box and download and unpack that library into the wg-custom-post-type/lib/wg-meta-box folder.
Include the php file class-wg-custom-post-type.php residing in the recently cloned/unzipped folder.
require_once( 'lib/wg-custom-post-type/class-wg-custom-post-type.php' );
This is a simple example on how to create a CPT for Events:
// Post type labels
$labels = array(
'name' => 'Events',
'singular_name' => 'Event',
'all_items' => 'All Events',
'add_new_item' => 'Add Event',
'edit_item' => 'Edit Event',
'new_item' => 'New Event',
'view_item' => 'View Event',
'search_items' => 'Search Events',
'not_found' => 'No event found',
'not_found_in_trash' => 'No event found in trash',
);
// Create the CPT
$event = new WG_Custom_Post_Type(
'event',
array(
'capability_type' => 'page',
'labels' => $labels,
'hierarchial' => true,
'supports' => array( 'title' ),
)
);
// Create a taxonomy for event types and a meta box for event information
$event
->add_taxonomy(
'event-type',
array(
'labels' => array(
'name' => 'Event types',
'singular_name' => 'Event type',
'add_new_item' => 'Add new type',
'edit_item' => 'Edit type',
'update_item' => 'Update type',
),
),
true, // We want an admin column for this taxonomy
true // We want the admin list to be filterable by this taxonomy
)
->add_meta_box(
'event-info',
'Event information',
array(
'date' => array(
'type' => 'date',
'label' => 'Date',
),
'time' => array(
'type' => 'text',
'label' => 'Time',
),
)
);
Note how the labels and options array arguments are identical to the ones you usually pass to register_post_type() and register_taxonomy().
__construct( $post_type, $args, $label_check = 'require_labels' )
-
$post_type – Name of the post type. (string, required)
-
$args – Options array as expected by WP:s register_post_type(). (array, required)
-
$label_check – Flag deciding whether the
labelsoption should be checked for required labels. (string, optional, default: 'require_labels')
Creates a new custom post type with the given name $post_type and the given arguments $args. The library by default checks the given $args array to see that all basic post type labels are set. To disable this check, pass 'disabled' as the third parameter.
An exception is thrown if the $post_type is one of the reserved post types or if it's longer than 20 characters.
Return: null
add_taxonomy( $id, $args, $admin_column = null, $admin_filter = false )
-
$id – Internal ID of the taxonomy. (string, required)
-
$args – Options for the taxonomy as expected in the third argument of WP:s register_taxonomy(). (array, required)
-
$admin_column – Options for displaying the taxonomy terms as a column in the list of posts for the current CPT. (array|boolean, optional)
-
$admin_filter – Whether the admin list of this post type should be filterable by this taxonomy. (boolean, optional)
Adds a taxonomy to the post type.
An exception is thrown if the $id is one of the reserved terms.
Admin column
Pass an array as the last parameter to set options for displaying the taxonomy terms in the admin table for the current post type. Available options are:
- 'display_after' – ID of the column this column should be positioned after. (string, optional, default: 'title')
- 'label' - Column heading label. (string, optional, default: the name of the taxonomy)
- 'sortable' - Flag determining if the list should be sortable on this column. (boolean, optional, default: true)
Pass true as the $admin_column parameter to use the default column options mentioned above.
Admin filter
If the $admin_filter parameter is set to true, a selectbox is added to the admin list to let the user filter by this taxonomy.
Return: $this – For chaining.
add_existing_taxonomy( $taxonomy_id, $admin_filter = false )
- $taxonomy_id – Internal ID of the taxonomy. (string, required)
- $admin_filter – Whether the admin list of this post type should be filterable by this taxonomy. (boolean, optional)
Adds a previously registered taxonomy to this post type.
If the $admin_filter parameter is true, the admin list for the post type
will be filterable by the given taxonomy.
Return: $this – For chaining.
add_existing_taxonomies( $taxonomy_ids, $admin_filter = false )
- $taxonomy_ids – Array of internal ID:s of the taxonomies to be added. (array, required)
- $admin_filter – Whether the admin list of this post type should be filterable by these taxonomies. (boolean, optional)
Adds multiple previously registered taxonomies to this post type
If the $admin_filter parameter is true, the admin list for the post type
will be filterable by the given taxonomies.
Return: $this – For chaining.
add_meta_box( $id, $title, $fields, $context = 'advanced', $priority = 'default', $callback_args = null )
This method uses the method WGMetaBox::add_meta_box() to create the meta box.
See information about the arguments in the documentation for wg-meta-box.
Return: $this – For chaining.
add_featured_image( $id, $label, array $size_attr = null )
-
$id – Internal ID of the image (string, required)
-
$label – Label to be displayed in the admin area (string, required)
-
$size_attr – Optional array of attributes for a thumbnail size to be registered. See above for info. (array, optional, default: null)
Adds an additional "featured image" using the plugin Multiple Post Thumbnails.
The (optional) $size_attr-array should, if given, have three or four elements corresponding to the arguments expected by WP:s add_image_size().
Return: $this – For chaining.
set_title_placeholder( $placeholder )
- $placeholder - The text to set as placeholder (string, required)
Sets the placeholder in the "Title" input field when adding or editing an item of this CPT.
Return: $this – For chaining.
set_menu_icon( $icon_url )
- $icon_url - Full URL for the icon sprite (string, required)
Sets the admin menu icon for this CPT. This method expects an icon sprite as described/developed by Randy Jensen.
Return: $this – For chaining.
set_screen_icon( $icon_url )
- $icon_url - Full URL for the icon (string, required)
Sets the screen icon for this CPT. The screen icon is shown in the upper left corner of the 'edit' and 'add' screens of the CPT.
Return: $this – For chaining.
Help tabs provides the user with contextual help on the screens for this CPT. The help tabs can be found by clicking the "Help" dropdown button next to "Screen options".
Along with the help tabs, there's a sidebar in the contextual help that for example can be used to provide links to more information.
add_help_tab( array $tab )
- $tab - Options for the tab as excpected by WP_Screen::add_help_tab() (array, reqruired)
Adds a help tab to the screens for this CPT. For information on the $tab argument, see the documentation for WP_Screen::add_help_tab()
Return: $this – For chaining.
add_help_tabs( array $tabs )
- $tabs - An array of tab options (see
add_help_tab()). (array, required)
Adds multiple help tabs to the screens for this CPT. See add_help_tab().
Return: $this – For chaining.
set_help_sidebar( $content )
- $content - HTML markup for the help sidebar. (string, required)
Sets the content for the help sidebar for this CPT
Return: $this – For chaining.
- Upgrades WGMetaBox to v0.5.5
- Adds methods for adding previously registered taxonomies (add_existing_taxonomy()).
- Adds possibility to have the post type admin list filterable by taxonomies.
- Some modifications to this README (adds TOC for example)
- Version bumped to v0.5
- Upgraded WGMetaBox to v0.5.4
- Upgraded to use latest WGMetaBox.
- Adds ability to pass $callback_args to add_meta_box().
- Throwing exception when $post_type ID is longer than 20 characters. Fixes #3
- Added support for admin columns. Fixes #1
- Throwing exception if reserved names for CPT or taxonomies are used. Fixes #2
- This document was created
- The library was modified to adhere more closely (but not fully) to WordPress Coding Standards
Copyright (c) 2012 Webbgaraget AB http://www.webbgaraget.se/
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.