[meta] Discuss the organization of subfolders in Classy

I've created a google spreadsheet with all of the templates in core (as of Oct 3, 2014). https://docs.google.com/a/albin.net/spreadsheets/d/1QPh_2_zZnbgg3IKzMMJ2...

We can test out different classifications to see which ones work best. So far I have a admin page/front-end forms/other classification. More classifications can be added.

my suggestion for a folder stucture:

As a general stucture:
classy/templates/[module-name]/template.twig.html

in the case of the "system" themes i would suggest that we catagorized em in sub folders like "form", "system", "markup-elements" etc

For now it seems pragmatic to deal with them all the same as mentioned above by mortendk

classy/templates/[module-name]/template.html.twig
Is a straight forward pattern to follow and can be broken up further later.

It's even scriptable.

I agree, also its consistent between core modules and classy.

After playing around with classy a little bit i began to rearrange templates into folders that make "sense"
so all form templates got into system/form/ all markup elements got moved into system/elements etc.

It do give a question of the logic, how strict do we wanna map up against drupals modules.
Does it make sense for a themer to look at the template on a "drupals way of thinking" or would it make more sense to move all blocks out into one folder (blocks) and catagorize it more by its function.
The majority would still be in a modulename folder, but we would then move "form" from template/system/form to template/form

Anyways heres a first patch to move the templates, lets get to work and figure out a sane way, without using to long on this :)

The distribution of templates between core's modules never made a great deal sense to me. So many templates are stuck in system, and it's not entirely obvious to somebody new to Drupal why.

So if there were a relatively straightforward way to group templates beyond the core module structure, I'd say go for it. However, I imagine that's a topic that is eminently bikesheddable, which is the opposite of what is needed right now.

Sensible groupings within the system folder might help at least.

After thinking about it a bit this night/morning i do think we need to go back to one of the basic concepts that we agreed upon all the way back at frontend united in amsterdam, the following sword of concensus discussion in san francisco & then the consensus banana (phew so many discussions)

We are building classy for themers, so they have an ideal starting point - we can seperate the markup from drupal into the theme, make it easy and all that (!)
Following a strict a modules template goes into the folder, makes little to no sense, when you look at it from a theme perspective.
as an example:
I wanna retheme the menu would I then expect to look in theme/system/menu.html.twi or would i look for theme/navigation/menu.html.twig Do we want rfd templates in a folder? When in reality its a "minor" element - sorry RDF geeks, but it kinda is ;) or should that live in a "various" folder, that gives me a pretty good idea where to find the "little things" (rss icon fx)

We wanna make it easy for the themer to find what s/he needs to work with, not what the module's name is (the folder name which in this case system)
So lets use a couple of judgement calls and make it a bit more simple to find whats needed based on a themer persective.

I have rebuild classys organization a bit more, to reflect some of these thoughts & to get feedback (or an RTBC)

Basic concepts:
* No more than one level of folders eg: classy/templates/folder/template.html.twig remember this is also a starting point for alot of themers (+ theres a potential issue with extend & finding templates, as seen in bartik (see patch)
* Judgement calls . follow drupal module structure, unless it make sense to move things around (ex: collect all forms templates into one folder: "templates/form"
* a folder for "all the little things that dont fit anywhere else" atm: "various" could be "other" or "stuff"
* templates/admin : theres things that are more related to admin elements (messages.html.twig)

Please dont bikeshed If a folder is called various or other or stuff-we-dont-know-what-to-call. Dosn't really matters, what matters is that we agree upon basic concepts. If dont end up gettting anything done then classy/templates/system/ is a cluster, just cause somebody wanted to start 3rd world war over a folder name ;)

Some good stuff, some debatable.

1. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/system/progress-bar.html.twig
   
   rename from core/themes/classy/templates/system/progress-bar.html.twig
   rename to core/themes/classy/templates/admin/progress-bar.html.twig
   

   I use progress bars outside of admin.

2. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/system/status-messages.html.twig
   
   rename from core/themes/classy/templates/system/status-messages.html.twig
   rename to core/themes/classy/templates/admin/status-messages.html.twig
   

   Admin vs system vs various... not so keen with those.

3. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/system/item-list.html.twig
   
   rename from core/themes/classy/templates/system/item-list.html.twig
   rename to core/themes/classy/templates/elements/item-list.html.twig
   

   This make sense, though bigger thing is elements shouldn't be templates files, that seems a bit wasteful (I know, I know, that's the plan but it does still seem that way)

4. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/system/select.html.twig
   
   rename from core/themes/classy/templates/system/select.html.twig
   rename to core/themes/classy/templates/form/select.html.twig
   

   I do like these form ones a lot +1!

5. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/system/block--system-menu-block.html.twig
   
   rename from core/themes/classy/templates/system/block--system-menu-block.html.twig
   rename to core/themes/classy/templates/navigation/block--system-menu-block.html.twig
   

   I like these but I'd also consider a block/ folder

6. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/system/table.html.twig
   
   rename from core/themes/classy/templates/system/table.html.twig
   rename to core/themes/classy/templates/table/table.html.twig
   

   Going to be a lonely folder.

7. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/system/feed-icon.html.twig
   
   rename from core/themes/classy/templates/system/feed-icon.html.twig
   rename to core/themes/classy/templates/various/feed-icon.html.twig
   

   Aggregation maybe?

8. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/system/indentation.html.twig
   
   rename from core/themes/classy/templates/system/indentation.html.twig
   rename to core/themes/classy/templates/various/indentation.html.twig
   

   Various?

9. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/rdf/rdf-metadata.html.twig
   
   rename from core/themes/classy/templates/rdf/rdf-metadata.html.twig
   rename to core/themes/classy/templates/various/rdf-metadata.html.twig
   

   I'd leave this in rdf.

@joel:
so what i read is:
progress bar move to “other"
table move to "other"
feed-icon move to aggregator with the other rss stuff
leave rdf even that is a very lonely tempate in a folder ?

- not so happy about admin/various/stuff whatever we call that bucket

The reason to move block--system-menu-block.html.twig to "navigation" is that is a nav element, but yes can go both places.
But like we keep field's that are based only for there for a node field--node--created.html.twig inside the node folder, it make sense to keep all the basic navigation elements one place ?

Maybe we just leave admin/various/stuff in system still a better grouping comes along? Then we don't force it to yet another generic mislabeled bucket.

Dont we then end up with system being a horrible misnames bucket (stopped myself for bikesheding)
- but yes could make sense, to use that as the place we drop stuff into, as thats where we still have templates left in system that havent been moved to classy.
I could live with a concensus around "dont move stuff to folders untill theres enough & with a name that makes sense" rule

System has become that grab bag, if we can move stuff out, like the form stuff, I say let's do that! Don't need more than one grab bag folder though unless there are very clear and understandable rules to when to use which.

+1 on that system is the bucket ;)

Heres 2nd stap on the reorganization - removed "admin","various" & "element" as they all are new buckets for stuff - so we keep that in system until those templates can live a better place

These are the only concerns I have, everything else I'm +1.

1. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   @@ -1,4 +1,4 @@
   -{% extends "@classy/system/block--system-menu-block.html.twig" %}
   +{% extends "@classy/navigation/block--system-menu-block.html.twig" %}
   

   'block' would probably make more sense for this don't you think?

2. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/system/block--system-menu-block.html.twig
   
   rename from core/themes/classy/templates/system/block--system-menu-block.html.twig
   rename to core/themes/classy/templates/navigation/block--system-menu-block.html.twig
   

   same, block.

3. +++ b/core/themes/bartik/templates/block--system-menu-block.html.twig
   similarity index 100%
   rename from core/themes/classy/templates/rdf/rdf-metadata.html.twig
   
   rename from core/themes/classy/templates/rdf/rdf-metadata.html.twig
   rename to core/themes/classy/templates/system/rdf-metadata.html.twig
   

   I'm ok with it having it's own folder.

RDF template is one file, it haven't deserved its own folder + its probably not one of those that a themer is gonna play with everyday ;)
moved the "blocks" into block/

* Moved field-formatter/link-formatter-link-separate.html.twig into tempaltes/field as its a formatter for a field.
* moved seach block up to the other blocks, to keep them all in one place
* moved search-results & taxonomy-term into system as the bucket folder

proposal of classy #4

I love this, here are my 2 cents:

• Should region.html.twig perhaps go into the page folder instead of system?
• I personally would not think of looking inside system to find the taxonomy-term.html.twig file, but then again I cant think of a better place, since this is the only twig file for taxonomy module..

