Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create Block: Support Custom Prompts in External Templates #67806

Open
wants to merge 5 commits into
base: trunk
Choose a base branch
from

Conversation

eduwass
Copy link
Contributor

@eduwass eduwass commented Dec 10, 2024


Closes #47524


What?

This PR enhances the @wordpress/create-block package by allowing external project templates to define custom prompts, enabling developers to specify additional parameters during block or plugin creation.

Why?

Currently, the @create-block package limits users to a predefined set of prompts, restricting customization based on specific project needs. Allowing custom prompts provides greater flexibility and aligns the tool with diverse development requirements.

How?

The implementation involves modifying the getDefaultValues and getPrompts functions within the templates.js file to recognize and incorporate custom parameters defined in external templates. This ensures that during the scaffolding process, any additional prompts specified are presented to the user and their inputs are integrated into the generated project files.

Testing Instructions

  1. Prepare an external project template that includes custom prompt configurations.
  2. Use the modified @create-block package to generate a new block or plugin with the custom template.
  3. Verify that the custom prompts are displayed during the creation process.
  4. Confirm that the responses to the custom prompts are accurately reflected in the scaffolded project files.

Testing Instructions for Keyboard

  1. Initiate the block or plugin creation process using the terminal.
  2. Navigate through the prompts using keyboard inputs.
  3. Ensure all prompts, including custom ones, are accessible and can be answered solely via the keyboard.

Screenshots or screencast

This quick demo contains a couple of examples of how I'd envision this working:

000445.mp4
Heres the code for: my-template/index.js

/**
 * Dependencies
 */
const { join } = require("path");

module.exports = {
    defaultValues: {
        title: "My Template",
        description: "My Template Description",
        icon: "admin-post",
        // Default values for custom prompts
        analyticsId: 'UA-11111-2',
        colorScheme: 'default',
        enableAdvancedFeatures: false,
        customCssPrefix: 'default-prefix-',
    },
    customPrompts: {
        analyticsId: {
            type: 'input',
            name: 'analyticsId',
            message: 'Enter your Google Analytics ID (optional, format: UA-XXXXX-Y):',
            validate(input) {
                if (!input) return true; // Optional
                if (!/^UA-\d+-\d+$/.test(input)) {
                    return 'Invalid Google Analytics ID format. Should be like UA-XXXXX-Y';
                }
                return true;
            }
        },
        colorScheme: {
            type: 'list',
            name: 'colorScheme',
            message: 'Choose a color scheme for your block:',
            choices: [
                { name: 'Default Theme Colors', value: 'default' },
                { name: 'Custom Palette', value: 'custom' },
                { name: 'Monochrome', value: 'mono' }
            ],
            default: 'default'
        },
        enableAdvancedFeatures: {
            type: 'confirm',
            name: 'enableAdvancedFeatures',
            message: 'Would you like to enable advanced block features?',
            default: false
        },
        customCssPrefix: {
            type: 'input',
            name: 'customCssPrefix',
            message: 'Enter a custom CSS prefix for your block (optional):',
            validate(input) {
                if (!input) return true; // Optional
                if (!/^[a-z][a-z0-9-]*$/.test(input)) {
                    return 'CSS prefix must start with a letter and contain only lowercase letters, numbers, and hyphens';
                }
                return true;
            },
            filter(input) {
                return input.toLowerCase();
            }
        }
    },
    // Make sure template files are found
    pluginTemplatesPath: join(__dirname, 'files', 'plugin'),
    blockTemplatesPath: join(__dirname, 'files', 'block'),
};

This enhancement addresses the need for customizable prompts in the @create-block package, as discussed in issue #47524.

Enhance the create-block functionality allowing the inclusion of custom prompts. This change enables template configurations to specify additional prompts beyond the built-in ones, facilitating more flexible block creation.

- Validate custom prompts for required properties: type, name, and message.
- Merge custom prompts with built-in prompts to offer a comprehensive query set.
- Ensure compatibility with existing template definitions by handling cases with null or non-object customPrompts gracefully.
…n into the block creation process.

- Merge built-in and custom prompts into a single array.
- Allow custom prompts to be included wherever keys are specified.
- Ensure default values for custom prompts are correctly retrieved and utilized.
- Simplify the logic for aggregating both built-in and custom prompts into a single comprehensive list.

This change enhances flexibility for developers using custom prompts with create-block.
Copy link

github-actions bot commented Dec 10, 2024

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: eduwass <[email protected]>
Co-authored-by: ryanwelcher <[email protected]>
Co-authored-by: gziolo <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@gziolo
Copy link
Member

gziolo commented Dec 11, 2024

This is looking very promising. One note is that the proposed API depends on inquirer. It's currently outdated in Create Block:

"inquirer": "^7.1.0",

The most recent version is 12.2.0. There were some breaking changes, mostly in versions 9.0 and 10.0. It would be great to validate separately whether we can upgrade to the latest version so we can ensure we support the most recent API for prompts.

@gziolo
Copy link
Member

gziolo commented Dec 12, 2024

I started migrating Inquirer.js to the latest version:

The recommend using now @inquirer/prompts instead of inquirer, which they put in the maintenance mode.

@gziolo
Copy link
Member

gziolo commented Dec 17, 2024

#67877 is ready to review. There were a few API changes which are essential before we offered support for custom prompts. Let's land that one first and update this PR accordingly.

@ryanwelcher
Copy link
Contributor

I've approved #67877.

Copy link
Contributor

@ryanwelcher ryanwelcher left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added some suggestions that will fix the whitespace issues in the PR.

packages/create-block/lib/index.js Outdated Show resolved Hide resolved
packages/create-block/lib/index.js Outdated Show resolved Hide resolved
packages/create-block/lib/templates.js Outdated Show resolved Hide resolved
packages/create-block/lib/templates.js Outdated Show resolved Hide resolved
packages/create-block/lib/templates.js Outdated Show resolved Hide resolved
packages/create-block/lib/templates.js Outdated Show resolved Hide resolved
packages/create-block/lib/templates.js Outdated Show resolved Hide resolved
packages/create-block/lib/templates.js Outdated Show resolved Hide resolved
packages/create-block/lib/templates.js Outdated Show resolved Hide resolved
packages/create-block/lib/templates.js Outdated Show resolved Hide resolved
@eduwass eduwass changed the title Enhance @wordpress/create-block to Support Custom Prompts in External Templates Create Block: Support Custom Prompts in External Templates Dec 21, 2024
@eduwass
Copy link
Contributor Author

eduwass commented Dec 21, 2024

Hey @ryanwelcher, @gziolo!

I’ve been thinking about the ideal structure of how this should work, before working on an actual implementation. I put together a document trying to cover all the edge cases. I'd love for you to check it out and let me know if it makes sense or if I’m missing anything.

Overview

  1. Block vs. Plugin Prompts: Separate prompts specific to block creation from those for the entire plugin.
  2. Variants: Allow different template variants, each with its own config and prompts.
  3. Non-Interactive Mode: Let users pass prompt values via the CLI for automation.

Proposed Design

  • Custom Prompts: Define extra prompts beyond the defaults from @wordpress/create-block.
  • Process Flow: Outline how prompts differ based on mode (standard or --no-plugin) and variant.
  • Testing Scenarios: Cover interactive and non-interactive modes in depth.

Next Steps

  • Implementation: Build out the API to match the proposed design.
  • Testing: Verify everything works as expected in all scenarios.
  • Documentation: Update any docs as needed.

Thanks for checking it out!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Tool] Create Block /packages/create-block [Type] Enhancement A suggestion for improvement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Create-block package: External Project Template Custom prompts?
3 participants