Knowledgebase

Check the knowledge base articles to get a jump start on your integrations, modifications, and all around user questions. If you don’t find what you’re looking for hit the help desk.

Search Knowledgebase

Abstract Post Types

While The Events Calendar provides the Organizer and Venue post types by default, you may want to have another post type to associate with events, like “Speakers” or “Instructors”. Like Organizers, you would be able to add existing Instructors to events, or create new Instructors while creating events.

Doing this before version 4.2 of The Events Calendar meant lots of extra custom coding, but since 4.2 you can add or remove event-related post types with just a few simple filters. This framework for relating post types to events is called the “Abstract Post Types” system, and in this guide, we’ll explore some of the main things this system allows you do to.


⚠️ Please Note: We are not able to help with custom coding, nor can we provide troubleshooting help for custom code you’ve written. These facts are elaborated upon here and here. This guide is simply a starting place for learning about some of the advanced features of our plugin code.


In this Guide


Getting Started

One thing worth clarifying before we get to the rest of the guide is that our Abstract Post Types system does not create the custom post types you want to have on Events—it only links existing post types.

For example, the rest of the guide will refer to custom post types like “Instructors”—in example code below, it’s assumed that the post types referred to have already been created on the hypothetical site in question.

So the first step in adding custom post types to events is to create the post types in the first place so that they exist on your site and can be linked to events. You can learn more about custom post types and how to create them on the WordPress Codex here.

🔔 Tip: You should specify a singular_name_lowercase parameter in your registration of the post type—this will help reduce the risk of PHP notices about undefined indexes in the post type labels. So instead of just this, for example:

register_post_type( 'instructors', array(
    'labels'  => array(
        'name'                    => 'Instructors',
        'singular_name'           => 'Instructor',
    ),
    'public' => true
));

Register your post type with a specified singular_name_lowercase parameter like this:

register_post_type( 'instructors', array(
    'labels'  => array(
        'name'                    => 'Instructors',
        'singular_name'           => 'Instructor',
        'singular_name_lowercase' => 'instructor'
    ),
    'public' => true
));

Adding Custom Post Types to Events

To make a post type available to Events, all you need to do is add code like the following on your site:

function tribe_link_instructors_to_events() {
	tribe_register_linked_post_type( 'instructors' );
}

add_action( 'init', 'tribe_link_instructors_to_events' );

☝️ This block of code adds a post type called “Instructors” to events. The result is shown in the following screenshot:

The Instructors Post Type Added to Events

The “Instructors” post type successfully added to Events, with the same capabilities as the default Organizers and Venues types.

Just like you can add one Organizer to many Events, and create new Organizers from within the event creation screen, you can now add one Instructor to many Events and create new Instructors from within the event creation screen.


Removing Custom Post Types from Events

If you have a custom post type like Instructors linked to Events using code shown above, and want to un-link the post type from Events without damaging existing data or the existing post type object, you can use a function called tribe_deregister_linked_post_type:

function tribe_remove_instructors_from_events() {
	tribe_deregister_linked_post_type( 'instructors' );
}

add_action( 'init', 'tribe_remove_instructors_from_events' );

Removing Default Post Types from Events

If you want to remove a default post type from events—either Organizers or Venues—then a few more lines of code are required, but the process is still simple. You would add a snippet like the following:

function tribe_remove_organizers_from_events( $default_types ) {

	if ( ! is_array( $default_types ) || empty( $default_types ) ) {
		return $default_types;
	}

	if ( ( $key = array_search( 'tribe_organizer', $default_types ) ) !== false ) {
		unset( $default_types[ $key ] );
	}

	return $default_types;
}

add_filter( 'tribe_events_register_default_linked_post_types', 'tribe_remove_organizers_from_events' );

☝️ In this code you’ll notice text that reads 'tribe_organizer'. If you want to remove Venues instead of Organizers, change this text to 'tribe_venue'.

Here is a screenshot showing the section of the edit-event screen with our previously-added Instructors post type available, but with the default Organizers post type removed:

The Organizers Type Removed from Events

The default Organizers post type successfully removed from Events, while the custom Instructors post type remains.


