Post Types

About Post Types

The post type API lets you extend the types of content available in WordPress.

Each type of content, or “post type”, should have a single responsibility. For example, “Post” and “Page” are post types built into WordPress and have separate responsibilities. “Post” is simply responsible for blog posts and “Page” for standard web pages.

“Post” is responsible for only one thing; blog posts. If you want to add a “Book”, type of content, to WordPress you don’t want to cheat and add a category of “Books” to a blog post. This will break single responsibility. Books are not blog posts. You want to create a post type called “Book” for your books.

Getting Started

To get started with post types using TypeRocket read these docs.

  1. Post Types: Making
  2. Post Types: Theming
  3. Post Types: Secured

Adding a Post Type

For terminology's sake, you “register” a “post type” when you want to add a new type of content. With TypeRocket 3.0 you add post types without having to understand the inner-workings of WordPress.

To register a “Book” post type in WordPress you only need one line of code.

tr_post_type('Book');

This one line of code adds the post type to the admin, sets all the correct labels in the navigation and applicable places, and implements the required WordPress hooks. This would normally take many many lines of code.

Note: you do not need to use any WordPress hook with TypeRocket here.

TypeRocket takes Post Types to the next level. When you create a post type with TypeRocket you are instancing a special PHP object that can do much more.

Let us assign the “Book” post type to a variable to see these features.

$book = tr_post_type('Book');

Custom plural form

In some cases, you will not want TypeRocket to manage the grammar for the post types plural form.

You can set your own by supplying it as the second argument when creating the post type.

tr_post_type('Book', 'Books');

For example when you have other ideas altogether.

tr_post_type('Person', 'Team');

Modify Post Type

To modify an existing post type when using tr_post_type pass the post type ID/name as the only value. If editing a built-in post type no hooks are required.

tr_post_type('post')->setIcon('book');

If editing any other post type you need to use the init action and call the register() method. Also, you may need to set the priority of the init action to a higher number for overriding to work.

$priority = 11;

add_action('init', function() {
    $product = tr_post_type('product')->setIcon('book');
    $product->register();
}, $priority);

Note: When overriding a post type created by a plugin that plugin may have its own code that TypeRocket can not override due to how that plugin works. For example, in WooCommerce you can not override the post type icon because WooCommerce implements its own CSS code and the TypeRocket CSS does not have more specificity than WooCommerce for the icon design.

Setting an Icon

To set a custom menu icon use the setIcon() method.

$book->setIcon('book');

Note: Browse the “dev” TypeRocket plugin page in the admin under the "Icons" tab to see the list of options.

Title Placeholder Text

By default "Enter title here" is the placeholder text of every post type. You can change this with TypeRocket, without hooks, by using the setTitlePlaceholder() method.

$book->setTitlePlaceholder( 'Enter book title here' );

Forms and Fields

There are 4 place to add custom content within the <form> element for each post type. You can open up these sections with 4 different methods: setTitleForm() for after the title, setTopForm() for before the title, setBottomForm() for the very bottom and setEditorForm() for after the editor.

Take a look at opening up a content section after the title area.

$book->setTitleForm();

When TR_DEBUG is set to true, as it is by default, TypeRocket shows you where the section was opened and suggests a function to be used to add content.

Note: this applies to all 4 methods.

setTitleForm Debug

Suggested function

By creating the suggested function you are able to start printing content to the screen.

function add_form_content_book_title() {
    echo "<h2>My Book Content</h2>";
}

Callback

Alternatively, when setting a form section you can supply an anonymous function as a callback to do the same.

Take a look at adding content after the editor using a callback.

$book->setEditorForm(function() {
    echo "<h2>My Book Content</h2>";
});

Fields

Adding fields to a post type can be done with the form content methods.

$book->setEditorForm(function() {
    $form = tr_form();
    echo $form->text('Custom Field Name');
});

Set Archive Slug

To set the slug for the custom post type and change the default use the method setSlug().

$book->setSlug('library');

Any time you add a new post type or change the slug you need to flush the WordPress rewrite rules.

Note: Flush rewrites by clicking "Settings > Permalinks > Save Changes".

Setting Admin Only

Sometimes you don't want post types to have an archive or single pages. You can use the setAdminOnly() method to keep a post type out of the front-end.

Take a look at making a new post type that is admin only.

tr_post_type('Store Manager')->setAdminOnly();

Set Archive Page Limit

You can set the number of posts that appear on the post types archive page using the setArchivePostsPerPage() method.

The setArchivePostsPerPage() takes one aurgument:

  • limit - An integer -1 for all posts and any positive number for the specific limt.
$member = tr_post_type('Member');
$member->setArchivePostsPerPage(-1);

Disable Archive Page

you can disable the archive page on a post type using the disableArchivePage() method

$member->disableArchivePage();

Apply: Taxonomy and Meta Boxes

Adding Registrable (PostType, Taxonomy, MetaBox) object instances like a Taxonomy or MetaBox is extremely simple when using the TypeRocket post type object.

To add a Taxonomy to a post type instance a Taxonomy and then use the apply() method.

$publisher = tr_taxonomy('Publisher');
$book->apply($publisher);

To add a MetaBox it is just as simple.