.

Perhaps something like this? Not too convinced either, since perhaps themers don't think in entities, but well, just an idea...

• /entities/taxonomy-term.html.twig
• /entities/user/
• /entities/node/
• entities/file/
• entities/image

@manul: Region template could go both ways. I have no preference over the other, bit yes region could live in /page/ as they are deeply connected there so it make sense

Lets not do nested folders (classy/templates/entititues/...) - it will make it harder to navigate (not good TX) & probably end up with a headache when we begin to do twig extend -lets keep it simple.
Another thing do anybody beside a Drupal Developer use entities when they talk about an image, a field a node, a user ? lets just call it for what it is in the template folder.
templates/node -> "aaaah theres my node templates" So yes themers dont think in entities: they see a pretty picture with a unicorn :P

Heheh makes sense @mortendk - This has my +1 now

- block-list.html.twig is not a "block" template, its a "block-list". its used for the block layout page Yes the template name is confusing & we should clean that up (in another issue).
when we one day have a /admin/ folder it should go there untill then it lives in the system bucket

-field templates that are only targeting on a specific type should be grouped together with that type (ex node)
A field template that changes a global element should be group in the global fields.
Your only theming "field--node--title.html.twig" when you theming the node, thats theming experience.

- the field formatter is only targetting global fields, so it make sense its in /field/

Maybe it doesn't make sense for a newbie but they have to learn somehow...

block-list isn't a block it's a part of an admin listing page (unfortunate name), so it shouldn't be in the block folder, and link-formatter is a link field formatter so it templates a link field so field is a good place for it. Those are logical as they are, I'd leave them.

Im not assuming any Drupal coding skills - i am though assume knowledge of how theming works (template overwrites etc)
The model of using module names as the only way to organize templates is not usefull (ex: all form related templates would not be in a /form/, but spread all over)
Just going with core is not an ideal solution, it makes no sense in a theming world, which have been one of the issues we have had for years - yes its the easy way to do it - but we can do better than that & status quo is not good enough

I read it as If the 2 real issues you have here:
1. block-list (thats only used for admin stuff should be in /block/ instead of in system)
2. a field formatter, that could also live in "system"

People will do whatever they will do. In Drupal7 we had introduced the BAT css naming scheme, and nobody was following them, so that wont keep me up at night ;)

We are not gonna find a perfect solution, but this solution is a ton better than just moving to a folder cause that module created it.

But learn what?

"Formatters format fields" and "block-list isn't for blocks", those are the lessons to be learned

We have theme debugging tool to tell us where a template lives - so the fear of not finding a template is not a real concern.

The usecase for me is this:
1. Start up a new theme -> copy classy to my local
Cause you want complete control over the markup, but you dont wanna write it all from scratch (as we know about 2/3 wanna do)
I dont wanna use my day to day time looking for templates, i just want em all, so i can get my stuff done and be awesome.

2. Open up the new theme looking at the file structure
Does the structure of the templates make sense compared to the work im gonna do ?
So yes if im gonna work on the RSS stuff it makes alog of sense to look into aggregator folder.

What i wanna know is from themers what they would like the better :) and what the usecases are.

This is not the end all be all file structure, but starting on a reorganization is needed, especially when we get the next bunch of system & views in
(and yes all views templates would probably go into one big folder, cause thats how we do it in drupal & it would make sense)

The way I see classy being used rather than copying it over as a starter theme, is for it to be the place where you grab the template files to override them.

Since if you don't inherit from classy, your theme would get no CSS classes from core, I really don't see the point in copying all classy templates into my site's theme.

In my mind, d8 theming would be:

1. Create a new theme from scratch (or subtheme of my liking)
2. Copy over twig files that I need classes on.
3. Theme.

So instead of browsing all around core for the proper twig file, you can just find it in classy.

That is the only use case I can see for classy, at least from my point of view. Of course others might choose to inherit from it, but well...

well lets get a bunch of themers in an weight in on it, lets see where it goes.

Might be a good idea to post a pointer to this discussion at g.d.o/core to get more visibility on this issue. (That gets syndicated to Drupal Planet, Twitter, etc.)

Anyone in MAINTAINERS.txt should have access. If you don't, ping me in IRC.

Oh, and before that, probably update the issue summary so people don't have to read 40+ comments to understand what's being proposed. :)

yes i was thinking of the exact same thing, need to clean it up a bit

I'm not a front-end developer, so my opinion here shouldn't count for much, but +1 to the "form" and "navigation" directories as a way to make the "system" directory have fewer files. I'd also be +1 to adding those as subdirectories in core/modules/system/templates/ if we want to maintain parity there.

As to the other reorganization, I don't quite get why block-list should move out of block, but image-widget should not move out of image, but it's not really important whether I get it, so long as themers get it.

A quick background: I'm both a developer and a themer, so I cannot claim complete understanding of the specialized themers or back end developers. I have, however, just finished my first year with Drupal, so I can still remember all the things that annoyed me when I sat down with Drupal 7 theming for the first time.

Like @davidhernandez have pointed out in a few of the previous comments, I don't find the "group by theming understanding" different enough from the current module grouping. If we (the Drupal community) push Classy to be the base theme to use for new Drupal themers and themers start "reverse engineering" their way from the "templates/node" directory to the node module due to the same naming and they try the same with "templates/form" or "templates/navigation" and is unsuccessful in finding any modules with the corresponding names, well, I only think that the "group by theming understanding" will add additional complexity to the theming process and learning curve of Drupal.
Drupal is already extremely modular where each module is very descriptive of its responsibilities, so I would rather suggest sub-folders in the "templates/system" directory where the "form" and "navigation" directories could live. To use one of @mortendk 's own arguments against himself:

@mortendk : We have theme debugging tool to tell us where a template lives - so the fear of not finding a template is not a real concern.

There have been a few mentions about newbies and people without Drupal skills:

@mortendk : Im not assuming any Drupal coding skills - i am though assume knowledge of how theming works (template overwrites etc)

@davidhernandez : My point is it seems to be assuming a certain level of experience for someone looking through the folders, not a newbie.

I think that it's important to be clear about the (in my head) two different kind of "non drupal skilled" themers who would be in a situation where they should create the frontend for a Drupal site. We have the group without any real interest in learning Drupal and the group that would actually like to learn Drupal theming.
With all the new hype about Headless Drupal in Drupal 8 and the ability for Drupal developers to, easily, provide APIs to themers without any interest in Drupal (and they would go on to create the front end in AngularJS, Ember etc), are those people we should consider?
Wouldn't the current template organization just increase learning speed and understanding of Drupals modular system for themers who would actually like to work with Drupal? And the debugging tools do give a clear explanation of "Go here to change this markup, Sir Themer".

Summary: I like the "module grouping" the most and if we add a completely new way of organizing the templates, are we not adding unnecessary complexity for new Drupal developers?

