Custom Post Type Settings

Generally the post type settings used in ACF Engine are an exact or very similar match to the options found in the core WordPress post types registration. There are some minor differences for convenience, or where the functionality of a certain setting works a little differently in the UX than how we might use it if we were writing registration code for register_post_type().

Settings Tabs #

The ACF Engine Post Type Editor has 4 tabs to organize the settings for post types. As post types are powerful WP objects, they come with a very rich set of options. We want to support all of them, and doing that in an interface means a lot of fields. The good news is you can still create a post type with nothing more than a key and a title and this will get you started with a functional post type.

Key (key) #

The post key must be unique, and it should normally be lowercased and alpha such as "vehicle" or "vehicle_model". Though it is less conventional, we do sometimes see hyphens used in place of underscores and it appears to work such as "vehicle-model", however we would still recommend using underscores exclusively for your post type keys.

Note that your final post types keys will be automatically prefixed with "acfg_" which is a universal prefix applied by ACF Engine. We may provide a way for advanced users to filter or change this in the future, but this automatic prefixing helps ensure uniqueness in the overall WP ecosystem. You'll still need to create unique keys within your own site or sites, and be even more diligent in this if you plan to migrate post types with similar names from one site to another.

Singular Name #

Aside from the key, Singular Name is the only field we set as required for post type creation in ACF Engine. If you use only Singular Name, we'll automatically utilize this for the Plural Name through simply attaching an "s". This may work if your post type is "Vehicle", it will not work well if your post type is "Story", which would result in pluralized "Storys". For that reason you'll sometimes need to set the Plural Name in addition to the Singular Name.

It is convention that the custom post type Singular Name is an exact match with the key, however this is not a requirement. Singular Name is only used for labels, and thus does not affect the functionality of the post type.

Plural Name #

Plural name is used to set the name anywhere that WP is referring to the "post type items" rather than a singular item. By default ACF Engine will set this to your post type singular name with an "s" at the end so if your singular post type name is "Vehicle" the plural name will be "Vehicles". When you have a post type name that doesn't fit this approach such as "Story" you'll want to set the Plural Name to "Stories" for example.

Public #

Controls how the type is visible to authors (show_in_nav_menus, show_ui) and readers (exclude_from_search, publicly_queryable).

This is a rare setting where we do not follow the WordPress defaults. WP default for public is false, which means the post type will not be available in the WP admin, and a range of other settings will by default be turned off. Because we feel the majority of custom post types ACF Engine users will create will be geared towards content management, rather than private data storage, we decide to make public true by default.

Show in Menu (show_in_menu) #

This setting defines if your post type should automatically appear in the WP Admin menu. This setting controls display in the main left-hand admin menu, so take note that there are separate options under "Advanced" in the Post Type Editor to control display for instance in the admin bar or other WP locations.

If you do choose to show your post type in the menu you may also want to use the related setting Menu Position to control where the new menu item is positioned.

Menu Position (menu_position) #

This setting defines where in the WP admin main menu (on the left) the new post type will appear. This works only if the "Show in Menu" setting is on which creates the post type. You can experiment with different numbers here to place your menu item where you want it to be, the higher the number the lower it will appear in the menu.

Menu Icon (menu_icon) #

The menu icon setting is for customizing the icon shown when your post type is provided in the WP main menu. This setting is only shown if you have set Show in Menu to true. Most commonly here you will specify a dashicon, that's the WordPress native icon font that is available. You can however specify a URL to an icon instead. By default ACF Engines uses the Dashicon Feedback (dashicons-feedback) icon.

Supports (supports) #

Supports is a list of features that the custom post type will support. We will defer to the official WordPress documentation on Post Type Supports the finer details of what these supported features will do. By default WP will utilize "title" and "editor", so these are also the defaults we have checked in the ACF Engine Post Type Editor.

It's worth noting that if your goal is to provide Gutenberg editing for your custom post type, then you must not only leave "editor" checked, but you must also have the "Show in REST" setting turn on as well. This is because Gutenberg uses the REST API, and if the custom post type doesn't have REST API exposure, then it can't use Gutenberg. As a result if your post type has "editor support" but does not "Show in REST", you will see the "classic editor" (TinyMCE). This also answers the question, what if you want the classic editor, well then you could simply turn off "Show in REST". Note that the Show in Rest setting is located under the Advanced tab in the Post Type Editor.

