Explore Custom Post Types handling in Blueprint

[artpi]

Whenever I am selling the idea of WordPress to people, I always like to show how easy it is to implement custom functionality for different use cases.
For example:
"I want a website that is a book catalog"

I always send then to online generators for CPTs and Custom Meta.
ACF entire selling point is to provide this glue code.
It would be nice if blueprint offered an opinionated, very lean options to create a website with those features.

TBD more examples once I think about it more :D

Goals

1. Ability to express any CPT
2. Autocompletion for devs
3. Easy for GPT to generate (e.g. Via a simple, validated schema?)

[adamziel]

On the surface, expressing a post type in a Blueprint could look like this:

{
	"postTypes": {
		"actors": {
			"public": true,
			"show_ui": true,
			"show_in_menu": true,
			"show_in_nav_menus": true
		}
	}
}

In reality, however, registering post types is more nuanced. I researched what registering custom post types looks like in top GitHub search and SourceView results – see the results below.

Movies demo

	$labels = array(
		'name'          => esc_html__( 'Movies', 'wp-movies-demo' ),
		'singular_name' => esc_html__( 'Movie', 'wp-movies-demo' ),
	);

	$args = array(
		'label'                 => esc_html__( 'Movies', 'wp-movies-demo' ),
		'labels'                => $labels,
		'description'           => '',
		'public'                => true,
		'publicly_queryable'    => true,
		'show_ui'               => true,
		'show_in_rest'          => true,
		'rest_base'             => '',
		'rest_controller_class' => 'WP_REST_Posts_Controller',
		'rest_namespace'        => 'wp/v2',
		'has_archive'           => 'movies',
		'show_in_menu'          => true,
		'show_in_nav_menus'     => true,
		'delete_with_user'      => false,
		'exclude_from_search'   => false,
		'capability_type'       => 'post',
		'map_meta_cap'          => true,
		'hierarchical'          => false,
		'can_export'            => true,
		'rewrite'               => array(
			'slug'       => 'movies',
			'with_front' => true,
		),
		'query_var'             => true,
		'supports'              => array( 'title', 'editor', 'thumbnail', 'custom-fields' ),
		'taxonomies'            => array( 'category' ),
		'show_in_graphql'       => false,
	);

	register_post_type( 'movies', $args );

Nothing out of ordinary here, except there is no straightforward way to express esc_html__ in JSON.

We could perhaps assume that labels are escaped and translated, but which text domain should we use? Each label could use a different one, so we can't just accept an additional textDomain argument. Blueprints would need a way to express "escape + translate" in JSON, like:

{
	"postTypes": {
		"actors": {
			"label": {
				"php_function": "esc_html__",
				"args": [ "Movies", "wp-movies-demo" ]
			}
		}
	}
}

But that's very clunky. What if we had a special syntax just for esc_html__?

{
	"postTypes": {
		"actors": {
			"label": {
				"esc_html__": [ "Movies", "wp-movies-demo" ]
			}
		}
	}
}

Still clunky, but maybe less.

Okay, how are other plugins doing it?

Webkit/websites