N.B. I read the summary and the last 10-15ish posts before writing this. I just found that keeping the module grouping with sub directories in the system folder was the first idea mentioned. So at least that show some sort of general agreement (even from @mortendk 's original thoughts, who is now the premiere speaker for the "makes sense grouping").

I thought I had posted a new comment earlier, but it seems to not have shown up. So here goes again.

I really like the way Morten has organized things. The two that strike me as debatable are system menu blocks and site branding blocks. Yes, they are blocks, so a block folder sort of makes sense. But the purpose of a system menu block is to show navigation, so navigation makes more sense to me. And a site branding block displays page-level branding elements, so the page folder makes more sense to me for that. Definitely debatable; that's just how I see it.

I could see an admin folder making sense, particularly if we ever get to bring in more back-end admin templates if time allows. That could make it easier to create an admin theme.

Here's how I see this working out.

If you're like Morten, and you want to start out your theme from scratch, because you know what you're doing, and you just want add in classes only where you need them, then you'll probably have your theme based off of core. You'll check source with Twig Debug on, you'll find the templates you need in the core modules, copy those you need to your theme and away you go.

Let's say you want to create a really simple Drupal site, and you want something like Bartik but not quite like Bartik. Well then you might create a subtheme off of Bartik, and you might see that's based off of Classy, so if you can't find a template you want to change in Bartik, you might check Classy. You haven't poked around in core much, so if you see some template folders that make sense, that might be helpful for you. If somebody has shown you Twig Debug, that might not matter much, but it might be slightly less confusing if you don't have to wonder why some of these important templates are all stuck in a system folder.

You're in a similar situation if you're using an advanced contrib theme that is more likely to be based off of Core. If you're using a theme with a lot of the appearance pre-determined, it could be based of Classy or Bartik or could be based off of core.

If you're fairly knowledgeable about theming, but you don't want to start from scratch in creating classes you can modify, you might just subtheme off of Classy. I still think there is value in that situation to have sensible folder names.

I guess the question is if it's terribly confusing to make slight improvements to the templates folder structure because it's not different enough to matter, what would qualify as being dramatically better enough?

I care a lot more about trying to find ways to make theming more friendly to site builders and themers and newer front-end developers than I care about keeping people who are already very knowledgeable about Drupal in their comfort zone. If you already know which modules create each template, congrats, you know a lot about Drupal! And you can leverage all that knowledge to create a theme based directly off of core. Rock on!

But seriously, it takes a long while for most people to start poking around in the core modules folder to see what dragons lie there. I don't think most newer folks will be confused by folders that aren't entirely based around the core module structure.

A quick background: I use Drupal since 5.x. I am designer, frontend dev, themer and to a smaller extend a programmer. I fancy minimal markup, so I am in Mortens camp.

My first template

When I wrote my first template I had no idea that core templates existed. I thought you had to made them up from scratch – which is imposible. So I took a template from a existing theme and tried to figure out how to change it. For the most parts I did not understood, why vertaion parts are in and where they are comming from. So I let them in and struggeled with dealing with them in CSS.

My own mothership

Later on (in D6) i learned about core templates and was able to copy an modify them. I build my own small, reduced basetheme. Modified it for every project, so it never became a real base theme to publish. But I was (and I am still) anoyed to rip something out of templates to just get a cleaner HTML.

Now I can find all core templates – but not because I find the places logically, but because I use grep. Or hunt for theme functions in the documentation.

The Consensus Banana

I still think the Banana is a great idea: Move the existing core templates with all classes to a base theme and use it for Bartik. The 2/3 themers who like the old core classes can use it.
And for the other 1/3 we clean up then classes and provide minimal core templates. Fine.

The Problem

This solves the bloated markup problem, but not the discoverbility problem: I still have to grep for the templates to get copy of all core templates.

I will not copy Classic (which has (nearly) all templates) and start again ripping out classes and divs. That would be no progression from D7.

All that has changed for me now: Cleaner templates to hunt for in core.

TX

What would make my TX awsome?

Simple: a templates folder in core, that has the same structure as the templates in Classy.

The Structure

I like the proposal from #24. That’s ok for me, I like it more than the module structure. And moving some templates around – please dont bikeshed here – is ok. I will find them. And if the structure is really good, I will know only after the 10th D8 theme.

Conclusion / Wishlist

* Agree on a structure for the Classy templates
* Build an equal structure for the minmal core templates.

@derheap oooh yeah it would be sweet TX if we had the "clean" templates collected on place - but i think its gonna be a pita to get that in d8, we can though in contrib do "the-cleanest-theme-ever" project & have all the templates there, right now the goal in core is to make sure we have templates that are ripped for all the classes, so we can get on to clean up the css (and who knows what happens later)

@david cause sometimes (wonderfull rule btw) keeping the templates collected by the module is a good idea - book make sense as its all on the same page that your gonna work on it ? but yeah the nav should go over in the navigation tbh

We should have templates/admin/ folder that have all the templates that are used for admin things put block-list. node-add-list, node-edit-form etc in there, would make sense, make it visible for what they are

yeah thinking about it all fields should be intemplates/field gives us an overview

To me this issue scarcely matters. I will continue to find the templates I need by using PhpStorms index and Twig's debug features. All the work done so far has given me more ways to be in control over the markup than I thought I would ever get from a Drupal project.

Thank you all for making that happen.

I think we have the potential to improve the organisation of templates and to make them more useable, but doing it only in Classy feels like we are plastering over the problem. I think it's important to have a consistent template structure between Classy and the rest of core and then improving them both together.

The only way we can have template organization change in both core and Classy is to create a new templates area within core that is outside of modules, and as far as I remember, that isn't possible at this point in the core development cycle.

So while it would be nice to have the perfect solution, I'll take making improvements where we can, and that's in Classy.

Were not gonna be able to also "fix core", and thats not what this issue is about its all about the classy theme. So lets not go down that road.

Tonight me and @kallehauge sat down and brainstormed on a structure, where we try to look at "what stuff do instead of where it comes from"

Folderstructure

admin (admin stuff)
block (all blocks)
component-content (node, taxonomy-term, aggregatore etc - basically article tags)
field (all fields, render helpers)
form (everything thats a form)
layout (page)
navigation (nav tags)
system (bucket)
user (user element)

obs we know the "component-content" folder name is horrible, but we needed a name that was not "node".

heres a screenshot for an easy overview

Discoverability is a tricky thing. The close connection between a template and its associated module cannot be denied, so my initial gut reaction tells me that breaking this connection in the way we organize templates in Classy may cause more problems than it solves. In fact, at first I was staunchly against deviating from the module organizational scheme. Upon further reflection I might be OK with organizing templates from a “themer's perspective,” but with some caveats.

1. Because knowing where a template comes from can be very important, we should add something along the lines of "@see /core/modules/node/templates/node.html.twig” to the docblock in each template file in Classy.
2. The words “debug tool” should never be the answer to a problem. At least not a problem that new themers (or new to D8 themers) might come across.
3. It’s a basic rule of visual design that if you’re going to make something different then you need to make it REALLY different—contrast, don’t conflict—and the same rule applies here. I wholeheartedly agree that a different organizational scheme will only be successful if it is blatantly different from the module scheme. With that in mind, we should only use module names for our directories if that is really the best, most descriptive name for the directory. We shouldn’t even think about calling a directory “System” just because that’s the name people are used to. If a folder is just holding miscellaneous templates with no where else to go, then call it what it is: “Miscellaneous.” If we’re going to do this thing, then lets do this thing!
4. Don’t be afraid to create a new directory that only has one template in it. I say this for two reasons. The first is discoverability, which is the whole reason for this organization. No one is going to look in “System” for a taxonomy template, so who cares if the Taxonomy module only has one template, it still belongs in a “Taxonomy" folder. But beyond that, whether we like it or not we are effectively creating a best-practice theme organization scheme here. Sub-themes built off of Classy, or new themes forked from Classy, may have additional taxonomy related templates and we want to give people a place to put those templates without creating yet another divergent organizational scheme. This is especially important with sub-themes. I’m asking for trouble if my theme’s directories don’t match its base theme.

In conclusion, I still think the module organization scheme is a safe bet, without too much downside. So if you’re going to do something new then it needs to be noticeably different, make a big improvement, and have minimal fuzzy edge cases.

Were not gonna be able to also "fix core", and thats not what this issue is about its all about the classy theme. So lets not go down that road.

Both of these statements are untrue. The Classy theme doesn't sit own it's own separate to core, the learnability of classy affects the learnability of the theme system in Drupal. You can't pretend that modules don't exist.

The Classy theme doesn't sit own it's own separate to core, the learnability of classy affects the learnability of the theme system in Drupal. You can't pretend that modules don't exist.

I dont pretend modules don't exist, but in the same way that working with css the file structure dont have to mimic drupal core (thank god). If it make sense then by all means group it, as i would do with views. Classy is all about separating us from core, its the key concept. You really want (hard)core, ya can go with stark.

classy is about "themer experience" can you figure out where stuff is, does it make sense why a template is in "admin" or "layout". does it gives information for what its used for. as it is right now its not even build on the module that create the template: look at system folder & lets take menu templates - is that system that generated that ?. As another example indentatoin.html.twig it took us today 10 minutes to figure out where & what id did placing that in templates/admin makes it recognizable, give info on what it does, and if I should even have it on my radar when im designing a theme, thats not touching admin.

One of the many key wins that was discussed at the banana #1 in austin was getting away from a template organization, that only made sense to a machine and no sense for a themer, cause it dosnt matter if its views - forum - node - user or views that created it, as i remember it the usecase was: "I just wanna modify that form element"

added a new patch with a misc & component folder + removed that icon folder (they should be added directly to the templates but thats for another issue)

This is gonna be even more fun when views moves into classy ;) it could be argued that only very few templates got moved out of /classy/templates/viewslike the min-pager & form-exposed, as views is its own beast.

@david the time.html.twig is used for a date field, so its in field

and screenshots as this is about themer experience

i was trying earlier with views - its a goddamn beast! I would start with: it goes into templates/view/[templates] untill we have figure it completely out, and its mentally have sunken in that were reorganizing templates.
-> But theres time to figure it out from the commit goes in to the next beta-x - beta-y - RC1