Another custom post type design consideration is that if you plan to provide an ACF field group for your custom post type, which is often the case when using ACF Engine... you may want to remove the editor, and possibly even the title as well. If you remove both title and editor, your ACF field group will become the primary and stand-alone element when that post type is edited, making it feel more like a custom app interface and putting the fields front and center. There are some downsides to not using the default post title however so you may want to experiment and see if it works for you. As an example if your posts don't have a title you'll probably need to provide an ACF field to serve the purpose of a title, but then you'll also need to replace default titles using code.

Labels #

WordPress offers a long list of labels that can be set for your custom post type. While it's great to have the option to do this deep customization, in most cases the vast majority of the labels can be left unset and WP will just use the defaults which look fine in most cases.

The Labels Tab settings in the ACF Engine Post Type Editor starts with the "Add New" label. We are not providing the settings for the main label (Singular Title) or the pluralized main title here under the labels tab as these are front and center as options in the Basic Tab of the editor. Unless you want to customize your post type more deeply by setting custom labels for various WP admin features that use the post type labels, you won't actually need to visit the Labels Tab at all.

We will defer to the official WordPress post type label documentation on how each label is utilized.

REST API Settings #

Show in Rest API #

Whether to include the post type in the REST API. This is one of the two settings that must be set in order for the Gutenberg editor to work in your custom post type. The other setting that must be active for Gutenberg to appear is "editor" must be checked under the "supports" list.

The WordPress default setting for Show in Rest API is false. ACF Engine however is designed for use with Gutenberg and we elected to turn this setting to true by default in order to make Gutenberg appear if "editor" is chosen in the supports list.

Turn this setting off to remove the Gutenberg editor. If you turn this setting off and leave "editor support" on, then the classic (TinyMCE) editor will be shown.

REST Base (rest_base) #

To change the Base URL of the REST API route. Default is to use the post type key.

REST Controller Class (rest_controller_class) #

REST API Controller class name. Default is "WP_REST_Posts_Controller".

Advanced Settings #

Description #

Description is a setting designed to store a brief description about the post type explaining what it is used for. In practice this setting is only available to programmers and is never shown in the WP Admin or even available on the front-end. In other words, ACF Engine provides it only for completeness, it is not usually useful unless you intend to for instance make a list of post types that would have their descriptions for context.

Hierarchical #

Hierarchical is a setting WP created specifically to support "Pages" which are a special form of post type in WordPress. It is not usually recommended as a setting, specifically because of the concern over performance if you have a large number of posts or deep nesting. However if you want the hierarchical approach of pages you can turn this on and WP will provide on the editor screens (under Document Settings when using Gutenberg) the option to nest the post by selecting a parent post.

Rewrite #

Triggers the handling of rewrites for this post type. To prevent rewrites, set to false.

Default value is true, and it uses the the post type key as the slug.

Has Archive #

Found under the Advanced tab, enabling "Has Archive" setting will tell WordPress to automatically create an archive which by default is setup using your post type key as the slug. For instance if your post type is "vehicle" the archive will be located at "/vehicle/". Sometimes you may want to alter this for instance you may want post type archive "/properties/" even thought the CPT slug is "/property/". To do this requires filtering the permalink settings using custom code.

Show in Nav Menus #

Whether post_type is available for selection in navigation menus.

By default this will match the "Public" setting. This means if the post type is set to public, which is the default in ACF Engine, then the post type will appear in Nav Menus.

Show in Admin Bar #

This setting determines if the post type will be listed in the quick menu through the Admin Bar that enables editor to create new posts.

The default setting is the same as the Show in Menu setting, so if that is set to true by default the post type will appear in the admin bar.

Can Export #

Can the Post Type be exported. Default setting is true.

Delete with User #

Whether to delete posts of this type when deleting a user. If true, posts of this type belonging to the user will be moved to trash when then user is deleted. If false, posts of this type belonging to the user will not be trashed or deleted. If not set (the default), posts are trashed if post_type_supports('author'). Otherwise posts are not trashed or deleted.

Query Var #

This is one of the most complicated settings for a custom post type. We recommend thoroughly reading the official WP documentation for Query Var to fully understand it. For most users, this setting should not be used.

Publicly Queryable #

Whether queries can be performed on the front end as part of parse_request().

Default is the value of Public setting.

Exclude from Search #

Whether to exclude posts with this post type from front end search results.

Default value is the opposite of the Public setting, which means if your post type is public it will be searchable, and if you turn off Public access then this will activate Exclude from Search automatically.

Powered by BetterDocs

Leave a Reply