Customizing Linked Post Types

When adding custom types, you use the tribe_register_linked_post_type() function. You can supply two arguments to this function. The first argument is required, and is the slug of the post type you want to link to Events. In the snippet above, for example, this argument was 'instructors'.

The second argument you can supply to the function is an array of options about how the post types should relate. The available options are:

  • name
  • singular_name
    • The singular name of the post type, if the post type’s “name” label is in plural form (which is common). Must be a string value.
    • Will default to the “Singular Name” label specified in the registration of the post type.
  • singular_name_lowercase
    • The singular name of the post type in lowercase format, for use in sentences or phrases. This is especially useful for any labels that might have multiple words. For example: You may not need to specify this option if your post type is just “Instructors”, but if you have “Main Instructors” and “Assistant Instructors” it may be useful for both types. Must be a string value.
    • Will default to the “Singular Name” label specified in the registration of the post type.
  • allow_multiple
    • Whether to allow multiple items of the linked post type to be associated to events. The default Organizers type is an example of having allow_multiple set to true, while the default Venues type is an example of having allow_multiple set to false. Only accepts true or false.
    • Defaults to true.
  • allow_creation
    • Whether to allow creation of new items of the linked post type within the event-creation screen. This is true for both the default Organizers type and the default Venues type. Only accepts true or false.
    • Defaults to false.

As an example of using these arguments, let’s say you wanted to link Instructors to Events, with the following details:

  • You want to ensure that only one Instructor can be added to any event (not multiple).
  • You want to ensure that it is possible to create new Instructors from right within the event-creation screen.
  • You want to ensure that the label “Instructor” is always capitalized as a proper noun, given the context of your organization.

To do all of this, you would modify the example snippet above to look like the following:

function tribe_link_instructors_to_events() {
	tribe_register_linked_post_type( 'instructors', array(
            'singular_name'           => 'Instructor',
            'singular_name_lowercase' => 'Instructor',
            'allow_multiple'          => false,
            'allow_creation'          => true
        ) );
}

add_action( 'init', 'tribe_link_instructors_to_events' );

Customizing Linked Post Type Forms

Once a custom post type is linked to events, you’ll see a form for adding or creating this post type in the wp-admin edit screen for events. By default, the existing form structure of Organizers/Venues is used. For example, this screenshot shows a default form generated for a linked post type called “instructors”:

screen-shot-2016-11-17-at-4-25-54-pm

If you would like to modify the form for a linked post type, you’ll need two hooks:

  • tribe_events_linked_post_new_form
    • An action hook that lets you add new form elements to the edit/creation form for a specific linked post type.
  • tribe_events_linked_post_create_{$post_type}
    • A filter hook that lets you handle the saving and updating of that form data.

Those two hooks give you the ability to change the form and react to the data in some way upon submission.

To see example code of how to add a “Website” field to the Instructors form (so that Instructors each have a “Name” and “Website” field), check out this GitHub Gist for some inspiration → https://git.io/vX7Cx

Writing the custom saving/updating methods so that the data is saved is an advanced process, but the example code above will hopefully help you get the ball rolling. The code in the above Gist mentions other methods and functions within The Events Calendar that are good example functions you can base your own functions on.


Advanced Functions and Learning More

There is an array of functions related to Abstract Post Types, all of which can be found in this file within The Events Calendar:

the-events-calendar/src/functions/advanced-functions/linked-posts.php

All of the available functions are as follows:

  • tribe_register_linked_post_type
  • tribe_deregister_linked_post_type
  • tribe_get_linked_posts
  • tribe_has_linked_posts
  • tribe_has_linked_posts_by_post_type
  • tribe_get_linked_post_types
  • tribe_has_linked_post_types
  • tribe_is_linked_post_type
  • tribe_link_post
  • tribe_unlink_post
  • tribe_get_linked_post_container
  • tribe_get_linked_post_id_field_index
  • tribe_get_linked_post_name_field_index

☝️ Dive into the code for more insight and information about these functions, and before you tinker—with Abstract Post Types or any feature of plugin code—be sure to make backups of your site and database!