is book-export an "admin" thing, its more a misc i think.

table & item-list are a bit strange, they are kinda doing the same as views. ex item-list are used to wrap around search results

I really like what @jstoller suggested in #66

Because knowing where a template comes from can be very important, we should add something along the lines of "@see /core/modules/node/templates/node.html.twig” to the docblock in each template file in Classy.

There haven't been any written agreement with this in the following posts, so I would just like to highlight it again :)

Regarding moving table to the "component" directory. Hmm... I see the templates inside component as "article tag" type templates like @mortendk suggested at #65. Table on the other hand is more some possible markup for content within the article tag. System/misc might not be the best place for it, but I feel like it's better than the component directory

i would actually add that we should even provide an example url into the template, so you dont have to guess where this template is used.
A thing we have a lot of fun with right now - that gives the theme a chance to find & look at the output.

{#
/**
 * @file
 * bla bla bla this template is for something awesome
 * content comes from this module: core/modules/awesome/
 * test url: [root]/foobar/baz/awesome-stuff/admin/
 *

WHY OH WHY - didnt we have this back in 4.7 -we had to guess by the classname, where it might came from & walk 10 kilometers after milk as the polar bears were trying to attack us.

btw we need a folder thats not "layout" or "component-article-stuff" and not "misc" ... to hold stuff like list, table etc.

I just took a second look at book-export-html and book-node-export-html. The book-node-export-html should really be moved to component since it's actually an "article tag" type template. It simply represents a node in a printer friendly way:

Taken from book-node-export's Docblock: Default theme implementation for a single node in a printer-friendly outline.

And book-export-html should really be moved into "layout" since it's actually similar to html.html.twig.

I am sold, no more organisation of templates by module any more.
#72 looks great.

And #76 is a great, great idea.
We should put it in a extra issue, as we can add them after the moving of the files.

Again my question:
What is blocking us from copying this structure in core?

@derheap:
1. its out of scope of this patch - we want to keep it as small as possible.
2. we dont want to have core modules to behave differently than a module in contrib, not having templates inside a module we break that pattern, else we could also argue for no /css files as well or they were all on place etc.
3. it can be done easy in contrip - Lets focus on the big, lines we have a long way home, before drupal8 theming out of the box is awesome.
4. it have been shot down again n again n again by the developer community, based on 2, 3 & 4. We should also listen to 'em.

its completely out of scope of this, so lets do that in a followup issue.

@mortendk
1. I don’t want to scope bloat this patch. But from a themers perspective thats my dream (in a followup).
2. I see two worlds colliding, yeah ok. I can accept this. But how can we provide a better solution?
3. In contrib? How? A module / drush / console script that collects all templates from core and arranges them in the same structure as in Classy/templates?
4. I give up for now.

How can we solve this in a followup, when its

it have been shot down again n again n again by the developer community, based on 2, 3 & 4. We should also listen to 'em.

?

3. at each release, if theres been a change to a templete you roll a batch script that graps all the templates & put em in the folders you want & update your contrip.
that theme in contrip would be the same as any other theme, the beauty is that now you have the essential classes, that you know that drupal needs to function, and complete clean templates (that probably can get cleaned even more & get better in all kinds of ways)

so lets focus on classy, if we get over that bumb, then we have a structure - we can begin on looking at how to make classy a strong basetheme with class structure etc. & use seven + bartik as perfect test cases

3. Oh, as a contributed base theme. I completely ignored themes as contrib in the past, so it was of my radar …

OK, let’s carry on with this stuff.

I'm first going to admit I have not read the whole thread. But after skimming a bunch of the posts from the past few days I still feel like we're adding another layer of ambiguity by creating a new organizational structure. That requires more judgement calls and guessing - where if we go with the module naming convention, at least there is a direct correlation of logic as to where things go. Overall I think that's easier for a novice to understand so they can always know 'I want to change the template for contrib module 'x' and I know exactly where to find it'. Drupal's organization may not be perfect but I think we should consider carefully straying away from consistency.

Unless of course that's already been decided :)

@jpamental it was part of the banana discussion in austin - That keeping an folder organization based on a modules, or putting every template into /templates/ made little sense for themers. A part of the TX we needed to rethink this for classy.

It do require a deep understanding of drupal to understand why some template is in "system" or that "/link/" is not "links templates" but its a linkformatter for fields, and no links are placed there - or menu templates are in "system" and not in a /menu/ or /navigation/ not to mention we have templates that are only used for admininstration all over, that makes the theming work less intuitive.

We can now collect all form templates in a form folder, all navigation templates in one folder etc.

btw the drupal 'consistency' is build on ideas thats proven for themer's to be a pita ;)

Nothing is decided yet - we do have bananas to make concensus with & question our own silly ideas

Classy is all about separating us from core, its the key concept. You really want (hard)core, ya can go with stark.

classy is about "themer experience"

Yes I think so, but we can also consider Classy to be an introduction or an onramp to theming in Drupal, so introducing a structure that is completely different if a themer decides to "upgrade" to Stark will make that upgrade harder. I agree with the improvements suggested here but I would prefer if it considered the Stark structure as well for this reason.

Sorry, by "Stark structure" I meant the default module folder structure.

The only reason were even considering using the module folder structure is that it was pushed down our throath for years.
its stockholm syndrome ;)

Yes it would be nice to have stark "as a real theme in core" and it would make sense (from a themer perspective) to move all the templates into /core/themes/stark Cause the "its not a theme, its just core/stark" makes little practical sense, it taste of an academic argument, not a practical one.
It would not fly untill we have a classy example (punt intended) that shows how its done.
First when we have:

1. cleaned out all css & classes dependencies from core
2. seperated the js from css classes
3. made classy theme a primo example
4. rewritten all the css to the bem/smaccs standard
5. made seven & bartik shine
6. celebrated that!

Should we even consider taking the "stak as a real theme" - we have RC1 as a target, when that ship is out, out markup & css structure is locked down.

stark can always be "fixed" in contrib where we have a copy of the clean templates organized the same way, and then put it into the documentation or whatever lowlevel solution we figure out

btw we need a folder thats not "layout" or "component-article-stuff" and not "misc" ... to hold stuff like list, table etc.

If everything in the "component" folder is actually article element type content, then why not put it all in an "article" folder and use "component" to hold the templates for smaller content components, like lists, tables, status messages, etc...

The only reason were even considering using the module folder structure is that it was pushed down our throath for years.

I'm saying we should improve the module folder structure, and not using the module folder structure in Classy does not remove it, it just covers it up until later.

I'm saying we should improve the module folder structure, and not using the module folder structure in Classy does not remove it, it just covers it up until later.

There will always be a fundamental disconnect between the modular structure of back-end functionality and the ideal organization of front-end display components. I don't think simply cleaning up the module folder is going to get us where many themers want Classy to be. If meaningful documentation is added to each of the template files, indicating what module it's really associated with, then I think that will alleviate some of my concerns about deviating from module organization here.

i want both a comment On where its from -module & where i can see the template beeing used so i can browse to that URL.
all depending On how our css Will end up we should have a reference to which css files is expected as Well same as js

original module: node
URL: /node/1
css file(s): /core/node/css/node.theme.css
js file(s): /misc/foo.js

I think we'd all be in favor, but how do you propose we do that? As mdrummond pointed out earlier, I think we are beyond the stage where can move the core module templates outside of their respective directories.

What if we apply the kind of structure we are devising here to each module folder? Then there would be some similarity between the two structures.

I'm listening, but that seems a little odd. The folders make sense as a collection, but would seem strange in the individual modules because most wouldn't have more than one or two folders.

hmm true, but for something like system.module it makes sense. I don't know if it's better to document standards based on the use case of few templates or many templates. If we set the guideline folder structure for modules but then add a caveat of 'common sense' into the guidelines, if you only have one template, then maybe don't bother?

@david exactly! that will also make it clear for the themer where to get the "raw" version for the template
and to that example ... nope lets not make a mess of folders, been there done that - no fun ;)

I dont think as long as we keep templates inside of the core modules, we can do anything there - Besides its scope creeping, that wont get us anywhere.
We should go for the wins we can take, Classy is where "theming starts" - lets focus on that.
Then If the time comes to it, we can go on a move-clean-templates-to-stark crusade.

@davidhernandez I totally get that, but I do see adding the documentation as a condition of reorganizing the templates in this way, so I just don't want it to get lost.

For what it's worth, I don't think breaking up core module template files into sub-folders, to match Classy's organization, will in any way help make the system more understandable, or make the templates more discoverable. If anything I think it further confuses things. However, I would support adding documentation within the (mostly empty) module templates that point to Classy's template overrides as examples, just as we're talking about putting documentation in Classy's templates that point back to the modules.

@david yes it would be awesome. I want to read a template file & understand what its role is in the universe of Drupal
and the fact that we have templates that we basically have no idea what they are doing just by looking at the filename is yet another reason that we need a context to put em in aka folders.

Template moves can break themes, because extending a template with the same name requires the exact path.

@davidhernandez are you sure, I thought we resolved any need for this, we have the theme registry pumped into the file system loader. Like {% extends "@bartik/block.html.twig" %} (I could be wrong, haven't tested recently)

Ah thanks for the clarification on that:) Yes that does sound like a different problem.

ok just took some time to look through this thread after the talk with alex today.
I think that we need to move on this next week - in reality we have 2 go on this before we hit upgrade path headaches.

Concensus

1. IF we move templates, it should be documented where it came from originally - suggestion:

Original template: core/modules/system/templates/indentation.html.twig
Example usage: Drag and drop table indentation (/admin/structure/menu/manage/admin)

.2 IF we move templates we need have a folder for list, talbes ...

Suggestion Folders:

admin
article
block
field
form
layout
misc
navigation
user
wrapper (*)

* wrapper is a terrible name i know, but lets start somewhere

One nitty-gritty on Mortens proposal:

/article should be /node as we are targeting templats for all nodes here not just article node types.
Yes, I know it reasambles the article tag. But in a Drupal context I immeditaly think of the article node type
and think oh no, I will delete you immediatly.
And it is not always the right idea to wrap a node in an article ...

Otherwise I am fine with it.

Re #111: I think this is getting a lot closer. I like the addition of "article" and I like that it's deviated more substantially from module names. The biggest thing that stood out to me at first glance is "wrapper." I found it a little confusing. "Component" feels like a more accurate description of what's in there.

@derheap I disagree. "Article" is for much more than just nodes and we need to indicate that. "Entity" would be more appropriate than "node," but all of these terms carry significant baggage.

@derheap comments & searchrestults templates are not nodes they are <article>...</article> if we use the word node, we are bound to keep ourself to only add "node templates" in it, and dont wanna confuse it with that.

@jstoller - Yes "wrapper" is terrible, my fear of component is that isnt everything a component. But im pretty sure we can come up with something better :P

It strikes me that this issue might benefit from a card sorting exercise. Basically, a card for each template, let a group of as many themers as possible put them in folders that make the most sense for them, scan through the results and look for trends.

Looks like http://frontendunited.org/ is not happening until June, but http://2015.drupalcamplondon.co.uk/ is coming up in about 2 weeks, and I know there will be a few front-enders there. There are also remote card sorting tools, though I don't know of any in particular; I can ask around at work.

@webchick I've played with that idea myself earlier, one of the problems is that a template name isn't always clear what it does until you open it - like blok-list.html.twig & we want a mental link from template to markup to CSS.

I hope we have this in (iteration 1 out of 2) before London so we can do a blind test on a bunch that haven't yet played with drupal8

one thing is for sure I'm gonna hijack a bunch of frontenders & site builders in London for test :)

Great. :) Carry on, then.

Also note that markup is unfrozen, so if the best solution is to rename templates so that they actually make sense, and it won't have a huge impact on module devs, we can explore that as well.

Just to close the loop on #117, Acquia UX uses http://www.optimalworkshop.com/treejack.htm for this purpose. Allows you to enter in a hierarchy and see how it does.

@webcheck yeah we might wanna rename em as well, but I think the order will be:

1. Organize templates in classy
2. Clean out classes from core & figure out whats actually essential css classes
3. Rebuild the core css structure on smaccs / bem (now that we know whats essential)
4. Get Stark & Bartik into order with the same css structure
5. Merge templates & rename templates to make better sense (im looking at you forum-icon.html.twig

that can give us time to itterate over the css groupings, fiddle with the templates & really "get to know them" with a minimum of hold up on each phase.
So thats why i want this 1 part done, so we can focus in smaller groups & hammer on it

Yep, makes sense. Thanks for the overview. Back to your regularly scheduled bikeshedding. ;)

that is what I do ;)

comments & searchrestults templates are not nodes they are <article>...</article>

"article" is a bit overloaded. If you think themers will be clear that it refers to <article> and not to the Article node type installed by the Standard profile, then ok. But otherwise, is there another word that is front-end friendly? Maybe "content"?

Hi ,
article is bit confusing though it talk abt tag so it will make lots of difference if we give different name like "node" or etc

Thanks
Harshil

This is looking so, so good.

If we're delaying finding out what a better word for "wrapper" is, then maybe we can also mark "article" as not completely ideal for now, but evaluate the groupings apart from the names.

I like the templates as they're grouped in #111.

OK so it sounds a bit like we have some concensus on the grouping on files yes ?
but theres some bikeshedding over the names of 2 folders :)

We should not hold up a first version of reorganizing the templates, cause of bikeshedding over a folder name. It will delay our work for the themer experience & we might run out of time! We have a ton of work that needs to get done.

Views templates are coming soon
views have templates that are making list, which would mean that table.html & item-list would be grouped there.

That would leave the badly named "wrapper" folder with 3 templates left:
* aggregator-feed.html.twig :
That tempplate should be merged in with the aggergator-item.html.twig & be called aggregator.html.twig
* forums.html.twig & forum-list.html.twig
Should merged into one template file: forum.html.twig

Both those templates aggregator & forum, are all about content:
classy/templates/content:

aggregator.html.twig *
forum.html.twig *
node.html.twig
comment.html.twig
mark.html.twig
search-result.html.twig
taxonomy-term.html.twig

* is the not yet merged templates

Views / list folder (continues in next comment

the views / list folder would contain this, with maybe a file or 3 to be moved to navigation & form

So my suggestion is this

* Name the folder that contains articles, comments etc to "content"
* Leave the wrapper folder for now and wait with til views templates gets moved

Start working on getting forum & aggregator into one template.

This will give us better overview of the templates as we work up until upgradable beta, and will make it clearer which templates that might needs remaning (block-list im looking at you)

Folder structure round 9 visualised
changes:
foldername:
"article" to "content"
"wrapper" to "list"

based on the expected views template move & everything else i commented on in #117

This is looking really good. I think this makes a big difference in making it easier to find templates.

It strikes me that one alternative name for misc might be meta. These are all icons that show info about something (meta data), info about the site (status messages) or literally meta data (RDF). The name misc is such a grab bag that it's not terribly useful to help finding things. I'm not sure if meta is dramatically better, but might be something to consider.

Morten mentioned above that aggregator-feed.html.twig and aggergator-item.html.twig might be merged into aggregator.html.twig, while forums.html.twig & forum-list.html.twig could be merged into forum.html.twig and both of those could go into the content folder. That only leaves item-list and table in the lists folder. That's not terrible, although I'm not sure I'd think of a table as a list. I'd say that item list and table could go into the content folder as well, but I suppose those are used for other things beyond content too. So... maybe lists is fine.

Anyhow, really great work. This would be a big improvement. Big thumbs up.

i like "indicator" - but i dont think were gonna get rid of "misc" thats unless we decide to not move rdf-metadata.html.twig file over, or we put it in content where it could be justified to have.

"misc" changed to "indicator"
rdf-metadata.html.twig moved to "content"
screenshot

@david think indicator is kinda strange "misc" at least people knows thats where "all the small crap that didnt fit anywhere else" is ;)

I agree "indicator" doesn't work. I have no intuitive sense of what might live there and I certainly wouldn't look there for something like the status message template. “Miscellaneous” isn’t perfect, but its a better catch-all.

Maintenance-page.html.twig belongs in “layout.” The page may be triggered by something an admin does, but it this template still represents the content of a front-facing page. It is more closely related by far to page.html.twig than it is to block lists and node edit forms.

Should tablesort-indicator.html.twig be in the same folder as table.html.twig, given that the former is a component of the latter (at least, I think it is)?

I’m not totally sold on this “list” folder idea. Not all views are lists and I don’t really think of tables as lists either. That said, I see what you’re going for and I’m not sure I have a better suggestion. Part of me really does just want to put all the Views stuff in its own “views” folder, but that might be the jaded Drupal developer part of me.

I was toying with the idea of bringing back a “system” folder for status-messages.html.twig and progress-bar.html.twig, since those are more system level things, but that might be going too far.

For now I think we should go with the simpel rule that "all admin theme stuff goes into admin" (theres still 10+ templates that have not been moved cause of various issues)
We should get this first part done - more or less like iteration 10 but with "misc" instead of "indicator". Then when views comes in - whenever all templates have been cleaned up, then we argue over that & restructure to that reality.

* It will give us time to play around with the folder structure - theres bound to be some hit n misses with 100+ template files.
* give us time to learn & understanding the templates better.
* figuring out if templates have the right name.
* Also will give us valuable feedback from ppl that just want to test it out, we cant expect ppl to patch drupal to play with a theme structure.

Then after that we take up all other discussions: if template Foo should be in BAR of BAZ, and change them one step at a time, cause else this will never happen, and well end up with a system folder from hell & drupalism's all over, which we dont want.

I would like to timebox this a bit hard & have 28 feb. as a "deadline".
When we do the first iteration & get that into classy.

...pst btw a table is just a list of data ;)

Then have another "move around" itteration, which we schedule before the upgradable beta comes out. That would give us about a month of testing.
and offcourse whenever we find stuff thats stupid we fix that

Sounds like a plan ?

+1 to moving to maintenance-page to the layout folder. I think of an admin template as something related to the admin interface, but maintenance page is a message to users about why the site isn't available.

Also, +1 to views in a views folder. Views can be anything, so trying to organize it by the type of thing it is doesn't necessarily work.

+1 on timeboxing this discussion.

elements could be an alternative to lists, but not sure I love that as a folder name either. indicators makes sense to me.

For now I think we should go with the simple rule that "all admin theme stuff goes into admin"

I completely agree. I just dispute that maintenance-page.html.twig has anything whatsoever to do with the admin theme. It templates a page that is largely seen by unauthenticated users. I would never want the maintenance page to display with my admin theme.

...pst btw a table is just a list of data ;)

I get where you're coming from, but a "list" is a one-dimensional listing of connected items. Only rarely are lists displayed in table form. Tables are most often used to represent two-dimensional collections of data. Plus there are other edge cases, like grid displays, that don't completely fit under the "list" descriptor and views can be used for all sorts of crazy stuff that aren't remotely lists.

How about calling it "dataset?" A dataset can be any collection of related sets of information. Lists, tables, thumbnail galleries, slide shows, calendars, graphs, maps, etc., are all datasets, so I think I'd even be comfortable putting views templates in there. "Collection" and "grouping" are other options, but I'm leaning toward "dataset."

Here's what I propose:

• admin
  • block-list.html.twig
  • file-managed-file.html.twig
  • file-upload-help.html.twig
  • file-widget-multiple.html.twig
  • file-widget.html.twig
  • filter-caption.html.twig
  • filter-guidelines.html.twig
  • filter-tips.html.twig
  • image-anchor.html.twig
  • image-crop-summary.html.twig
  • image-resize-summary.html.twig
  • image-rotate-summary.html.twig
  • image-scale-summary.html.twig
  • image-style-preview.html.twig
  • image-widget.html.twig
  • node-add-list.html.twig
  • node-edit-form.html.twig
  • text-format-wrapper.html.twig
• block
  • block--search-form-block.html.twig
  • block--system-branding-block.html.twig
  • block--system-menu-block.html.twig
  • block.html.twig
• content
  • aggregator-item.html.twig
  • book-node-export-html.html.twig
  • comment.html.twig
  • mark.html.twig
  • node.html.twig
  • rdf-metadata.html.twig
  • search-result.html.twig
  • taxonomy-term.html.twig
• dataset
  • aggregator-feed.html.twig
  • forum-list.html.twig
  • forums.html.twig
  • item-list.html.twig
  • table.html.twig
• field
  • field--comment.html.twig
  • field--node--created.html.twig
  • field--node--title.html.twig
  • field--node--uid.html.twig
  • field.html.twig
  • file-link.html.twig
  • image-formatter.html.twig
  • image-style.html.twig
  • image.html.twig
  • link-formatter-link-separate.html.twig
  • time.html.twig
• form
  • checkboxes.html.twig
  • confirm-form.html.twig
  • container.html.twig
  • datetime-form.html.twig
  • datetime-wrapper.html.twig
  • details.html.twig
  • dropbutton-wrapper.html.twig
  • field-multiple-value-form.html.twig
  • fieldset.html.twig
  • form-element-label.html.twig
  • form-element.html.twig
  • form.html.twig
  • input.html.twig
  • radios.html.twig
  • select.html.twig
  • textarea.html.twig
• layout
  • book-export-html.html.twig
  • html.html.twig
  • maintenance-page.html.twig
  • page.html.twig
  • region.html.twig
• misc
  • feed-icon.html.twig
  • forum-icon.html.twig
  • progress-bar.html.twig
  • status-messages.html.twig
  • tablesort-indicator.html.twig
• navigation
  • book-all-books-block.html.twig
  • book-navigation.html.twig
  • book-tree.html.twig
  • breadcrumb.html.twig
  • links.html.twig
  • menu-local-action.html.twig
  • menu-local-task.html.twig
  • menu-local-tasks.html.twig
  • menu.html.twig
  • pager.html.twig
  • toolbar.html.twig
  • vertical-tabs.html.twig
• user
  • forum-submitted.html.twig
  • user.html.twig
  • username.html.twig

@jstoller + @mdrummond
maintenance-page.html.twig Yes i hear ya, thats a valid point, and would be a standard page as well to theme - so in layout with that, we should not try to hide stuff from ourself ;)

"dataset" can work for me, were might gonna find a better name later on, i can go with that "list" do put the mindset towards an <li>
views is probably just gonna end in its own folder, also cause any theme ever build always used up with a folder with all the views inside of it.

Rolled another with the above discussion on top based on jstoller.
Began to work with modifying the documentation as well inline te file

block-list.html.twig

{#
/**
 * @file
 * Two column template for the block add/edit form.
 *
 * Original template: core/themes/classy/templates/admin/block-list.html.twig
 *
 * This template will be used when a block edit form specifies 'block_edit_form'

The only line for now would be to add the original template one line below the into @file stuff, is that the spot

In keeping with standards elsewhere, I'd suggest something like this:

/**
 * @file
 * Two column template for the block add/edit form.
 *
 * This template will be used when a block edit form specifies 'block_edit_form'
 * as its #theme callback.  Otherwise, by default, block add/edit forms will be
 * themed by form.html.twig.
 *
 * Available variables:
 * - form: The block add/edit form.
 *
 * @see /core/modules/block/templates/block-list.html.twig
 *
 * @ingroup themeable
 */

The pointer back to the original template in the module should be towards the end, under the description of what the template is for and what variables it can access, since that information is more generally useful. The @see designator seems to be the standard way to refer to other related files/functions in a file's docblock, so it seems like we should stick with that, no? It's already used in some templates to point to preprocess functions and such. For example, you might have something like this...

/**
 * @file
 * Default theme implementation to display a file widget.
 *
 * Available variables:
 * - element: Form element for the managed file.
 * - attributes: Remaining HTML attributes for the containing element.
 *
 * @see template_preprocess_file_widget()
 * @see /core/modules/file/templates/file-widget.html.twig
 *
 * @ingroup themeable
 */

Agreed with @davidhernandez, let's not bite off too much in this issue. I am a bit doubtful that the @see format examples above would be able to be parsed by the API parser, for example.

ok lets put this to test & see if we get 146 more comments ;)

