New Package: Gutenpride Template to use with the tutorial

[jessynd]

Description

This is a package to be used with @wordpress/create-block. It is a template to generate the completed Gutenpride block plugin based on the Gutenpride Tutorial.

How has this been tested?

This package was tested using an npm package published privately at https://www.npmjs.com/package/jsa_gutenpride_template. This is how to reproduce the testing with this template in the published version currently on npm, which is identical to the one in this PR.

1. Inside the gutenberg repository run npx wp-create-block --template jsa_gutenpride_template
2. Go through the terminal prompts to create your plugin from the template.
3. Take the generated plugin out of Gutenberg into the Plugins folder of a WP installation.
4. Activate the plugin in WP
5. Open the edit screen of a page or post and add the new block to the page.
6. You should now see an input box that you can type text into and it will be saved and shown on the front end of the page. You will not however see the font displaying. This is because the font has been removed by the create-block plugin.
7. To make the template work, download a fresh otf file and add it to the plugin folder.
8. Reload your page and you should see the font reflected now.

In order to fix the issue of the create-block template removing the otf font when it creates the plugin, I published an additional version of the template which has the .mustache extension added to the otf font. In this version of the template the font is there in the plugin but create-block modifies it and it doesn't work either. To test this one, follow the instructions above but run npx wp-create-block --template jsa_gutenpride_template_otf_with_mustache instead. Compare the otf font included in the plugin with the original font downloaded above from https://www.typewithpride.com in a code editor. You will see that the font is modified by create-block.

Screenshots

Types of changes

This is a new feature to work with the @wordpress/create-block

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.
• I've updated all React Native files affected by any refactorings/renamings in this PR.

[jessynd]

@gziolo The original intent of this package was to create a final version of the gutenpride template that would help showcase how third-party templates can be used with create-block. However, as you can see above, we encountered the issue of the otf font being either deleted or modified:

1. The font is deleted by create-block if it doesn't have the .mustache extension.
2. The font is modified by create-block if does have the .mustache extension, making it unusable.

I hope this draft PR might help troubleshoot this issue. Ideally it would be great for third-party templates, if developers could include files without a .mustache extension. This was a good experiment to help us figure that out.

[gziolo]

@jessynd thank you for all the fantastic work done so far! ❤️

You are 100% correct that assets like images or fonts don't quite fit to how it all currently works. It feels like we should either add another option in the block template package that defines the path to the folder with assets or use the convention where assets subfolder next to .mustache templates is copied over without processing. Option one seems to be less magic but it might create some friction when referencing those Can you think of any alternative?
Besides, it still isn't clear where we would need to move those assets in both cases.

[mkaz]

With regards to assets, I like the first option of having an asset folder that gets copied over. This seems quite straight-forward for some one implementing or using.

it still isn't clear where we would need to move those assets in both cases.

The assets would just get copied to the top level of the plugin that is created, right?

[gziolo]

Thanks @mkaz for sharing feedback. @leoloso and @fabiankaegy, do you have something to share as well?

I plan to look at adding support for assets in the template later this week. In addition to that, it would be great to add better support for assets in the default webpack config shipped with @wordpress/scripts.

[gziolo]

@jessynd, is the final goal of this PR to publish this template as part of WordPress npm packages? Assuming that all the listed issues are resolved.

[jessynd]

@gziolo and @mkaz thank you for your feedback! I agree that having an assets folder would be good.

The final goal of the PR is to publish it as part of WordPress as an example that can be referred to by developers wanting to develop their own third-party templates for the create-block package. It doesn't necessarily need to be this example, but since this is the block being used as an example in the create-block tutorial, it made sense that the third-party template could also match the create-block tutorial. I'm not sure if the tutorial will change given the ongoing discussion in #27565. If it does, the sample third-party template here could be adjusted to match that.

This template could also be referenced as an example in the tutorial on how to create third-party templates for the create-block package.

As a separate but related discussion: Have any decisions been made around how developers will be able to share third-party templates for create-block? Will there be an official naming convention for those wanting to share their templates to use when publishing to npm? If there will be, it will be good to replicate that in this example third-party template.

[gziolo]

I opened #28038 with an initial proposal for assets handling.

It can be tested with jsa_gutenpride_template_otf_with_mustache package withe the following modifications:

1. gilbert-color.otf.mustache -> assets/gilbert-color.otf
2. In index.js, there needs to be assetsPath added:

    },
    templatesPath: __dirname,
    assetsPath: require( 'path' ).join( __dirname, 'assets' ),
};

With those changes published to npm, you can try to run the script with the branch from PR:

npx wp-create-block --template jsa_gutenpride_template_otf_with_mustache

It might be still buggy as my first attempt reads the content of the file and writes it to the new file. I don't know if it will work with fonts since it was causing when using mustache, but I hope that this issue was coming from the mustache processing. Otherwise, I will have to rework the processing of the downloaded template package to be able to copy files instead.

[gziolo]

@jessynd, thank you for all clarifications. I agree that it makes sense to include the proposed template as another WordPress package published to npm from the Gutenberg repository. As long as we keep it in sync with the tutorial it would be an amazing way to make it easier to follow it along. The other benefit you mentioned is also nice, the ability to showcase how to create custom templates by the community 👍🏻

As a separate but related discussion: Have any decisions been made around how developers will be able to share third-party templates for create-block? Will there be an official naming convention for those wanting to share their templates to use when publishing to npm? If there will be, it will be good to replicate that in this example third-party template.

I don't think we should enforce any conventions but we could give a good example by picking the proper pattern ourselves. I personally always look at this from the perspective of how would I name the package to have a bunch of them colocated in the folder director. Some existing examples:

I don't think that there is a well-established pattern in the JavaScript community:

For our purpose it could be: @wordpress/create-block-template-tutorial or @wordpress/create-block-tutorial-template.

[jessynd]

Thanks @gziolo! Tested it here #28038 (comment)

[gziolo]

Impressive work, we are almost there. The last question is what do we want to name this package?

I left some proposals earlier. I would personally avoid using gutenpride because this template might change completely if one day we decide to use a completely different block in the tutorial.

[jessynd]

@gziolo I think the suggestion you made above for the block to be named either @wordpress/create-block-template-tutorial OR @wordpress/create-block-tutorial-template is great. My preference is @wordpress/create-block-tutorial-template

Should I change the folder name to create-block-tutorial-template and all the files gutenpride is referenced?

[gziolo]

Should I change the folder name to create-block-tutorial-template and all the files gutenpride is referenced?

Yes, that's it and we can look at merging this PR 🎉

[gziolo]

@jessynd, how about you rename the package and we merge it so I could open PR with some janitorial changes? Otherwise, it might be difficult to explain what to tweak. It's mostly coding style related, the structure of the template might require some changes. Anyway, it's something that we could divide easier once we merge this PR.

[jessynd]

@gziolo I have pushed the name change. Now the package is at create-block-tutorial-template and I've swapped out the name everywhere gutenpride was referenced.

[jessynd]

Thank you for all your help and support @gziolo, @mkaz, @fabiankaegy, @brezocordero, @rbest!! I learned so much working through this first PR. It's been a really eye-opening and exciting process for me. 🥳🙏❤️

[gziolo]

Let's merge it as is. I plan to apply some follow-up enhancements in a follow-up PR.

Major kudos to @jessynd for taking us thus far 🎉

[gziolo]

I have just opened a follow-up PR with mostly janitorial changes: #28215.