Adding a way to include Javascript or PHP snippets to Block Themes

[annezazu]

A broader conversation broke out in the nineteenth call for testing with the FSE Outreach Program that I wanted to bring here for a wider discussion and for awareness.

I think block themes need to rethink CSS, php, and Javascript customization based on the modern web, not on WordPress historical choices. I’d like block themes to have an (optional) theme.php and theme.js to complement theme.json. So I can add php and javascript snippets like seems to be underway in adding CSS snippets in theme.json. To me, modern Javascript (vanilla, no jQuery of old or React of block development required) is a natural customization feature for block themes.

The comment continues here with more context (trying to capture the gist right now).

On the flip side, @scruffian shared:

This doesn’t align with the way I see block themes. In my opinion classic themes have been stepping over the line from being a theme to being a plugin for a long time. This caused problems where user’s content became too tightly coupled to their theme. An example of this might be a theme that provides an image carousel. If I set that carousel up on my homepage and then switch to a new theme I will lose the carousel. Switching a theme should be a non-destructive action with respect to content – it should only change the appearance of the site, not the content. Block themes offer us an opportunity to refocus the function of a theme on the areas of responsibility that are the intention, which is to say on the presentation layer. For this reason I don’t support the idea of adding Javascript to block themes. The Javascript layer is about modifying the functionality of the page not the presentation, so I wouldn’t want to encourage users to do this within their themes. It seems like plugin territory to me.

In my mind this is plugin territory too but I wanted to open the conversation here in case I was missing something. I'd love to hear what @tadlock @DaisyOlsen think here as well as any @WordPress/block-themers. Either way, I imagine Rob isn't the only one wondering this and it seems wise to have the conversation now.

[robglidden]

Here is a specific use case I ran into, smooth scrolling. A "presentation layer" popular theme feature where you need both modern CSS and Javascript snippet to do right.

[annezazu]

Thank you!

[DaisyOlsen]

There does not need to be anything new in order to accomplish this. Block Themes have access to the same tools that classic does in this regard. A functions.php file with script/styles enqueuing would be the approach in both cases.

[robglidden]

Exactly, and what I said.

And that's the problem.

Please look a little further.

Maybe the title "Adding a way to include Javascript or PHP snippets" misleads. Talking about a way to customize with CSS, JS, and PHP.

Of course there does not need to be anything new in order to add CSS, JS, or PHP to a block theme in functions.php, just like in classic themes.

So block themes just perpetuate the same lack of customizing problems like overwritten-in-the-next-theme-update and "stepping over the line from being a theme to being a plugin", child theme clumsiness, etc.

Customize in the name of Gutenberg phase 2 to me means empowering the user of a theme to make changes. Not what a theme developer does to build a theme.

I think the heart of the issue is the dual use of functions.php by customizing users and builders/developers. A classic lack of "separation of concerns" -- different people or uses for changing the same file at different times and purposes.

Separating these two uses/time frames into different files would fix this and open doors.

Functions.php would live on. Customizers wouldn't get their customizations trashed by each theme update.

I am hoping this is clear in the original post?

[scruffian]

If you're extending a theme that you don't control, could you create a child theme and then add extra javascript using the functions.php in the child theme, which would be untouched by parent theme updates?

[robglidden]

Yes, of course, as mentioned in original post.

But that means on this block themes are no better than classic themes, just equally uncustomizable and past-facing.

And overall harder, because now you have to do both the older harder stuff and the newer easier stuff, not just the new stuff. Easier user customization is the whole point of Gutenberg phase 2 after all, not just adding onto the old hard ways.

The site editor is adding back in CSS customization, recognizing that CSS is a valid user customization feature for modern WordPress.

I am just suggesting the same logic for adding Javascript and PHP customization.

And with the modern Web, there are far more reasons that Javascript is a great, and sometimes necessary, customization option.

Also as mentioned, modern module loading (import) would be a snap, compared to the classic complications of enqueueing modern JS modules, which were not by default module-enabled. That would open new customization options for theme developers to provide for users.

[t-hamano]

I’d like block themes to have an (optional) theme.php and theme.js to complement theme.json.

I may not understand exactly, but I don't understand why such a file is needed to customize a block theme with PHP/JS/CSS.

Instead of the block theme having a file called theme.php, maybe you could add a snippet in functions.php? If you need your own JavaScript or CSS, you will be able to enqueue those files. Of course, this could be accomplished with a plugin or child theme.

As I understand it, one of the goals of Gutenberg Phase 2 customization is to make it possible to customize the entire site without having to write HTML/PHP/CSS/JS code, not to make it possible to customize it with code.

If you encounter a case that cannot be achieved without writing code, and it is desirable to be able to achieve this without writing code, or if you consider that to be the presentation layer, then I think it is a good idea to propose this as an issue. If not, or if the current Gutenberg cannot handle the case, we may have no choice but to use the old method, as mentioned in the previous comment.

[robglidden]

I may not understand exactly, but I don't understand why such a file is needed to customize a block theme with PHP/JS/CSS.

WordPress 6.2 is already adding this kind of customizing for CSS.

You can customize CSS in the UI (in a text box) both CSS globally, and per block.

I am simply proposing a similar text box in the UI for also customizing JS and PHP.

A theme.php and theme.js just seems a more natural implementation than theme.json, which CSS customizations will use.

Instead of the block theme having a file called theme.php, maybe you could add a snippet in functions.php?

Yes, but users should not put their customizations in theme.php, because they will get over-ridden in the next theme update. True in both classic and block themes. The classic "lack of separation of concerns" that would be easily fixed.

