Relevant issues - however, I think this spec is part of the Blueprints API v2 which isn't quite yet ready

• Advanced blueprint.json code block incomplete wordpress-playground#1110
• Advanced example blueprint.json appears truncated #8

@flexseth Thanks for the fix! How can the rendered doc be previewed? Does the final result include the backticks or not?

If it does, that's a bit of a problem as that won't work in Playground. The functioning API spec uses backticks to split the code over multiple lines. The price to pay is that it isn't a valid JSON anymore, only valid JavaScript. And a doubly wrapped strings could lead to a syntax error, e.g.:

{
    "code": "`<?php require_once 'wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'wp-load.php required for WP functionality', 'post_status' => 'publish')); ?>`"
}

Would output two backticks and work. However, this, without the closing ?>, would be a PHP syntax error:

{
    "code": "`<?php require_once 'wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'wp-load.php required for WP functionality', 'post_status' => 'publish')); `"
}

In the Blueprints v2 I'd like to include the following multiline string syntax:

{
    "code": [
        "<?php",
        "function test() {",
        "    return 'test';",
        "}"
    ]
}

This is to say, we may need to fix the doc renderer to fix the problem. If the backticks are displayed in the final doc, we can't have them :( cc @dd32

I see. That was the only example that I found that worked with runPHP code so I assumed it was the backticks.

What you end up having to do is wrap code that is in backticks in a code block, perhaps escaping.

It's not pretty, there's an example below. I'll try out your PHP code sample after coffee 😀

Here's that code on GitHub, it's a bit difficult to decipher without formatting

<BlueprintExample display={{ "steps": [ { "step": "login" }, { "step": "installPlugin", "pluginZipFile": { "resource": "wordpress.org/plugins", "slug": "friends" } }, { "step": "runPHP", "code": <?php include 'wordpress/wp-load.php'; wp_insert_post(array( 'post_title' => 'Post title', 'post_content' => 'Post content', 'post_status' => 'publish', 'post_author' => 1 )); } ] } } blueprint={{ "steps": [ { "step": "login" }, { step: 'installPlugin', pluginZipFile: { resource: 'wordpress.org/plugins', slug: 'friends', }, }, { "step": "runPHP", "code": <?php include 'wordpress/wp-load.php'; wp_insert_post(array( 'post_title' => 'Post title', 'post_content' => 'Post content', 'post_status' => 'publish', 'post_author' => 1 )); } ] }} />

You will notice there are formatting issues here, also.

Last week I ran into a similar example on the REST API, where someone wanted to use the backtick syntax to highlight a URL. And it messed up the paragraph until the next line break.

I believe this was due to GitHub's Markdown renderer believing it to be code inside of code, an then leaving an extraneous backtick... it previewed OK using the Markdown Preview Enhanced extension for VS Code.

In the REST API use case...

The code had to be changed from