im happy to wait with the documentation issue, as this can indeed mess things up. Then we need a followup issue.

I just created #2430381: Improve Classy template in-line documentation.

Looks good to me. Only question: is "content" and "field" being separate folders useful, or should the field ones be merged into "content"? From a theming standpoint, I'm not clear on what makes fields more special than other content.

Interesting possibility: put both field and dataset templates into the content folder. That gets rid of a difficult labeling problem, and all of those things seem like content to me. Lists and tables do have some uses outside of content I suppose, but content seems like a better place to look for those than dataset.

I think indicators is still a better label than misc given what's left in there.

Blocks is still a bit of a Drupalism. What if the system menu block moved to navigation which is its real purpose and the others moved to layout? The search block and site title are more page-level things in a site layout, and blocks themselves are a layout tool.

@mdrummond:
merging "content, field & dataset" that would result in 25 templates in a folder, thats a nogo for the theming experience. The issue we have is "dataset" is a naming issue, it seem like we have a reasonable compromise ?

misc will probaly get some more stuff in there as well, when we take another stab into core's templates & theres always need for a misc ;)

@effulgentsia
its not the law of how templates are organized, but its an pretty ok indication of a structure, that still work's on a site with 10 content types, 20 overwritten fields & 20 blocks, merging to much together would be confusing