$bookDetails = tr_meta_box('Book Details');
$book->apply($bookDetails);

Get Applied Registrable Objects

To see what objects have been applied use the getApplied() method.

$uses = $book->getApplied();

Advanced usage of apply

You can also apply as many Registrable objects as you like using each as a new parameter.

$publisher = tr_taxonomy('Publisher');
$bookDetails = tr_meta_box('Book Details');
$book->apply($bookDetails, $publisher);

Also, an array. You can decide.

$publisher = tr_taxonomy('Publisher');
$bookDetails = tr_meta_box('Book Details');
$book->apply( [$bookDetails, $publisher] );

Applying to Existing Taxonomies

To apply a taxonomy that already exists use the addTaxonomy() method and pass the taxonomies ID as a parameter.

$book->addTaxonomy('categoy');
$book->addTaxonomy('post_tag');

Setting and Getting the ID

The ID is used to specify the name that WordPress associates with your post types. It is also registered under the ID. When you register "Book" with TypeRocket the id is set to "book".

You can change the ID using the setId() method.

$book->setId('library_book');

Get the ID

$bookId = $book->getId();

Arguments

There are 5 methods for dealing with arguments. Arguments are used when the post type is being registered. All arguments can be found in the WordPress codex.

These methods are: getArguments(), setArguments(), getArgument(), setArgument() and removeArgument().

  1. getArguments() returns the full array of arguments.
  2. setArguments() takes an array of arguments.
  3. getArgument() return an argument by its key.
  4. setArgument() sets an argument by a key.
  5. removeArgument() removes an argument by its key.

Take a look at using all the methods without affecting the already set values.

$args = $book->getArguments();
$args = array_merge( $args, [ 'public' => true ] );
$book->setArguments( $args );
$public = $book->getArgument( 'public' );
$book->removeArgument( 'public' );
$book->setArgument( 'public', $public );

Add Table Columns

You can add and remove columns from the admin post type index page table using TypeRocket. Here we will use a post type of person for our examples. Also, we will have one custom field so we can add it in a custom table column.

$person = tr_post_type('Person', 'People');
$person->setTitleForm(function() {
    $form = tr_form();
    echo $form->text('Job Title');
    echo $form->image('Photo');
});

Add Column

To add a column it needs to match the custom field's name.

$person->addColumn('Job Title');

If the custom field is grouped then you need to use the base group name.

The addColum() method takes up to 5 aurguments.

  1. field - The name of the field to add. You can use any string format but lowercase letters and _ (underscores) should be used for precision.
  2. sort - The column is sortable true or false.
  3. label - The tabled header column label.
  4. callback - The value to be displayed in the column.
  5. order_by - How the field should be ordered 'string' or 'number'.

Here is an advanced example:

$person->addColumn('photo', true, 'Photo', function($value) {
    echo wp_get_attachment_image($value, 'thumbnail');
}, 'number');

Remove Column

You can remove a column using the removeColumn() method. The removeColumn() method takes 1 string argument and it needs to match the field's name.

$person->removeColumn('date');

Set Primary Column

In some cases, you will not have a title column and still want the "Edit | Quick Edit | Trash | View" controls to be used. To do this you will need to set a new primary column.

$person->setPrimaryColumn('job_title');

REST API

You can also set the WordPress post types REST API resource location using the setRest() method.

$team->setRest('people');

Forcing Root URLs

The standard rewrite rules for custom post types is /{post-type}/{post-name}. However, you can set a post types custom URL to the site's root by using the setRootOnly() method; doing this will change the post types URLs from /{post-type}/{post-name} to /{post-name}. Further, TypeRocket makes sure URLs are not duplicated for any other post type using the site's root.

  • Disabled the archive page.
  • Forces the use of the site's root.
  • Forces a unique post_name for URLs.
$team->setRootOnly();

Gutenburg

Force disable or enable Gutenberg for a post type use the enableGutenberg() or forceDisableGutenberg() methods.

If you have edited your app.php config file with your own custom Gutenberg feature settings your config settings will take priority over enableGutenberg() and forceDisableGutenberg(). To take advantage of these new features be sure to keep your Gutenberg config feature set to true.

Enable

$team->enableGutenberg()

Disable

$team->forceDisableGutenberg()

Add Support

Add support for a WordPress feature:

  • title: The post's title.
  • editor: Gutenburg or the classic editor.
  • author: Author metabox.
  • thumbnail: Add to get the featured image; the current theme must also support post-thumbnails.
  • excerpt: Excerpt metabox.
  • trackbacks: Trackbacks metabox.
  • custom-fields: WordPress powered custom fields metabox; not required for TypeRocket custom fields.
  • comments: Enabled comments.
  • revisions: Save revisions.
  • page-attributes: Adds menu order; optionally, hierarchical must be true to show parent select box.
  • post-formats: Add post formats.
$symbol = tr_post_type('Symbol')
$symbol->addSupport('comments');

Registration Hook: Action

WordPress gives you a hook when a post type is registered. This makes registering post types developer-friendly. This hook exists to let plugin developers limit post type conflicts.

You can modify the registration if you need to from here.

add_action('registered_post_type', function($postType, $args) {}, 10, 2);