Post Type

Intro

Post Types are one of the main data types in WordPress and the "Post Type" location allows you to associate fields with them. If you are not familiar with post types, please read the Codex Article about them. Some of the built-in examples for post types in WordPress include Pages and Posts.

Custom Post Types mimic the functionality of the build-in post types, but allow developers to register their own data types. If you are interested in creating additional custom post types, you can check Ultimate Post Types. It is an add-on of Ultimate Fields, which allows you to create post types through the WordPress administration area.

When you associate a container with a post type, you will get an additional meta box on the editing screen of that post type, similar to the "Categories", "Tags" and other built-in boxes. In some descriptions below, mentioning "Meta Box" will refer to a post type-associated container.

Usage through the interface

To add fields to a post type with the the Administration Interface, please follow these steps:

1. If you are not on the "Add Container" screen already, locate the "Ultimate Fields" section in the administration area and click the "Add New" button on the top (next to the "Containers" title).
2. Locate the "Locations" box.
3. Click "Post Type" from the bottom row.
4. Select whether you want to display fields for a particular post or page, or you want to select rules manually in order to display the fields for all posts, matching a certain criteria.
5. Adjust all other needed options. All of them are described further down this page.

Usage through PHP

The post type location in Ultimate Fields is handled by the Ultimate_Fields\Location\Post_Type class. In order to use it, you can either create the new location object manually or let the container do it for you.

The constructor of the class looks like this:

public function __construct( $post_type = null, $args = array() )

• $post_type is optional, but recommended. You can either pass a single post type's slug as a string, or an array of post type slugs.
• $args is an array, which allows you to set arguments without having to explicitly call the particular setter. For example, you can pass 'templates' => 'template-home.php' instead of calling ->set_templates( 'template-home.php' )

Manual creation

Create a new location by using the new keyword and assign it to the container through the add_location() method.

use Ultimate_Fields\Container;
use Ultimate_Fields\Location;

$container = Container::create( 'homepage-settings' );

// Create a new location and add definitions to it
$location = Location::create( 'post_type', 'page' );
$location->set_templates( 'template-home.php' );

// Once the location has been fully set up, add it to the container
$container->add_location( $location );

Do not forget to use the correct namespace for the location class!

Automatic creation

You can also let the container create the location for you by providing the "post_type" string as the first parameter to add_location(). The rest of the parameters are the same as for the constructor of the location class.

use Ultimate_Fields\Container;

Container::create( 'homepage-settings' )
	->add_location( 'post_type', 'page', array(
		'templates' => 'template-home.php'
	));

This method allows you to use method chaining and shortens the syntax, in order to make the code more readable.

Data retrival

To retrieve the values of fields, associated with the Post Type location, you can use the following formats of the $type parameter of all *_value functions:

• Empty (null) will attempt to load a value, associated with the current post. Please make sure that you have already called the_post() first, otherwise Ultimate Fields might not be able to locate the needed post (ex. get_value( 'subtitle' )).
• A number (int), containing the post ID (ex. get_value( 'subtitle', 5 ))
• post_, followed by the ID of the post that you need (ex. get_value( 'subtitle', 'post_5' ))
• The slug of the post type, an underscore and the post ID as a string (ex. get_value( 'subtitle', 'event_8 )).

Examples:

<!-- Skip the identifier -->
<h2><?php the_value( 'subtitle' ) ?></h2>

<!-- Use an ID -->
<?php
$homepage_id = get_option( 'page_on_front' );
$homepage_subtitle = get_value( 'subtitle', $homepage_id );
?>

Options

Post Type

Post Type locations can be associated with particular post type, for example "Page" or "Post".

• If you choose to Show the container based on a particular post or page, it is not necessary to select a post type, since it will be automatically detected from the post.
• In normal mode or when creating the location with PHP, you have to select at least a single post type.
  • In the UI, selecting each post type will activate its additional options (like Templates for Pages, Post Formats for Posts)
  • In PHP you can either use a single post type as a string or add multiple post types by providing an array with their

Templates

If you are working with a post type, which supports templates, you can filter the templates, which a container is displayed on.

In the UI,

once you have checked the "Page" post type, you will see a "Templates" field, which allows you to select templates to show and hide the container on. Simply check the the needed templates and you are done.

In PHP

you can either pass the templates argument to the $args array or call the set_templates method.

Before doing so, you need to find the name of the PHP file, which contains the template. If the template is in a sub-directory, make sure to include the name of the directory in the template, ex. page-templates/template-home.php.

If you need to use the default template, simly use "default" as the file name.

Templates are an MVIE Rule

You can add multiple values and/or exclude values by appending a minus sign in front of them.

Learn more

// Argument
$container->add_location( 'post_type', 'page', array(
	'templates' => 'page-templates/template-home.php'
));

// Method
$location = new Ultimate_Fields\Location\Post_Type( 'page' );
$location->set_templates( 'page-templates/template-home.php' );

If you'd only like to show a group for the default page template, please use "default" for the slug.

Terms

When the post type you are working with has any taxonomies associated with it, you can add term-based rules for when to show a container.

In the UI,

once you have checked a post type, which has any hierarchical taxonomies associated with it, you will see a field, which has the same name as the taxonomy, ex. "Categories" for the "Posts" post type.

The field will have two sub-fields: Show on and Hide on. Select the terms that you want to show/hide the container on and you are all set.

In PHP

you can either pass the taxonomy's slug as an argument in the $args array or call the set_terms method.

Terms are an MVIE Rule

You can add multiple values and/or exclude values by appending a minus sign in front of them.

Learn more

Examples:

// Argument: Hide for "Uncategorized"
$container->add_location( 'post_type', 'post', array(
	'category' => '-uncategorized'
));

// Method: Show only "Uncategorized"
$location = new Ultimate_Fields\Location\Post_Type( 'post' );
$location->set_terms( 'category', 1 );

As you can see, you need to include the slug of the taxonomy (category in this case) in both cases.

For the set_terms, the taxonomy slug is the first parameter and the second one contains the actual values.

Levels

Pages in WordPress are a hierarchical post type, meaning that each page can have a parent page. The same also applies to custom post type when the hierarchical argument has been set to true during the post type registration.

For the post type location, you can select which levels to display a container on. The levels start with level one, meaning that:

• Using 1 only works on top-level posts (or pages).
• Using 2 only works on pages with a top-level parent.
• Using -1 will not display the container on the first level (when no parent has been selected).

In the UI,

fields for levels will be automatically displayed once you select a hierarchical post type.

You can enter levels as text, separated by commas.

In PHP

you can either use the levels parameter in the arguments array or use the set_levels method.

Levels are an MVIE Rule

You can add multiple values and/or exclude values by appending a minus sign in front of them.

Learn more

// Argument: Hide on top-level pages
$container->add_location( 'post_type', 'page', array(
	'levels' => -1
));

// Method: Show on second and third level pages
$location = new Ultimate_Fields\Location\Post_Type( 'page' );
$location->set_levels( 2, 3 );

Post Formats

Based on the theme that you are using, you might be able to utilize post formats, which you can read more about in the codex.

In the UI,

once you have checked the "Post" post type for a location, you will se additional fields for post formats. Check which formats you want to show or hide a container on and you are ready to go.

In PHP

you can either use the post_formats argument or call the set_post_formats method.

Post formats are an MVIE Rule

You can add multiple values and/or exclude values by appending a minus sign in front of them.

Learn more

// Argument: Hide on quotes and videos
$container->add_location( 'post_type', 'post', array(
	'post_formats' => array( '-video', '-quote' )
));

// Method: Show on images
$location = new Ultimate_Fields\Location\Post_Type( 'post' );
$location->set_post_formats( 'image' );

Association with particular post IDs

Instead of using location rules when assiging a container to a post type, you can associate the container with particular IDs. This will make the container only visible on those selected pages/posts.

In the UI,

Select Show the container based on a particular post or page for Location Type. This will hide the standard fields and allow you to select a specific item.

Once you have selected an item you can choose whether you want that item (not) to be the post itself or its parent.

In PHP

you can use:

• The ids parameter or the set_ids method to work with particular IDs.
• The parents parameter or the set_parents method to work with parent pages on hierarchical post types.

Post IDs and parents are MVIE rules

You can add multiple values and/or exclude values by appending a minus sign in front of them.

Learn more

// Use the argument to show only on the post with ID 1
$container->add_location( 'post_type', 'post', array(
	'ids' => 1
));

// Use the argument to show only on children of the homepage
$container->add_location( 'post_type', 'post', array(
	'parents' => get_option( 'page_on_front' )
));

// Use methods for the same purpose
$location = new Ultimate_Fields\Location\Post_Type( 'page' );
$location->set_prents( - get_option( 'page_on_front' ) );

$location = new Ultimate_Fields\Location\Post_Type( 'post' );
$location->set_ids( array( 1, 2 ) );

Context and Priority

When adding metaboxes to WordPress you have the option to choose what context to add them to with what priority.

The context determines which column to add the metabox to. There are three options:

• Both normal and advanced will display the meta box in the normal editor column (after the content field). The advanced group is displayed with higher priority (first).
• side will show the metabox in the sidebar (like the "Publish" box)

Priorities determine how important the container is. There are two options:

• normal displays the metabox with normal priority.
• high displays the metabox higher on the page.

In the UI

both of these options are displayed in the "Advanced" tab of the location.

In PHP

you can use the context and priority arguments or the set_context and set_priority methods:

$container->add_location( 'post_type', 'post', array(
	'context' => 'side',
	'priority' => 'advanced'
));

$location = new Ultimate_Fields\Location\Post_Type( 'post' );
$location->set_context( 'side' );
$location->set_priority( 'advanced' );

Adding fields to the customizer

The post type location is amongst the supported locations in the customizer. Please read the Adding fields to the Customizer article to learn how to do it.

Usage with the REST API

In the UI

you need to go the "REST API" tab and select which fields you want to include. You can also select if those fields are editable or not.

In PHP

Please read the REST API section section of the Container Settings article, as the REST functionality is directly controlled in containers.

Adding administration columns

The Post Type location supports Administration Columns. Click the link to learn how to use them.