One can use a child theme, plugin, or a third-party snippets plugin, but each adds its own unnecessary complexity. Basically, a theme user is being asked to use the more complicated tools of a theme or plugin developer to do the simple step of adding a snippet.

If you need your own JavaScript or CSS, you will be able to enqueue those files.

Yes, but it is not "customizing" through a text box in the UI, like 6.2 is already adding for CSS.

And enqueueing modern Javascript modules is not built in -- though you can get there with the script_loader_tag filter. This is even more unnecessary complexity to a simple task.

As I understand it, one of the goals of Gutenberg Phase 2 customization is to make it possible to customize the entire site without having to write HTML/PHP/CSS/JS code, not to make it possible to customize it with code.

Customizing with CSS is already in scope and is being added (back) in WordPress 6.2 with a text box in the UI.

I am just saying I'd like the same for Javascript and PHP snippets, as they are also user-loved customizations.

If you encounter a case that cannot be achieved without writing code, and it is desirable to be able to achieve this without writing code, or if you consider that to be the presentation layer, then I think it is a good idea to propose this as an issue.

Yes, this issue is that very issue proposal.

I pointed out one such case above, smooth scrolling, typical of modern CSS/JS presentation features that require both CSS and JS to do right.

There are countless ways to use modern CSS, JS and PHP, there is no way they will all be quickly, or even ever, added to Gutenberg. This is why 6.2 is adding CSS customization already.

If not, or if the current Gutenberg cannot handle the case, we may have no choice but to use the old method, as mentioned in the previous comment.

Why use an old hard method if a new, easier, seamless, and more customizable method could be added? Isn't this the very philosophy of Gutenberg in the first place?

[aristath]

I am simply proposing a similar text box in the UI for also customizing JS and PHP.

My 2c: This should not, under any circumstances, happen in WordPress-Core, for a very simple reason: Security.
If such a box is added in Core, then users who shouldn't be messing with this will start adding snippets they found in random places online. Sites will break. Sites will get hacked. Vulnerabilities will be introduced to sites by users who don't understand what they're copy-pasting. Such functionality can be done in a plugin, but not in WordPress-Core.

[robglidden]

Core already has such a text box, the Theme File Editor. That is what I am saying shouldn't be the (only) go-forward way in the site editor and block themes.

And code snippets are pretty universally recommended, by Woocommerce, Jetpack and the WordPress Codex, among countless examples.

Doing this in the site editor would be more secure with revert-ability from the database like the rest of the site editor and block theme styles. And in 6.3, revisions for theme tools like styles is slated, an even better way, likely in phase 3 enabling better permissions/user role workflows across the board.

So better, not worse, security. Site editor and block editor are great, and worth moving forward with rather than hanging on to old harder, and less secure ways.

[aristath]

I'm having trouble understanding what the issue is exactly here.
Is the problem that block themes don't provide enough customisation tools? Or is it that theme-authors have too much freedom to customise things?
Themes can:

• Add custom CSS on a per-block basis, to customise how a specific block looks
• Add custom JS on a per-block basis, to enhance the behavior of that block for that theme
• Use PHP in functions.php to do whatever they need to do (including but not limited to adding the custom CSS/JS mentioned above for specific blocks).

Adding plugin-territory features in themes is strictly forbidden and themes that do that are not allowed in the w.org themes repository. However, we have no control over what developers do in their custom themes... Nor should we. If someone builds a one-off theme for a client and they want to add site-specific functionality to that theme instead of a plugin, WordPress has no business forbidding that.

[robglidden]

I'm having trouble understanding what the issue is exactly here.
Is the problem that block themes don't provide enough customisation tools?

Yes, that is the problem.

Block themes do not provide any customization tools for users to easily add and customize Javascript and PHP.

This was also the case for user customization tools for custom CSS, but they are now being added in 6.2.

Of course, this CSS feature exists in the customizer, but up until 6.2 not in the site editor and not on also on a block-specific basis.

So users are expected to keep reusing the old, hard ways of repurposing theme and plugin developer mechanisms that would be much easier to do in a "text box in the site editor" like 6.2 is doing for CSS.

Or is it that theme-authors have too much freedom to customise things?

I think this was brought up as a reason to not make customizing with Javascript and PHP easier in the site editor. On the theory that if it were even easier for a user to customize Javacript and PHP in a theme's site editor, it would open up misuse or behaviors to be discouraged.

Themes can:

Add custom CSS on a per-block basis, to customise how a specific block looks
Add custom JS on a per-block basis, to enhance the behavior of that block for that theme
Use PHP in functions.php to do whatever they need to do (including but not limited to adding the custom CSS/JS mentioned above for specific blocks).

"Themes can" are theme-development mechanisms. Not theme customization mechanisms for users in the site editor.

In 6.2, users will now be able to customize CSS on a global and per-block basis.

Excellent user-oriented improvement, even though users could already use the hard old ways to add CSS (functions.php, child themes, custom plugins, snippets plugins, customizer).

I am just proposing that users should also have an equivalent as-easy-as-a-text-box-in-the-site-editor way to customize JS and PHP.

Doesn't that make sense?

Several collaborator/maintainer comments seem orthogonal, and seem to just argue the old ways are available, good enough, or surprisingly unchangeable.

And don't even consider "if customizing CSS, also customize JS and PHP".

Modern JS and CSS are linked at the hip -- customization in the modern Web isn't just CSS any more. And PHP snippets have been long used, they are just not customizable in the site editor.