How to sync edits made within a theme's files to the Block Editor (Full-site editing)

[skorasaurus]

As I experiment with the theme editor more, I realize that there's still a lot of aspects of the theme editing process that haven't been already articulated yet in the theme outline. Since the editor is a remarkable change in WordPress, articulating these decisions, is important to minimize distrust and skepticism, and provide direction to theme developers.

We should still be able to edit theme templates and other theme files through a separate file editor outside of Gutenberg and have those changes immediately reflected in the theme.

You're taking away a long used feature by theme developers and agencies that manage a site's theme by modifying files within a separate file editor (e.g. vs code, sublime, vim) and have those changes immediately visually reflected in their site.

Several use cases that this file-based editing and syncing enables or facilitates:

• quicker version control of themes (I don't think this can be understated).

• Automation: By ensuring theme files are file-based and any changes to theme files are immediately applicable to the website; theme changes can be made in a separate environment and they can be quickly deployed to the production website through a variety of means: Gitlab/Github actions, travis-ci, rsync, FTP, etc; without altering the database.

I do this pretty often; for example, tweaking a template php file (e.g. removing a sidebar) on my local environment and then upload template file by FTP; instead of directly editing on production.

One simple use case of what I am asking is to be able to modify a page template that's exactly the same as an existing one, remove the footer, or add sidebar blocks to that template without having to make several clicks through the GUI.

I understand that there are separate audiences for Gutenberg:
one of those audiences are users who aren't comfortable with even basic html and would solely use gutenberg but there are also many users who are more comfortable through separate file based editors.

The flexibility of WordPress is a key reason why WordPress has managed to be relatively attractive to users across various levels of technical ability with differing preferences.

Being able to edit the layout of your website through a GUI like the customizer and widgets screen as well through a separate file editor is one great example.

Related issues: #43395

https://developer.wordpress.org/block-editor/explanations/architecture/full-site-editing-templates/

(speaking personally, not as an CPL employee).

[vindl]

One simple use case of what I am asking is to be able to modify a page template that's exactly the same as an existing one, remove the footer, or add sidebar blocks to that template without having to make several clicks through the GUI.

Would this be fulfilled by having the code editing mode available in the site editor? (#22528)

Currently those edits would be saved in wp_template CPTs, although we could look into saving them alongside block template html files that themes provide. I'm not sure if editing the default ones is the best way to go about it since those changes might be overridden during theme updates.

[skorasaurus]

One simple use case of what I am asking is to be able to modify a page template that's exactly the same as an existing one, remove the footer, or add sidebar blocks to that template without having to make several clicks through the GUI.

Would this be fulfilled by having the code editing mode available in the site editor? (#22528)

Currently those edits would be saved in wp_template CPTs, although we could look into saving them alongside block template html files that themes provide. I'm not sure if editing the default ones is the best way to go about it since those changes might be overridden during theme updates.

Although the code editing mode in the site editor, I'm afraid this would not be really fulfilled by code editing within the site editor.

While I occasionally use the code editor (and it's helpful!) to make small edits to blocks, a couple common use cases that the code editing mode in the site editor wouldn't be applicable:

• need to make a new template that's identical to another template but the new one doesn't have a sidebar.

With FSE:
log into the website; go to the template editor, copy the block code; create a new template; then copy in and save as.

With local file-based editing:
I can open my local file editor, open the template file, remove the lines of code, save as a new template with a different file name (and commit it to a git based repo), and upload to my theme on production (which I can do with a one line alias in my local developing machine).

How are larger agencies and enterprise-like companies working on this? I can't imagine that they are making edits of site design and templates directly live on production nor should you to expect them to do that.

[carolinan]

I don't understand. I don't read any distinction between the different kinds of templates and template parts above.

Are you saying that local file based editing is not working? At all? Are changes you make not reflected in the templates?
This has been buggy for me in different plugin versions but seems to work well now.

-I don't see what could prevent you from editing the .json file for global styles.

Or, did you mean that local file based editing does not work after you create/save a template/template part in the site editor (Because no local files are created)?
-The files are not created until you use the export functionality.

[skorasaurus]

At the time that I created the issue, I hadn't found any documentation whether local file based editing + syncing would be supported at all since I had read that edits made to templates within the GUI site-editor #19260 had to be exported to local html files.

I was wondering whether local edits to a theme's html files would be automatically applied to the theme at all or if I had to go into the site-editor GUI to import any changes made to the html files locally.

[carolinan]

Does it mean the issue is resolved?

[vindl]

I was wondering whether local edits to a theme's html files would be automatically applied to the theme at all or if I had to go into the site-editor GUI to import any changes made to the html files locally.

I think I understand the gist of the issue better now. Yes, edits to theme's template and template part html files should be reflected both in the editor and in the fronted. There is one caveat though - if these have been modified within site editor and saved as CPTs (wp_template or wp_template_part) these will override the default theme html files so the file changes would not be visible.

So local file based editing and syncing will work as long as those CPTs are not present. It's entirely possible to change everything related to theme provided templates and template parts just by editing the files, without the need to access site editor.

[pagelab]

So local file based editing and syncing will work as long as those CPTs are not present.

This means that, in practice, a theme is just a starting point. That's an issue if the theme code needs to be updated in a way that is not possible using the UI.

For example: at the moment the UI does not allow me to add a data attribute to any tag. If, for any reason – technical or whatnot – I need to update the theme to add it, the update will not be applied if its CPT counterpart has been changed.

In order to apply it, the user will either have to delete his/her version of the template or change the structure manually, using the code editing mode, which can be cumbersome.

I'm sure that there are other cases where the ability to update the site code via a theme update would be quite useful.

The new block system is awesome in a lot of ways, but this issue is a downgrade in user experience compared to the current theming system, IMO.

Developers will lose direct control over the actual code used to render the site, and the responsibility for applying changes to the code that are not possible using the UI will be transferred to the user.

[vindl]

For example: at the moment the UI does not allow me to add a data attribute to any tag. If, for any reason – technical or whatnot – I need to update the theme to add it, the update will not be applied if its CPT counterpart has been changed.

That's right. This is a hard problem to solve in general. I don't think it would be good to completely overwrite CPT content during update, because that will change the site layout and remove any user created template customizations.

In some cases the element that you want to update might have been removed via UI customizations, so changing it would no longer be a concern. In others when it's still present in CPTs, we don't have a way to differentiate theme supplied blocks from the ones added by users afaik. So solving this would require merging the two template contents (updated one from the theme and CPT) in a seamless way, but that too can fail in general case due to merge conflicts which require manual intervention.

I'm curious if you all had some ideas of how this could be resolved?

[pagelab]

I don't think it would be good to completely overwrite CPT content during update, because that will change the site layout and remove any user created template customizations.

Maybe a solution is to adopt the Revisions system for every template, including the ones provided by the theme. This could be similar to what already exists for the content of regular posts.

At least the user should be able to revert to the default version of the template without removing its customized version first. This would allow for more flexibility compared to the current system.

[iandunn]

#36008 might help to solve the updating problem, since certain parts of a template could be locked, while others allow user edits.

Locked parts could always be loaded from the file system, while unlocked parts could be loaded from the db if the user has made changes.

[caraya]

I'm curious if you all had some ideas of how this could be resolved?

I think we're mixing two cases in this issue: preserving user changes and the need for theme authors to have an easier way to make changes to a theme under development.

Perhaps having a create-theme mode would help. In this mode, all the changes are automatically reflected in the matching template file and changes made on the template files are automatically reflected in the FSE and the front end.

This would have to be opt-in as it would ignore the CPTs containing user-made changes.

[skorasaurus]

Ran into this again as I was working on a theme locally, added a color palette to the theme.json file; and uploaded to FTP remotely to a the theme's folder on the site; the changes in the theme.json were not read remotely.

[caraya]

Ran into this again as I was working on a theme locally, added a color palette to the theme.json file; and uploaded to FTP remotely to a the theme's folder on the site; the changes in the theme.json were not read remotely.

This is the expected behavior. Modifications to a theme are saved as CPTs and not directly to the files on the server

It's always been possible to create a zip of your theme with all the latest changes. it requires manual action

1. Go to the menu (three vertical buttons on the top right of the editor screen)
2. Under tools select Export

This will create a zip to download. You can open it and use the files in the export to update your remote site.

[leonardola]

@skorasaurus I've just opened the issue #53249 because I need it to work the other way around. Save the changes in the WordPress editor and make them show up in the file.
While testing I noticed that what you need actually works on my side. All I had to do was to revert the template in wp-admin changes back to default before WordPress started to pick the changes from the file.

To do this I went to: Appearance > Themes > Select the theme > Click Customize > Templates > Manage All Templates > Click the ellipsis in the template > Click Clear Customizations. This might vary depending on which template file you are editing. I don't know how this would go for theme.json for example.

After doing this all changes to the template file I made using VSCode reflect in the site right away. No need to do anything in wp-admin.

[carolinan]

Can we either close this issue or re-write it to explain a single actionable point?
It is four years old, and the tools have changed, and how developers work with block themes have changed.
There is still a need for version control of the theme files, but reading the older discussions in this issue is confusing.

[caraya]

Go ahead and close it, there's no need for this annymore

[skorasaurus]

Yes, there have been a lot of changes.

As I understand and know:

• Theme changes made in the browser aren't instantly reflected in the installation's theme's files; changes are only saved to the database. Theme changes need to be manually exported through create-block-theme's export feature, then unzipped (and overwritten) in the existing installation's theme's folder. (If there is a way to automate this, this would be great but I don't think this is yet possible).

(This is just as much for me to learn, for my own reference):

To learn:

• When changes to a theme's files are made; are they instantly read and activated by the site editor ?
  (e.g. I update my site's footer.html file ; can I refresh my website and the changes to the footer appear on the front end) ?

• When I make updates to a theme on a local instance (e.g. creating a new block pattern; new template; or modify an existing template); how can I migrate those changes to my production level website that have the existing (older) theme installed ?

Further discussion about this can be found at #59480