Secret WordPress core feature: subdirectory

szepeviktor commented 4 years ago

If one is having a lot of development files in the root, or just to tidy up things: core finds theme files in a subdirectory!

I propose /template

szepeviktor commented 4 years ago

E.g. the starter theme has:

.gitignore
.travis.yml
LICENSE
README.md
composer.json
humans.txt
phpunit.xml

gchtr commented 4 years ago

@szepeviktor I never looked at that function in detail. But what do you mean exactly? What files or folders should we move where? 🙂

szepeviktor commented 4 years ago

theme files will have their own subdirectory
development files (mainly configs) will remain in the root
non-theme files may also have their own subdir, e.g. src/ for PHP classes

gchtr commented 4 years ago

What I think the function you linked means is that you could move the whole theme into a subfolder. So instead of

wp-content/themes/getting-started-theme

you could have

wp-content/themes/subfolder/getting-started-theme

But it’s not possible to move template files like index.php and single.php from the theme root folder to a subfolder just like that. WordPress needs at least an index.php as entry point for templates files. And I think we mostly follow the WordPress default here, see the Template Files section in the Theme Developer Handbook. It seems to me as if most WordPress themes work like that and developers are used to it.

But I totally agree that it’s not very clean to mix template files with other config and development files 👍.

szepeviktor commented 4 years ago

wp-content/themes/subfolder/getting-started-theme

Nooooooooooooooooooooooooooooooooooooooooo! :)

WP files: wp-content/themes/getting-started-theme/template/index.php

other files: wp-content/themes/getting-started-theme/composer.json

gchtr commented 4 years ago

WP files: wp-content/themes/getting-started-theme/template/index.php

I checked this, it doesn’t work 😉. At least not by default.

szepeviktor commented 4 years ago

It works. Please see https://github.com/WordPress/WordPress/blob/89e99f57a2a175ccb75282d1a7eefb0bfce94bcb/wp-includes/theme.php#L515

But if you have the theme active you must switch to another one and switch back.

szepeviktor commented 4 years ago

and of course require_once dirname(__DIR__) . '/vendor/autoload.php'; in functions.php

gchtr commented 4 years ago

Please see WordPress/WordPress:wp-includes/theme.php@89e99f5#L515

That’s exactly what I mean! This function figures out which themes are available, but not which template files. I can put themes in subdirectories, but apparently not template files.

But if you have the theme active you must switch to another one and switch back.

If I move the index.php file to wp-content/themes/getting-started-theme/template/index.php, then the theme isn’t even listed in the WordPress’s theme settings and I can’t switch back to it. That’s because each theme needs an index.php to work.

The logic that figures out which template to load is in wp-includes/template-loader.php. And the function that actually figures out which file to load is locate_template(), and it is not looking into subdirectories.

I don’t know how you do it, but I really can’t get this to work, even with

require_once __DIR__ . '/vendor/autoload.php';

😊

szepeviktor commented 4 years ago

Okay! I send a PR...

gchtr commented 4 years ago

Oh, of course! You put all WordPress related files in the template folder, including style.css and functions.php 💡. Now I get it!

I’ll keep the discussion in here and not answer in the pull request.

We should figure out what to do with views!
1. keep it in the root

2. move it to `template/`

The views folder should still work if you’d put them in template, because of the load order in Timber, which is defined in this Guide. There might be side effects for other files and functions we didn’t think about yet and which might not even surface, even if we try to test it thoroughly.

Suppose if you have asset files, you could have them in the theme root folder and build them to the template/build or template/dist folder. Or put them in template as well.

I’d rather use the name theme instead of template, because in WordPress, templates are mostly template files for the Template Hierarchy.

I kinda like the idea 👍. However, I still feel like it might be confusing for developers, if we use a structure like this. For a low-entry level theme that shows how to transition from a WordPress theme to a Timber theme, I think we shouldn’t do it. But we could maybe do it for the Starter Theme. Or we could document this in a new Guide.

I wonder what @jarednova thinks about this.

szepeviktor commented 4 years ago

low-entry level theme

I cannot argue with this low thing :) One must be irritated by the mixture of files with very different purposes in 1 directory.

Suppose if you have asset files, you could have them in the theme root folder and build them to the template/build or template/dist folder. Or put them in template as well.

Yes this subdir opens a wide spectrum of possibilities!

gchtr commented 4 years ago

One must be irritated by the mixture of files with very different purposes in 1 directory.

You’re right. I can’t say anything against that either 🤷‍♂️😄

jarednova commented 4 years ago

Just catching up on this. I agree that it's something to look into, but in the starter theme and not the "getting started theme." Now that we have two, I think this will make it easier to separate their goals.

timber/getting-started-theme (this repo) is meant to link up to the Getting Started section in the docs. It should be as minimal as possible to introduce the main Timber concepts in a way that's recognizable to people w some WordPress knowledge.
timber/starter-theme to showcases the current best practices in building a site with Timber. It should remain current with the features of the most recent version and provide a strong example which to base theme development work from.

Based on this I think there are two action items:

Clarify the name. Since the "getting-started-theme" is the new kid on the block, I think we should find a more differentiated name: setup-theme? basic-theme? base-theme? for this repo
Let's move PR #3 into starter-theme; this will also give us a chance to totally rectify templates vs. views for Twig files. In that PR we can debate and come to an agreed-upon names for all the appropriate directories

szepeviktor commented 4 years ago

Okay.

In that PR we can debate and come to an agreed-upon names for all the appropriate directories

I've totally forgot about that 22 day old PR!

gchtr commented 4 years ago

1. Clarify the name. Since the "getting-started-theme" is the new kid on the block, I think we should find a more differentiated name: `setup-theme`? `basic-theme`? `base-theme`? for this repo

I see. The term "start" might be confused with Starter Theme. But if we’d call it something like "base", then I would assume there’d also be a base with Timber code. But actually, we start with WordPress code, like here:

https://github.com/timber/getting-started-theme/blob/135e3362725049fcb250b636dd0e68229e5a53ae/single.php#L1

Maybe we could use one of the following names:

tutorial-theme
introduction-theme

What do you think?

szepeviktor commented 4 years ago

To me tutorial-theme is very similar to getting-started-theme.

How about learn-timber-theme ?

jarednova commented 4 years ago

@szepeviktor I think Learn Timber is 👍. Speaks to the purpose (and also helps to make me think of some good places to take it next).

@gchtr you got the ball rolling here so wanted to make sure you were on the same page before proceeding

gchtr commented 4 years ago

@szepeviktor @jarednova I like «Learn Timber Theme» / learn-timber-theme 👍.

I’ll make sure to update the name in all places.

szepeviktor commented 4 years ago

Let's go!

szepeviktor commented 4 years ago

Done.

https://github.com/timber/learn-timber-theme/blob/master/composer.json#L2

timber / learn-timber-theme

Secret WordPress core feature: subdirectory #1