Repo link

        register_taxonomy(self::MEETING_TAXONOMY, [self::CUSTOM_POST_TYPE], [
            'label' => __('WebKit Meeting'),
            'hierarchical' => false,
            'rewrite' => ['slug' => 'webkit-meeting'],
            'show_admin_column' => false,
            'show_in_rest' => false,
            'labels' => [
                'singular_name' => __('WebKit Meeting'),
                'all_items' => __('All WebKit Meetings'),

This is register_taxonomy, not register_post_type, but one notable thing is it uses the __ function, not the esc_html__ one. Okay, so that's another thing to support in blueprint.json:

{
	"postTypes": {
		"actors": {
			"label": {
				"__": [ "Movies", "wp-movies-demo" ]
			}
		}
	}
}

Hm, I wonder how many aimilar functions like that are out there.

10up/ElasticPress

Source link

		$args = [
			'description'        => esc_html__( 'Elasticsearch Synonyms', 'elasticpress' ),
			'public'             => false,
			'publicly_queryable' => false,
			'show_ui'            => false,
			'show_in_menu'       => false,
			'query_var'          => true,
			'capabilities'       => Utils\get_post_map_capabilities(),
			'has_archive'        => false,
			'hierarchical'       => false,
			'menu_position'      => 100,
			'supports'           => [ 'title' ],
		];

		register_post_type( self::POST_TYPE_NAME, $args );

The interesting part is 'capabilities' => Utils\get_post_map_capabilities(),. Should calling arbitrary methods be supported at the setup stage? I hypothesize that 99% websites won't need to do that and the remaining 1% could just provide a custom PHP file to register its post types.

WooCommerce/projects

Source link

This is an interesting code example:

		$labels = array(
			'name' 					=> $this->plural_name,
			'singular_name' 		=> $this->singular_name,
			'add_new' 				=> _x( 'Add New', $this->post_type, 'projects-by-woothemes' ),
			'add_new_item' 			=> sprintf( __( 'Add New %s', 'projects-by-woothemes' ), $this->singular_name ),
			'edit_item' 			=> sprintf( __( 'Edit %s', 'projects-by-woothemes' ), $this->singular_name ),
			'new_item' 				=> sprintf( __( 'New %s', 'projects-by-woothemes' ), $this->singular_name ),
			'all_items' 			=> sprintf( _x( 'All %s', $this->post_type, 'projects-by-woothemes' ), $this->plural_name ),
			'view_item' 			=> sprintf( __( 'View %s', 'projects-by-woothemes' ), $this->singular_name ),
			'search_items' 			=> sprintf( __( 'Search %a', 'projects-by-woothemes' ), $this->plural_name ),
			'not_found' 			=> sprintf( __( 'No %s Found', 'projects-by-woothemes' ), $this->plural_name ),
			'not_found_in_trash' 	=> sprintf( __( 'No %s Found In Trash', 'projects-by-woothemes' ), $this->plural_name ),
			'parent_item_colon' 	=> '',
			'menu_name' 			=> $this->plural_name

		);
		$args = array(
			'labels' 				=> apply_filters( 'projects_post_type_labels', $labels, $labels ),
			'public' 				=> true,
			'publicly_queryable' 	=> true,
			'show_ui' 				=> true,
			'show_in_menu' 			=> true,
			'query_var' 			=> true,
			'rewrite' 				=> apply_filters( 'projects_post_type_rewrite', true ),
			'capability_type' 		=> 'post',
			'has_archive'			=> 	( $projects_page_id = projects_get_page_id( 'projects' ) ) && get_page( $projects_page_id ) ? get_page_uri( $projects_page_id ) : 'projects',
			'hierarchical' 			=> false,
			'supports' 				=> array(
										'title',
										'editor',
										'thumbnail',
										'excerpt'
										),
			'menu_position' 		=> 5,
			'menu_icon' 			=> 'dashicons-portfolio'
		);

		$args = apply_filters( 'projects_register_post_type', $args );

		register_post_type( $this->post_type, (array) $args );

Notably, it uses _x(), sprintf(), __, $this, apply_filters(), ternary operators, assignments etc. This is way out of scope for blueprint.json and would have to be done using a custom PHP file.

GravityView/future

Source link

This is another advanced example:

		$args = array(
			// ...
			'public'              => apply_filters( 'gravityview_direct_access', gravityview()->plugin->is_compatible(), 0 ),
			'show_ui'             => gravityview()->plugin->is_compatible(),

wp-twitter-tools/blob

Source link

There's some non-JSON-expressible PHP code in here as well:

		register_post_type(self::$post_type, array(
			'labels' => array(
				'name' => __('Tweets', 'twitter-tools'),
				'singular_name' => __('Tweet', 'twitter-tools')
			),
			'supports' => array(
				'editor',
				'thumbnail',
			),
			'public' => (bool) self::option('tweet_visibility'),
			'show_ui' => (bool) self::option('tweet_admin_ui'),

Others

Here's a few more repos where registering custom post types was done in, mostly, a JSON-friendly way:

• fossasia/loklak_wp_plugins
• nk-crew/lazy-blocks
• oceo/jeo

[adamziel]

A few observations true for all the examples I saw

• There was no mixing text domains when translating
• Translations have only been used for labels
• Each registered post type relied on a single translation function

Here's what a Blueprint syntax inspired by these learnings would look like:

{
	"postTypes": {
		"actors": {
			"label": "Movies",
			"labels": {
				"name": "Actors",
				"singular_name": "Actor"
			},
			"public": true,
			"show_ui": true,
			"show_in_menu": true,
			"show_in_nav_menus": true,
			"can_export": true,
			"rewrite": {
				"slug": "actors",
				"with_front": true,
			}
		}
	},
	"postTypesSettings": {
		"translations": {
			"domain": "wp-movies-demo",
			"function": "esc_html__"
		}
	}
}

And for anything that cannot be expressed using this syntax, the developer could always rely on a custom plugin or a mu-plugin.

More research would still be useful to confirm these patterns.

Are there any clear benefits of inventing a JSON syntax over simply supporting shipping PHP files with Blueprints?

There will be developers who hit a wall with the JSON syntax and will have to migrate to PHP. Why not start with PHP right away? The JSON syntax would be a specialized subset and would differ in subtle ways, I’m sure we’d get the schema wrong in different places not to mention WordPress plugins could reframe the expected data types in $args.

Other open questions

• How should CPT templates be registered? Here's some related thoughts from StackOverflow.
• Should registering metaboxes for post types be supported in this data format?
• Would every WordPress export be expressible using the JSON syntax, or is it missing anything?

[dmsnell]

One thing to keep watch over is how much of the existing PHP API we're creating in an almost-identical-yet-incompatible custom DSL. In the given JSON examples there's very little difference in providing those "declarative" configs to running custom PHP code which registers the custom post type with the real PHP API, something that provides a system where everything works by default instead of a system where everything other than the most basic functionality is missing.

I love the idea of registering custom posts types, but maybe we can make it clearer for people how to run PHP code and provide template for things like CPTs instead of creating sidecar languages that will inevitably grow more complicated until almost everything in the CPT registration API is recreated, but with subtle differences…?

[adamziel]

My thoughts exactly @dmsnell! The more I think about it, the more it makes sense to just add a convenient support for PHP, maybe with something like JSON5 or Yaml so that you can write simple examples inline?

[adamziel]

Case in point for YAML, all the existing Blueprints would keep working (with nuanced caveats that hopefully don’t apply):

YAML is a superset of JSON, which means any valid JSON is valid YAML

Here’s what that could look like:

post_types:
  actors:
    args:
      labels:
        name: Actors
        singular_name: !php __( 'Actor', 'movies-demo' )
        add_new: Add Actor
      public: true
      publicly_queryable: true
      show_ui: true
      show_in_menu: true
      query_var: true
      rewrite: true
      capability_type: 'post'
      has_archive: projects
      hierarchical: false
      supports: 
        - title
        - editor
        - thumbnail
        - excerpt
      menu_position: 5
      menu_icon: 'dashicons-portfolio'
  actors:
    code: |
      $labels = array(
        'name' 					=> $this->plural_name,
        'singular_name' 		=> $this->singular_name,
        'add_new' 				=> _x( 'Add New', $this->post_type, 'projects-by-woothemes' ),
        'add_new_item' 			=> sprintf( __( 'Add New %s', 'projects-by-woothemes' ), $this->singular_name ),
        'edit_item' 			=> sprintf( __( 'Edit %s', 'projects-by-woothemes' ), $this->singular_name ),
        'new_item' 				=> sprintf( __( 'New %s', 'projects-by-woothemes' ), $this->singular_name ),
        'all_items' 			=> sprintf( _x( 'All %s', $this->post_type, 'projects-by-woothemes' ), $this->plural_name ),
        'view_item' 			=> sprintf( __( 'View %s', 'projects-by-woothemes' ), $this->singular_name ),
        'search_items' 			=> sprintf( __( 'Search %a', 'projects-by-woothemes' ), $this->plural_name ),
        'not_found' 			=> sprintf( __( 'No %s Found', 'projects-by-woothemes' ), $this->plural_name ),
        'not_found_in_trash' 	=> sprintf( __( 'No %s Found In Trash', 'projects-by-woothemes' ), $this->plural_name ),
        'parent_item_colon' 	=> '',
        'menu_name' 			=> $this->plural_name

      );
      $args = array(
        'labels' 				=> apply_filters( 'projects_post_type_labels', $labels, $labels ),
        'public' 				=> true,
        'publicly_queryable' 	=> true,
        'show_ui' 				=> true,
        'show_in_menu' 			=> true,
        'query_var' 			=> true,
        'rewrite' 				=> apply_filters( 'projects_post_type_rewrite', true ),
        'capability_type' 		=> 'post',
        'has_archive'			=> 	( $projects_page_id = projects_get_page_id( 'projects' ) ) && get_page( $projects_page_id ) ? get_page_uri( $projects_page_id ) : 'projects',
        'hierarchical' 			=> false,
        'supports' 				=> array(
                      'title',
                      'editor',
                      'thumbnail',
                      'excerpt'
                      ),
        'menu_position' 		=> 5,
        'menu_icon' 			=> 'dashicons-portfolio'
      );

      $args = apply_filters( 'projects_register_post_type', $args );
      register_post_type( $this->post_type, (array) $args );

Upsides:

• Unlimited expresiveness

Downsides:

• No code completion
• You need to remember how to use register_post_type

There must be some intermediate solution that would still offer code completion 🤔

Maybe YAML tags would help?

postTypes:
	movies:
		label: !php esc_html("Movies", "text-domain")
	actors: >
		<?php

This would offer autocompled experience, enable PHP expressions, and finally allow developers to run any PHP code if they need to structure something differently.

It checks all these boxes:

1. Ability to express any CPT
2. Autocompletion for devs
3. Easy for GPT to generate (e.g. Via a simple, validated schema?)

[swissspidy]

That seems weird to me. Such a declarative approach for registering a custom post type is not really portable and maintainable. At this point you can just as well write PHP code in an actual PHP file and load that as a plugin the blueprint 🤔 See #9

[artpi]

You are correct @swissspidy ! In fact, I just realized today that your point may extend to most of Blueprint actions:
WordPress/blueprints#6 (comment)

As far as I am concerned, we can close this issue.