@effulgentsia and @mdrummond: There may be a bit of a semantics problem here. "Content" is really referring to entities that might be wrapped in an article element, but "article" was deemed too confusing, since there is an article content type, so we generalized it to "content." Unfortunately, that brings with it its own set of baggage, but it seemed like the lesser of evils. "Field" then deals with the individual bits of stuff making up that content, while "dataset" is dealing with collections of content (or other data). These are fundamentally different things and it makes sense to separate them. Otherwise we're headed back to one big unorganized "templates" folder and nobody wants that.

I think we need to remember that the structure we're developing here isn't just about organizing the templates we have. We're also setting a standard framework for other themes building on Classy to use. So even if it looks like one of our folders is a little light on templates, that template count could grow in real world subthemes when they start overriding contrib templates and such.

@jstoller: ok, makes sense, but then why are mark and rdf-metadata in content? I get that they're providing information about the content, but in terms of markup, they're not the content itself, but individual bits inside it, so should they move to field or misc?

@effulgentsia: rdf-metadata was in "misc," but was moved to "content" when "misc" temporarily became "indicator" and didn't move back when we changed the folder back to "misc." I'm pretty sure RDF metadata applies to elements at several levels and isn't limited to article element content, in which case it probably should move back to "misc." I'm less concerned about moving the mark template, since it seems to only apply to article type content. Of course I really don't know too much about how either of these templates are used in practice.

I'm pretty sure RDF metadata applies to elements at several levels and isn't limited to article element content

Nope. It only applies to entities. But still, it applies to the entities, it isn't the entities themselves.

in which case it probably should move back to "misc."

"misc" would make some sense to me. Except that it would be the only item in "misc" that is rendered inside of articles. The other things there like forum icon, status messages, etc. are generally rendered in some other part of the HTML, not inside an <article>. Not sure if that matters though.

I'm less concerned about moving the mark template, since it seems to only apply to article type content.

To me, mark is conceptually similar to field--node--created. Maybe themers think otherwise? In which case, why so?

Well, this takes us back to a question I was trying to ask earlier: if LittleThing is a component of BigThing and is only used in conjunction with BigThing, then should LittleThing's template be in the same folder as BigThing's template?

Examples...

A table sort indicator is a component of a table and is only ever used as part of a table, so should tablesort-indicator.html.twig be in "dataset" with table.html.twig?

mark.html.twig and rdf-metadata.html.twig template components of content entities, so should they stay in "content?"

As a themer, it may be more convenient to have intimately related templates in the same place when one is a component of the other. Especially when the alternative is a generic "misc" folder.

Note that this would not apply to something like a filed going in "content," since field can be components of lots of things that are not content.

rdf-metadata.html.twig moved to misc
new patch uploaded.

Screenshot for patch .. -161 & updated the summary. (smaller one added in next comment

changing the screenhot file to 72 cause its huuuuge

I think we've discussed the nuances of the edge cases in this list as much as we can. There may not be a perfect classification system, but I think what we have come up with is practical and helpful. These groupings of template files make a great deal more sense than simply grouping by core modules. Yes, this change may be a shift for those already intimately familiar with core, but let's be honest, that is a very small percentage of overall people working with Drupal, and it's certainly a small percentage of those who will interact with Drupal templates on a regular basis. For that group, this organization should be much more approachable than the module-based organization system.

+1 from to move forward with this change

We can argue it both ways ... if we moved forum-icon & table-sort into dataset, then should feed-icon be moved as well?

I think we should get this one in now as in #161 both forum-icon & table-sort should be merged into forum & tablesort, but thats a whole other issue

there new patch uploaded with the changes forum icon & table-sort moved into dataset

corrected folders ...

172 patch

+1 RTBC. Lets get this in and deal with any cleanup later. That way we can move forward with some of the other dependent issues.

I'm not to sure that admin is a good name for things that are here because they appear on the node add form. It conflicts with the notion of admin theme. Plus the admin list shows that we should not have copied (the very badly named) block-list template to classy. Creating a node is not an "admin" action.

On larger scale sites, there is likely to be a differentiation between those who are administering the site as a whole and those who are adding and editing individual pieces of content. Those two roles are likelier to converge on smaller sites. I'm not sure how worthwhile it would be to suss out the differentiations between those two roles, as different sites will draw different lines or no lines at all.

If we instead draw the primary distinction between those who are visiting a site and those who are responsible for making the site, then the node add form definitely falls on the admin side. If there are sites with user-generated content, then a node-add form could be user facing, but that just means that users are helping to administer the content of the site in some ways.

From the point of view of a themer or a front-ender, having node add in admin seems very logical. I'm not sure what the value would be of putting it elsewhere or where indeed would be an alternative place to put it.

I agree with @mdrummond. Managing content is an administrative task done by authenticated users. Whether the theme being displayed is a special admin theme, or not, is irrelevant in this context. As a themer, having the node edit template in an admin directory seems perfectly logical and I can't think of anything better.

Unfortunately there are no meaningful words we can use for these directory names that won't bring with them unwanted connotations and associations.

i dont see how this is conflicts with an "admin theme" ? the folder/directory is called admin cause all the templates here are "admin" stuff - if block-list.html.twig should be there or not, is another discussion (that we will take later) anyways dont see the issue here, from a theme perspective.

Is adding a comment to a site an administrative task? In my mind everything in the admin folder belongs in content because it is all about managing content.

Nope adding a comment to a page is not a administrative task, and its part of how the node would look, why they are in the same folder "content"
We separate to avoid an overload of a ton of templates, that makes the overview hard & the initial understanding of what the templates are used for easier.

There will be cases where a template could be used for normal user interaction - left say an image widget is added to a comment field, then that would create a muddy middle ground, but were not trying to solve every problem there might is - this is solving the 80% of themers needs -and give em a quick overview of whats used where.

Given that we are past our (self-imposed) deadline for discussion of this issue, and given that several themers have now addressed the latest dissenting opinion, I'm going to bump #172 back to RTBC. If you REALLY think this is premature then feel free to bump it back. However, I would ask that you only do so if you honestly think this patch would make things worse than they already are and not just to debate the finer points of folder naming. As has been noted before, we are trying to get the broad strokes of this reorganization into Core, so other issues can move forward. At that point we can continue to discuss the edge cases and, if warranted, rename a folder here, or move a template there. Let's please hold off on the bikeshedding for just a touch longer please. :-)

I wrote the following comment at the same time as #189. Posting it here, but not changing status.

For addressing #187, how about?

• Renaming "field" to "field-view"
• Adding a "field-edit" folder
• Moving "file-*", "filter-*", "image-widget", and "text-format-wrapper" from "admin" to "field-edit"
• Moving "field-multiple-values-form" from "form" to "field-edit"
• Either moving "node-add-list" and "node-edit-form" into "content" or else splitting content into "content-view" and "content-edit" and moving them into "content-edit"
• "admin" would then just be left with "block-list" and the image configuration UI, both of which seem like clearly administrative things

I really like #190. Creating "field-view" and "field-edit" is super clear and mirroring that with "content-edit" and "content-view" is sensible too.

And yep once this is done we can discuss removing the entire admin folder as these probably should not have been copied anyway.

Also apart from misc and admin then folders refer to what they theme whereas misc is a general bucket and admin is task type.

I would strongly recommend that we NOT add a "-view" descriptor to any folder, given the likelihood of confusion with Views. I'm not opposed to adding the additional directories, but I would leave "content" and "field" as is, while adding "content-edit" and "field-edit." I think it would be obvious from the context that "content" and "field" are for templating the way these items are viewed. If you really think you need a descriptor then I would suggest "content-display" and "field-display." It might be a few extra characters, but "display" is more accurate and less likely to cause confusion.

And yep once this is done we can discuss removing the entire admin folder as these probably should not have been copied anyway.

I completely disagree. In fact, I still say the mistake was in creating this artificial distinction between front-end vs. admin themes and not just copying all templates over to Classy. In any case, I certainly wouldn't condone removing a template that has already been copied to Classy.

Also apart from misc and admin then folders refer to what they theme whereas misc is a general bucket and admin is task type.

I see little difference between "admin" and "content" in this regard. They're both just buckets for different classes of page content. The important thing is, will themers intuitively understand what sorts of templates they'll find in these directories and I think the answer to that is yes. Without even looking I know that the admin folder will have templates for administrative functions on the site. You're right about "misc," of course, but there will always be a few bits that just don't fit well into any categories and it's better to have a general bucket to put them in then to try and shoehorn them into a category where they really don't belong.

@jstoller

I completely disagree. In fact, I still say the mistake was in creating this artificial distinction between front-end vs. admin themes and not just copying all templates over to Classy.

What you are saying does not make any sense given that Drupal is modular. Until an admin theming solution exists that takes this into account and does not introduce undeclared dependencies between classy and modules we are not going to have a good solution for admin theming. Quite why anyone thinks that a solution that copies all the templates blindly into classy makes the situation better once contrib is taken into account is beyond me. The move to use a common admin component library based on seven in modules that have an admin UI is the right way to go but we're still not going to have a world where all markup is going to be removed from all core modules, let alone contrib modules.

And also I don't know how many times I have to argue this but adding a node is not an administrative task. That is determined by the site owner. Our UI makes this a choice per site as you can have your node add form in your admin template or your front end theme.

Some feel that adding a node is an admin task, others dont, depends on what kind of site you have build its getting close to that place i park my bike..

Theres a really good reason that nobody made admin themes in D7 (theres 2 afaik) Touching anything was dangerous unless you accepted drupals status quo markup rooted back into pre 2010, which is exactly what were trying to solve.

#190
These changes seems to me are based on developer lingo & not thinking in a theming perspective. That said splitting up the admin folder is a thing that we would do later anyways, when the rest of the admin templates get moved over - but not blindly @alex ;)
I was trying to keep this first move simple(!) but we can digg a bit deeper even that i fear that this will take forever. but if thats what it takes...

Edit folder
I dont se any reason for 2 folders here lets keep it simple: "content-edit"
The Content folder is used for elements that are markup wise an <article> "Article" wasnt used as name, its tainted by drupal's article (disucssed & solved earlier) mark.html.twig is bound to node & comments and taxonomy-term.html.twig should be an article tag instead of the div (well need a follow up issue on that btw)

Fields was separated out of "content" and as its common to have multiple versions of a specific field (filed--whatever.html.twig) aving "everything content" in the same folder would be a mess.

Thats not the case when editing templates, so lets keep it simple: one folder "content-edit"

Here's an updated version taking the ideas raised in #187 & #190

again

A single "content-edit" folder works for me. I'd also be ok with shortening it to just "edit" if people preferred that, but I don't even know if I do.

I would probably suggest moving "image-widget", "node-add-list", and "field-multiple-values-form" into "content-edit", but I'm ok with leaving those for follow-ups if they require individual discussion.

I'm fine with the addition of content-edit and even field-edit. Agree that content and field or content-display and field-display are better than content-view and field-view.

Would be good if we can at least agree how to organize the templates currently within Classy, then leave whether to remove or add templates for a follow-up issue. Time is short, and it would be better to get done what is doable now, then continue to make incremental improvements rather than hash this into perfection and be told it's too late to make the change.

ok then lets talk around this a little bit more...

I think #195 solves all discussed issues, so I am putting it back to RTBC.
All other stuff can be bikeshaded in some followups.

Sorry if I am repeating what has been said in the 202 comments above...

So what happens from project to project and company to company? It is good to have the discussion here but themers aren't the only ones editting the templates, and is there a way to make this distillable so it can be placed by a guideline. Granted there is a debugger that helps locate, there isn't a debugger to help place. Thus, depending on the level of developer who is bringing up the theme the folder structure could look completely different.

Right now SCSS partials experience this problem because everyone has a different structure approach and where the styles should go is debatable. I'm for the module approach because there isn't much wiggle room in where the templates should go and clean up of a massive templates/ folder is doable with relative ease. Granted 'system' can get overwhelmed, quite easily...

@timodwhit yes that discussion we took about 100 comments ago & 2 weeks ;)

The issue with the module folder approach is its not an effective or good way to organize templates. The only argument for keeping templates in module folders is stockholm syndrome - "we used to do it, so that must be good, cause thats how drupal does it" The templates are not even connected besides of the module spits out the templates - modules are putting the same data structures out (look at the content folder 4 different modules that all put out the same templates.)
Yes we could argue we should have components, but thats gonna be in D9.

We are not targeting everybody for everything we are targeting here 80% is the goal - not 100% - see the discussion we have had the last 3 years of how to build D8 waypoints to guide us: https://www.drupal.org/node/2008464#principles
especially "Organization should be driven by meaning and semantics over technical convenience", "Build on use case" & offcourse the consensus banana #2289511: [meta] Results of Drupalcon Austin's Consensus Banana .

Making it easy for themer's to find the templates and understand what the context of the templates in drupal core, is the core goal of reorganising the templates this is Theming Experience.

What any company or anybody else do in there own themes, are completely up to them self & is not of interest- Nobody should ever place they own templates inside of core. The usecase would be that they cope classy to /themes/ and modify what they wanna do there, which is out of our hands.

@mortendk, thanks for the response and sorry for not making it through the novel. ha

Well then, I think this looks good. Makes sense where most things are to me. Changing back.

he he yeah its a pita to get an overview over + there is 3 years of consensus (both with swords & bananas) to take in as well ;)

I'm ok with what's shown in the screenshot of #195. I see no problem with adjusting folder names or moving a few files around after this gets in, so long as it's before RC. While "file structure of themes" is not explicitly mentioned in https://www.drupal.org/contribute/core/beta-changes#unfrozen, "markup" is, so I would argue that file structure of themes should also be fully unfrozen during the beta cycle. Assigning to alexpott for commit evaluation, since not all of his feedback has been implemented, so it's up to him to decide if that's ok.

Can node-add-list.html.twig go in either content or content-edit. I prefer content but I'm not ideologically wedded to either.

@alex its not "content" as descriped earlier content is "<articles>" but we use the name content, to avoid confusion with the drupalingo ;)

node-add-list is to me its an admin page, but im fine with moving it to content-edit - in that way its a part of the workflow "oooh overview of creating new nodes -> the node edit form" - that make sense

patch uploaded screenshots not provided ;)

So how is search-result.html.twig in content? I think this is also used to theme the user search result too?

search-results.html-twig is printing out what is considered "content" - we do need a followup on this as well as the tags are not correct should be <article>

Yes Its also printing out search results for users, yes but we are aiming for 80% usecase not every-possbile-thing-that-might-happens-so-we-better-make-it-complex-cause-what-if( https://www.drupal.org/node/2008464#principles)

The reason the "user" folder is there it make sense to group those 3 templates together, move them into "content" would break up collecting "all user theming" one place as we also have forum-user.html.twig , which is in dataset.
The "user" is normally a separate theming task, and if im not mistaken more templates could show up here, as we get deeper down to the templates.

We could argue that the templates should be merged into node.html & comment.html, but thats out of scope atm & those things would be fixed later on as we continue the cleanup work, that this patch atm is blocking for

so alex would you be satisfied if we moved :
user.html.twig & username.html.twig into content (even that its not but its bound with a node the same way as mark.html.twig is)
forum-submitted.html.twig over to "dataset" (even that its not a data set but in the same way as tablesort-indicator.html.twig is connected into this)

+1 to search-result being primarily contentish, even if you can also search users. Back to RTBC.

Im fine eater way with killing the "user" folder it & move the templates to "content" & "dataset", as they do follow the same reasons for mark etc as mentioned in #212 but then thats it (i hope) - But this can just as well been done as we hopefully merge the templates...

Intellectually I know users are just entities, but in practice users are special. They deserve their own folder IMHO. I would leave it the way it is.

btw is this a bikeshed now ? ;)

Sorry I missed the previous discussion. I was cowering in the 3rd bikeshed from the left.

(Courtesy webchick)

RTBC+1

So on an issue about discussing folder names, it is a bike shed to discuss what those folder names should be? And if the folder names don't matter (as in the colour of the bike shed example everyone seems so happy to use) then why do we have this issue in the first place? Should I close with won't fix then?

That said, I'm happy that the content stuff has been removed from the admin. Wrt to search-results.html.twig I still think the current folder is wrong. We're putting a listing of things in a folder full of templates of single things. Also I'm fascinated that the 80% use case is deployed here after the discussion about copying 100% of the templates to classy.

Anyhow I guess this is good enough and some change later will probably occur.

Template changes are not frozen in beta. Committed dc1bc4a and pushed to 8.0.x. Thanks!

Opened a followup to resolve the admin folder issues #2448213: Remove admin templates from Classy