`https://somecoolulr.com\`
to
<code>https://somecoolurl.com</code>

And below is a screenshot of what it actually looks like in the GitHub Markdown editor (I am not trying to re-create this in Markdown 😆)

This isn't 100% accurate but hopefully proves the point about the syntax

@flexseth Thanks for the fix! How can the rendered doc be previewed? Does the final result include the backticks or not?

I think it's possible to make it look good on the front-end, rendered from Markdown, but it's going to lead to a lot of escaping, and wrapping stuff in code blocks that isn't actually wrapped in code blocks.

Potentially making the documentation much more difficult to edit and maintain.

cc: @dd32

In the Blueprints v2 I'd like to include the following multiline string syntax:

{
    "code": [
        "<?php",
        "function test() {",
        "    return 'test';",
        "}"
    ]
}

I believe this would be...

{
    "code": [
        "<code><?php",
        "function test() {",
        "    return 'test';",
        "}?></code>"
    ]
    
}

@flexseth Thanks for the fix! How can the rendered doc be previewed? Does the final result include the backticks or not?

I think it's possible to make it look good on the front-end, rendered from Markdown, but it's going to lead to a lot of escaping, and wrapping stuff in code blocks that isn't actually wrapped in code blocks.

Oh, sorry, I didn't mean PHP syntax coloring, I just meant the backticks shouldn't be in the final JSON displayed to the end readers of that documentation. It's absolutely fine for PHP to be treated as a JSON string and not be syntax highlighted.

@adamziel I think if you replace the backticks with <code></code> it will still use the Markdown syntax highlighting

Might be a bit beyond the scope of this PR, but can you use wp cli commands in the steps?

@helgatheviking yes, you can! Or did you mean to update those examples to actually use wp-cli?

cc @tellyworth @StevenDufresne for reviews as I don't have the handbook build environment set up.

Well more examples are always great! In reviewing the doc, I found the import file, but my plugin's live preview doesn't seem to actually import that file.

@tellyworth @StevenDufresne, @adamziel - this code is incorrect I believe. We discussed wrapping the code in backticks which is not correct, I need to revert that change. Didn't have a chance to get to it yesterday but I should be able to clean up this commit today

cc @tellyworth @StevenDufresne for reviews as I don't have the handbook build environment set up.

I don't have it configured either but the changes look ok to me.

LGTM. I don't think we have any way to preview the change to confirm correct handling/escaping, so let's just go with it and if there's an issue then deal with the new problem.

Yeah I've been looking at some of the idiosyncrasies with escaping PHP inside JSON code blocks. It's a bit iffy - but you're right, there is no way to preview the Markdown it it does not look like.

Happy to work on the formatting if it doesn't look right with the end product and adjust accordingly, I'll keep the issues open until it looks right.

TY for reviewing, look forward to merge so I can check the formatting!

Yeah I've been looking at some of the idiosyncrasies with escaping PHP inside JSON code blocks. It's a bit iffy

I'm not having any success with that yet and I can't tell if it's CLI or the playground. I have an issue open at CLI as well.

Just tested my blueprint.json and it's crashing the playground

{
            "step": "wp-cli",
            "command": "wp post create --post_title=\"User Directory Demo\" --post_type=page --post_status=publish --post_author=1 --post_content=\"<!-- wp:simple-user-listing/directory-block {\"columns\":3,\"showAllUsers\":false,\"roles\":\"subscriber\",\"usersPerPage\":9,\"className\":\"is-style-grid\"} /-->\""
        }

resulting in this error... which I think is coming back to the block attributes not getting inserted correctly.

[03-Apr-2024 01:37:39 UTC] PHP Fatal error:  Uncaught TypeError: array_key_exists(): Argument #2 ($array) must be of type array, null given in /wordpress/wp-includes/block-supports/align.php:2
Stack trace:
#0 /wordpress/wp-includes/class-wp-block-supports.php(3): wp_apply_alignment_support(Object(WP_Block_Type), NULL)
#1 /wordpress/wp-includes/class-wp-block-supports.php(3): WP_Block_Supports->apply_block_supports()
#2 /wordpress/wp-content/plugins/simple-user-listing/dist/directory/render.php(20): get_block_wrapper_attributes(Array)
#3 /wordpress/wp-includes/blocks.php(2): require('/wordpress/wp-c...')
#4 /wordpress/wp-includes/class-wp-block.php(3): {closure}(Array, '', Object(WP_Block))
#5 /wordpress/wp-includes/blocks.php(2): WP_Block->render()
#6 /wordpress/wp-includes/blocks.php(2): render_block(Array)
#7 /wordpress/wp-includes/class-wp-hook.php(3): do_blocks('<!-- wp:simple-...')
#8 /wordpress/wp-includes/plugin.php(2): WP_Hook->apply_filters('<!-- wp:simple-...', Array)
#9 /wordpress/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php(2): apply_filters('the_content', '<!-- wp:simple-...')
#10 /wordpress/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php(2): WP_REST_Posts_Controller->prepare_item_for_response(Object(WP_Post), Object(WP_REST_Request))
#11 /wordpress/wp-includes/rest-api/class-wp-rest-server.php(3): WP_REST_Posts_Controller->get_item(Object(WP_REST_Request))
#12 /wordpress/wp-includes/rest-api/class-wp-rest-server.php(3): WP_REST_Server->respond_to_request(Object(WP_REST_Request), '/wp/v2/pages/(?...', Array, NULL)
#13 /wordpress/wp-includes/rest-api.php(2): WP_REST_Server->dispatch(Object(WP_REST_Request))
#14 /wordpress/wp-includes/rest-api.php(5): rest_do_request(Object(WP_REST_Request))
#15 [internal function]: rest_preload_api_request(Array, '/wp/v2/pages/4?...')
#16 /wordpress/wp-includes/block-editor.php(2): array_reduce(Array, 'rest_preload_ap...', Array)
#17 /wordpress/wp-admin/edit-form-blocks.php(2): block_editor_rest_api_preload(Array, Object(WP_Block_Editor_Context))
#18 /wordpress/wp-admin/post.php(2): require('/wordpress/wp-a...')
#19 {main}
  thrown in /wordpress/wp-includes/block-supports/align.php on line 2

@helgatheviking the issue seems to be with escaping the quotes. You have JSON in a shell command in JSON. Your Block markup seems to be:

<!-- wp:simple-user-listing/directory-block {"columns":3,"showAllUsers":false,"roles":"subscriber","usersPerPage":9,"className":"is-style-grid"} /-->

Escaping that for wp-cli would be rather cumbersome, but you could just switch to single quotes ', as in:

wp post create --post_title="User Directory Demo" --post_type=page --post_status=publish --post_author=1 --post_content='<!-- wp:simple-user-listing/directory-block {"columns":3,"showAllUsers":false,"roles":"subscriber","usersPerPage":9,"className":"is-style-grid"} /-->'

Now, bringing that into a Blueprint requires encoding the entire command as JSON:

{
  "landingPage": "/wp-admin/edit.php?post_type=page",
  "phpExtensionBundles": [
    "kitchen-sink"
  ],
  "steps": [
    {
      "step": "login",
      "username": "admin",
      "password": "password"
    },
    {
      "step": "wp-cli",
      "command": "wp post create --post_title=\"User Directory Demo\" --post_type=page --post_status=publish --post_author=1 --post_content='<!-- wp:simple-user-listing/directory-block {\"columns\":3,\"showAllUsers\":false,\"roles\":\"subscriber\",\"usersPerPage\":9,\"className\":\"is-style-grid\"} /-->'"
    }
  ]
}

Which works as expected: