Problem/Motivation

One of the things to come from #1801582: Add a new, non-default framework-based theme to Drupal core was the want to implement a system similar to Jacine's proposed Theme Component Library for Drupal 8 Core. While I'm not sure if we're going to have time to implement everything we need, I believe we can start and, if it doesn't make it into D8 Core, we can continue this in Contrib.

Proposed resolution

I think the steps to start are something as follows:

  • Get feedback from more frontend to see if most of us agree this is the direction we want to go. seems like we agree here?
  • Determine how much of this proposal is already covered by other proposals (I believe Twig actually may cover a fair deal of this) Twig can use this issue :)
  • Determine if there is enough time to get this complete to an acceptable phase before the D8 feature freeze. LETS GO!

Remaining tasks

  1. Decide on & create item components
    • menu
    • item_list
    • table
  2. Decide on and create container components
    • a title and a thingy (block, comment, etc)
    • an administration page
  3. Re-work all existing markup from core to use these components: (This task belongs to TWIG)

More from the original issue

The following is, what I believe to be, a brief high level overview of what the Component Library needs to do and what it should not do.

Jacine sums up what is looking to be accomplished brilliantly in her post (link above):

Components are usually a combination of containers and formats that make up custom UI elements. Examples of components include Tabs, Vertical Tabs, Form Widgets (like password confirm and machine name), Carousels, Accordions, etc. Components usually have recommended use cases for application. Their implementation can vary from CSS and JavaScript standpoint, but their markup is pretty standard.

The goal of a Theme Component Library is to provide the markup and let the theme handle the CSS and JavaScript

  • Provide a set of common markup patterns as wrappers to be called (button patterns, unordered list patterns, ordered list patterns, headers, def lists, form elements, etc…) with the goal of having one set of predictable, easy to override, semantic markup. Jacine has done a lot of great work on the demo page she put together already.
  • Provide an easy way for themes to override a specific pattern and have it apply to all patterns without the use of override functions.
  • Provide predictable, precise, and useful CSS classes based on SMACSS guidelines that are easy to override or remove, ideally without the need of lots of override functions.
  • Allow for components to ingest other components and template files (where appropriate).
  • Disallow, to the best of our ability, markup to be directly injected into a component from a theme function or for a theme function to output markup directly without using a template/component. This is extremely frustrating currently and continuing to allow this would defeat the purpose of the component library.
  • Provide development and UI hooks to allow developers and site builders to make use of the components through code or through UI
  • Provide development hooks to allow developers to add additional components to the Component Library
  • Provide a Style Guide menu callback with all components on screen (or divided between major groupings) to allow for easy theming
  • VERY SPECIFICALLY do not include any default CSS or JS for these components unless absolutely necessary (such as in the case of widgets). When default CSS or JS is needed, make sure it is as minimal as possible and very easy to override/remove, ideally without a process/preprocess function. Think Stark as the default theme for these components, not Bartik.
    • This may seem like it's missing the point of the component library, but from a front end developer's perspective, this is precisely what we want; predictable, semantic, clean markup that's easy to override that doesn't come with a bunch of CSS or JavaScript that we need to wrangle into place. While it will make life harder for site builders or backend developers not seeing their vision 100% initially, the goal here is to make frontend's life easier. Additionally, doing it this way allows for Contrib to come in with themes/modules (the line will start to blur) that are style guides to style this all (opening up easy integration with Bootstrap or Foundation or Skeleton or whatever in Contrib).

Comments

sun’s picture

anthonyR’s picture

I believe we need this somewhere in the future. This can be the missing link between the front and back-end community to make the patterns easier to use and discover.
This issue is the elegant solution instead of the Bootstrap integration #1801582: Add a new, non-default framework-based theme to Drupal core.

AdamGerthel’s picture

This would be a major asset to Drupal. I love the work Jacine has done. Most Drupal projects end up with the last 20% taking 80% of the project time - often related to theming difficulties.

jwilson3’s picture

Component Library++.

With the amount of bullet points on this issue, I can see this turning into a meta issue; take this one for example:

* Disallow markup to be injected into a component from a theme function or for a theme function to output markup directly without using a template/component.

We'll need to probably create an issue for each core module that returns output in a theme_somesuch_thing() to replace all their theme_* functions, extracting content massaging and meta/attribute additions to preprocessor functions (if not using them already), and place all markup generation in template files. To save on the amount of rewrite work this will involve, this key part of the issue almost becomes dependent on twig issues like this one: #1697854: Allow modules to provide both .twig and .tpl.php templates temporarily until twig is the default engine being in place first.

catch’s picture

Priority: Normal » Major

I don't think there's any dependency on Twig to start removing near-duplicate theme functions. A good example would be #1778990: Merge theme_pager_link*() theme functions into theme_link() and #1598886: Clean up pager theme functions where we went from nearly adding 2-3 new theme functions to removing some instead.

I'd suggest a meta-issue which has a list of all the array keys from hook_theme() with all core modules enabled, then try to group those into similar-ish functions and open issues to consolidate ones we think can be removed in favour of a re-usable one. Some of the individual patches might end up depending on Twig but there's loads of up-front work which could have happened at any time

Also following up on a comment from the Twitter/Bootstrap issue, it's absolutely not the case that removing 200 templates/theme functions means themers end up being unable to customize markup in a granular way - that's what theme suggestions are for. The reason we have hundreds of theme functions in core is because we're not properly using theme suggestions in core, so that is straight clean-up work that can happen right up to code freeze (i.e. after feature freeze). There are other parts of this which are more feature-y but that shouldn't hold up bringing some basic sanity to the organization of existing theme elements in core - and from there it'll be a lot easier to see what the remaining requirements are.

catch’s picture

RobLoach’s picture

I'm not doubting our ability to create an awesome component library. I'd just be ashamed if we did, when project owners of other libraries have openly talked with us, stating that they'd be willing to help us out.

pixelwhip’s picture

I think this is a great idea. It makes sense to me that these components be defined independent of other core work. As a front-end dev, it would be more useful to have generic HTML markup patterns rather than Drupal specific components -- at least as a starting point. For instance, a generic 'Article' or 'Section' component defined here, could be used by many different entities such as Nodes, Users and Blocks. Likewise, a predefined list component could be used to markup Pagers, Menus, Breadcrumbs, Views etc.

IMO, the key to getting more front-enders contributing themes is a good component library that is well documented and extensible. I would guess that the success of Bootstrap and Foundation is more about their documentation and less about their implementation. The idea of a style guide that can be viewed directly on a site could be the key to this. Style guide has a good start on this, but could certainly be improved upon. Some things that come to mind are the ability to group components into different pages and include the raw markup and template code much like Jacine did with her examples in the component library.

I also think Stark should provide no stylesheets (layout included) unless absolutely necessary. A separate core theme could provide a basic framework similar to Bootstrap or Foundation or even utilize one of those if it would be quicker. I personally don't feel core needs to provide the ultimate front-end framework theme out of the box, but should provide the tools for that unicorn to be birthed in contrib.

pixelwhip’s picture

Didn't mean to remove that tag.

criz’s picture

Great one, I think that a Drupal component library like this would be a big step forward!

@Rob Loach

Should the Drupal core theme component library really copy/adopt the html provided by an external framework as ZURB foundation or Twitter Bootstrap? I don't think so, as there is plenty markup included that only makes sense with their JS and CSS.
 And like stated in the issue description the component library shouldn't include any default CSS or JS.

The markup provided by Drupal core modules should be as lean as possible. It's the job of the theme to add all styling and special classes if needed, and themes are the place where frameworks like Foundation or Bootstrap can step in.

Of course there could be a Bootstrap Core theme, but it should have to add its special classes and JS and stuff like every other theme/framework would have to.

Of course we should have a look at the markup suggested by these frameworks, but imho core theme components should just be inspired by the best/gist of it. The better (leaner and predictable) the components are designed, the better they can be used together with multiple external frameworks.

Of course it is awesome and important that maintainers of external libraries are willing to help out and adapt licensing and stuff, I am a big fan of joining forces, but this might be more important for #1801582: Add a new, non-default framework-based theme to Drupal core.

RobW’s picture

This issue is about core code, and needs to be entirely framework agnostic. The place for framework integration is in themes. We can look at other frameworks for structural inspiration (although I think there won't be much of use at this basic a level), but the guiding principle here should be reusability, semantics, and **reduction**. Drupal core markup should be a solid base on which to build, and have absolutely nothing that needs to be stripped out in order for a professional front end developer to begin integrating whichever framework or custom code they choose through **addition** of code.

This conversation has already been had in a recent issue which sparked the creation of this one. Let's not derail. Frameworks are out.

RobW’s picture

If we don't know how things are going to fit together and how flexible our components need to be it's going to be hard to standardize the theme system and build a useful component library. So we should start by tackling template file inheritance. Note: I’ve tried to take most examples from documented sources like the D7 template suggestion page and Entity API. And oh damn this is longer than I thought it would be. I apologize in advance. Here we go...

Current state

Templates cascade by template directory placement and template suggestion.

Templates with the same name override each other depending on the directory they live in, from least to most specific:

  1. Module directory
  2. Base theme directory
  3. Child theme directory

The theme function or preprocess function provides template suggestions. Variables are used to create a naming scheme that serves specific templates when certain conditions are met. For example, the default D7 field template suggestions, from least to most specific are:

  1. Field.tpl
  2. Field--{field type}.tpl
  3. Field--{node bundle}.tpl
  4. Field--{field name}.tpl
  5. Field--{field name}--{node bundle}.tpl

So the template field--article.tpl would be used to display every field on the article content type.

What needs to change

  • Since multiple modules will now be specifying a single base object template, we need to add a new, more general source directory that holds all of the base object templates.
  • Template name variables (the parts of the template file name I've written in {curly brackets}) and variable combinations vary wildly depending on the module providing the themed output. Improving and standardizing the template suggestion cascade will help us understand the markup that needs to be included in our base object templates.
  • Some inconsistencies and profanity inducing aspects of the current theme system can be addressed while we’re mucking about in here too.

New lowest level source directory

This is the easy one. A new object library module will be added to core. This module will have a “theme” directory that contains all of the base object1 templates, along with any front end developer helper features we decide to include (e.g., rendering test pages that contain all common html elements or objects).

Modules will now specify a base object as the first theme suggestion, even if they immediately override it with their own module level template (it's beneficial to front end developers to know what the template in use's starting point was, and might become important for more advanced functionality). The goal is for as many modules as possible to use and re-use base object templates or base objects with slight alterations, creating repeating html objects across a site.

Our new location based cascade will be:

  1. Base object library
  2. Module directory
  3. Base theme directory
  4. Child theme directory

1: In case some of you have no idea what I’m talking about, an html object is a small snippet of html repeated in similar semantic or display situations across a site. It’s a way of standardizing output for easy styling with css, and has some nice side benefits like increasing gzip performance and often reducing code cruft. For more info, see anything on OOCSS or the media object.

Template names, name variables, and cascade

OK, this is going to be a little longer.

  • Current template suggestions use different name variables in different combinations, and have different levels of cascade. That’s too many “different”s.
  • Template naming schemes are hard to guess and can’t be discovered without Devel Themer, Poor Themer’s Helper, or reading module code.

Let’s look at some common template name variables:

Common variables derived from entity properties

  • Entity label, sometimes called name. Example: field--user-address.tpl
  • Entity bundle, sometimes called type. Example: node--blog.tpl
  • Entity type. Wait, I thought we already said type? This is the entity type name, like field, taxonomy term, or node. The generic and hard to understand bundle is going to have to supplant node type in docs for this to make any sense. Example: node.tpl
  • Entity subtype. Whaaaaa? Is this a dream? No, this is an inherent type separate from bundle, usually describing what the entity contains. Type is just a really versatile word. Example: field--boolean.tpl (field--{field type}.tpl), page--node.tpl (where the page contains a node as opposed to a taxonomy term list or a view).
  • Entity serial ID. In D8 we might want to also include entity UUID; although that would be ugly as shit it would also be useful as hell. Example: node-22.tpl
  • Entity view mode. All yall themers know what I’m talking about. As mentioned in another thread, the single most useful theming addition to D7, view modes are a way of describing the context of a piece of content. Example: node--teaser.tpl, field-collection-item--slideshow.tpl.

Less common entity variables and variables derived from other things

This is a partial list; inclusion is no endorsement and vice versa.

  • Providing module. See block.
  • Delta. See block, but could be used elsewhere and probably is.
  • Containing Region. The region a renderable array is contained in.
  • Module specific attributes. A long list including forum name, page path, poll’s “is block”. Many of these are valuable and will be kept as layers on top of the default entity suggestions, while others can be removed in favor of standardized, modern names (e.g., “is block” can be removed in favor of the more configurable view mode).

Suggested Solution

Create a standard pattern and minimum theme suggestion list that all modules must implement. We'll want a cascade reference for module and theme developers, a simple base object cascade (we want to give some options so developers keep using those base objects as long as possible), and a default implementation of the beyond-base-object cascade. Since a lot of themed things are entities, Entity API’s cascade seems like a good starting point, although its current implementation is too limited to be really useful.

General cascade

Every name variable is not going to apply to every renderable array. But for module and theme developers we need a canonical list of all general name variables from least specific to most specific. This can and should be revised and added to when necessary.

This list is a draft. Please comment and refine.

  1. {entity or render array name}.tpl. This is the base that all tpls start with. Assume it as a prefix to everything that follows.
  2. --{view mode}.tpl (very general: all nodes when teasers)
  3. --{region}.tpl
  4. --{module providing}.tpl
  5. --{subtype}.tpl
  6. --{bundle}.tpl
  7. --{label}.tpl
  8. --{serial ID}
  9. --{UUID}

Base object cascade

This is a little different than the entity cascade. Very little information is consistently available or needed at this level, since you can apply a base object to aaaanything. If you need to use the entity label name variable you’re far past the level of specificity intended here, but I can see a use for s to have different structure or classes in a teaser or a specific region.

Note: when a single template has multiple name variables, they are ordered from most specific to least specific.

  1. {object name}.tpl
  2. {object name}--{view mode}.tpl
  3. {object name}--{region}.tpl
  4. {object name}--{region}--{view mode}.tpl

If others are adamant that base objects should have no template cascade I would be fine with that as well.

Entity cascade

I’d like to see a generic entity cascade be the base for all entities in D8. My goal would be for it to work with field and node with no module specific revisions, and with taxonomy with just a few extra suggestions added to the middle. Because we’re starting with a base of five name variables, I’m not going to write all of the combinations out -- we would have every combination of non-id based name variables overriding each other based on the number of name variables, or if they have the same number then the weight/primacy of the leftmost different variable. It sounds confusing but when you see it in a directory it’s pretty easy to understand. We’d probably want to generate the theme suggestions with some logic in the theme or preprocess function to avoid writing out a page of template suggestions.

  1. First the plain old entity type:
    {entity type}.tpl
  2. Now the dynamic list. Entity type is required, but everything else is optional.
    {entity type}--{name}--{bundle}--{subtype}--{region}--{view mode}.tpl
  3. And finally the ids, where it only makes sense to add context based modifiers.
    {entity type}--{serial ID}.tpl
  4. {entity type}--{UUID}.tpl
  5. {entity type}—{serial ID or UUID}--{region}--{view mode}.tpl

A brief note on a related profanity inducing situation

As promised, I have a related issue that I think is would be good to raise here. A couple of years ago, using the #prefix and #suffix render array properties to add wrapper markup found its way into some tutorial that reproduced itself across the internet, making theme developers everywhere scream and curse the world and cry themselves to sleep surrounded by empty liquor bottles.

I propose adding a wrapper--{the full file name of the template you want to wrap}.tpl, using either #theme_wrappers or a new function. The wrapper should not be able to be nested (no wrapper--wrapper--whatever.tpls), and unfortunately won't be able to be used as a wrapper for multiple templates, but it would more than make up for the loss of power with ease of use. This would seriously improve the reusability of base objects and the happiness of developers everywhere.

Questions

Some questions that came up as I was writing – those more qualified please chime in.

  • Are view modes entity specific, or just another piece of a render array that could be applied to anything? I don’t think pages or views can have view modes, so I’m inclined to think the former, but I could be wrong.
  • Are views entities or configuration in D8? They’re going to need special consideration one way or another.
  • Would having such a robust combination of template suggestions completely destroy performance?
  • We'd need to standardize "subtypes" in some way. Even a solid definition would go a long way.
  • A big one: Namespacing. Look at #1137024: Field--your-field-collection.tpl.php cascades and overrides all collected field's tpls, it tells you all you need to know. If there's a view mode slideshow and a node bundle slideshow, it's very possible to get unexpected behavior.

Thanks

This turned into a serious essay. I can’t believe you read the whole thing.

jwilson3’s picture

Wow, very impressive investigation there. Couple things.

5. Field--{field name}--{node bundle}.tpl

Does anyone else besides me find this one to be backwards? I guess from the database table perspective, sure you can have the same field used on different content types, so maybe its hard to justify it logically, but from a file-organization perspective, I'd want see have all field-article-{field name}.tpl grouped together.

In your "general cascade" section {view mode} comes before {region}, but in the subsequent "base object cascade" section, it comes after. Was that on purpose, and if so, is this something that could be fixed for consistency?

RobW’s picture

I think view mode always comes in before/ at lower priority than region. Reviewing this on a phone, so maybe I'm just not seeing the mistake.

I see what you're saying with bundle and name. If the mental model is like folders, you want them arranged from most general to most specific. But everything I've seen in core and contrib uses the pattern {base template name}--{most specific variable}--{least specific variable}. I could definitely imagine switching that around.

jwilson3’s picture

In your "general cascade" section {view mode} comes before {region}, but in the subsequent "base object cascade" section, it comes after

(A) I think view mode always comes in before/ at lower priority than region. [...]
(B) [...] everything I've seen in core and contrib uses the pattern {base template name}--{most specific variable}--{least specific variable}.

(A) makes perfect sense, given that i now understand (B), tho, I still think its bassackwards. This statement also particularly threw me off, but now makes total sense. #facepalm

when a single template has multiple name variables, they are ordered from most specific to least specific.

jwilson3’s picture

I'm on the fence about namespacing the variables in the template file names. The file names will get horrendously long, and hard to look at/organize/control. Anyone implementing custom views templates already knows what I mean. Maybe this thought should go on #1137024: Field--your-field-collection.tpl.php cascades and overrides all collected field's tpls, but what about an alternative, but parallel structure for namespaced directories underneath /templates, just for the case when you need lots of custom templates in custom regions, view modes, etc.

templates/field-{fieldname}.tpl.php => could also be =>
templates/fields/{fieldname}.tpl.php

^ is not a great example, but:

templates/field-{fieldname}--{region}--{view mode}.tpl.php => could also be =>
templates/view_mode_X/region_Y/field-{fieldname}.tpl.php => or maybe even =>
templates/view_mode_X/region_Y/fields/{fieldname}.tpl.php

JohnAlbin’s picture

Issue tags: +Twig

I would like to point out that a refactoring of Drupal's theme hooks to use Jacine's component idea was one of the main goals of the Twig work. It was just, necessarily, a later step in that process. Straight port to Twig first, then dramatically simplify Drupal's "library" of theme hooks. (I put library in quotes, since Drupal's current collection of theme hooks more closely resembles a giant pile of dirty laundry.)

But I do think the time is right to start discussing a component library within the context of Twig templates (now that most of the templates have been converted to Twig inside the Twig branch). Doing this in PHPTemplate files first is nonsensical.

RobW’s picture

We shouldn't start filing issues against php templates, totally agree. What we can do in this issue is look at the system's structure and eventually create markup examples, parallel to twig work without writing a bit of compilable code.

My proposal above I think is a good start -- introduce a new template suggestion level, standardize the template cascade with an eye to SMACSS (region and view mode template name vars), and introduce a wrapper template convention. I think they're clear wins, and I'd love some feedback, especially dx and implementation roadblocks. Especially with feature freeze 45 days away.

Fabianx’s picture

@RobW: Performance is not a problem as suggestions are saved during theme registry build, but the long filenames are difficult, I agree.

How are others solving suggestions like this?

Also: Modules can't provide suggestions right now and (pre)process does not run for suggested entries.

RobW’s picture

Also: Modules can't provide suggestions right now and (pre)process does not run for suggested entries.

Can you explain? Many modules provide theme suggestions right now, and I'm not sure what you mean by entries.

Fabianx’s picture

@RobW: I meant theme suggested templates, like mymodule--1.tpl.php.

At least I saw no code for that in the engine, so if it works, I would be surprised :-).

RobW’s picture

Ah, right right. The only place it's used currently is in Block, as in block--{module that provides block}.tpl.php. I included it for completeness, and can imagine some areas where it could be useful, but wouldn't cry if we decide it's rarely used and take it out for simplicity.

To rephrase, the long string of template name variables includes every core type possible. Modules wouldn't need (or want) to add every one to their render array, for example saying a node entity is provided by node module is extremely redundant. The list would be there so every module that creates themeable output adds template suggestions in the exact same order, and there's an expectation of what should be available before you read specific code.

Anonymous’s picture

Please see my comments here as input for this discussion:
http://groups.drupal.org/node/259593#comment-836973
http://groups.drupal.org/node/259593#comment-836988

In response to the group discussion Designs for unified Blocks and layouts UI

We may be able to kill two birds with one stone here, and possibly save a lot of work.

The article as a whole is interesting to read as well as the comments.

Data and Markup Entry at a Block Level

Pulling data in straight from the module through views without markup, and setting markup and assign data in the block for output to the theme would simplify theming as well. For example:

Markup:
heading: h1/h2/h3
aria role: navigation
container: div
container id: sidebar-menu
container class: block
list-type: ul
id-for ul: menu
class for ul: easy design menu
li class: leaf
Do you want first, active, and/ or last leaf: (checkboxes)

Assign/ Enter data:
heading: plain text/ dynamic
li: text/ dynamic value (for text offer the option of multiple fields e.g. for three li items)

It's a really crude example, but a friendly user interface should be possible. For example having the markup element in front of the data element field. As well as being able to set and call on block templates to reuse (across websites). This would tie in with the new admin interface in the group discussion, lower the theming threshold for designers, and could make the theme layer independent of the core. This could allow for greater durability of themes. Possibly reducing maintenance on themes. You could hide al this stuff from a normal user, but for designers have a switch in configuration that shows this. (One central location is preferred to having to click override every single item.) Could maybe even prefill some of the values for design features. For example have a jump-menu with presets such as a menu or table. Just select table, and fields will show, where you can tell it to add dynamic data. How many columns do you want? 3. Okiedokie. If you have no classes for a markup element, then no class is added.

Done the right way this could mean huge amounts of improvement and speed with working. You could roll out a theme in fractions of the time that it takes now. As well as it being potentially way more flexible in site-building and design needs.

Accessibility and W3C

We could also hook into modules that check markup based on accessibility and W3C. Some of which already exist within the Drupal modules:

Accessible Content module: http://drupal.org/project/accessible_content
Node Accessibility module: http://drupal.org/project/node_accessibility

There is a need and wish with some organisations to be able to check some of the accessibility themselves in order to save budget on external testing, as the basic stuff can be done by themselves, while extensive testing can then still be done by testing organisations. We could possibly work with those organisations as well when it comes to coding stuff. Good W3C and accessibility is good for allowing a broad user base acces to content as well as being excellent for SEO.

Automatic tpl.php Creation

If needed you could have tpl.php be created automatically. This would mean you wouldn't have to change the current theme handling.

Even people that don't know how to code, know how to use or can learn a GUI

Most people know how to work with a GUI. Solves the problem of having to code. Would allow resources to work on twiggy, as the code for the admin panel needs to be written anyway. And also designers do not have to learn Twiggy. Heck, might not even need something like Twiggy, reducing an area of maintenance as all the markup is rendered automatically. The designer would never have to go into the code, but could see the site through Firebug for example.

In Conclusion

This work way would allow for a greater amount of flexibility, and easier data handling and output. This method could in theory make working with Drupal a breeze from a site-builder/ design standpoint. Plus, views has already some of this implemented, so we can build on that.

Feedback

I'd love to hear input on this, so please feel free to comment.
This in relation to the issue, and the problem we're trying to solve.

Fabianx’s picture

For all that are wondering:

http://jacine.net/post/19652705220/theme-system

is Jacine's great post about this.

RobW’s picture

@DesignDolphin: Those ideas are out of the scope in this issue, and probably D8 since there's around 40 days to get new features in. I personally am not interested in the "define granular markup through a UI" route, because if you know what a ul or aria role is, you know how to code. If you're interested in pursuing it further, please open a separate issue.

Anonymous’s picture

#26

If you know what a aria role or a ul is you know how to code.

How do you figure that? Maybe we need to define what you and I understand with code first? Because you'd be wrong if you mean PHP, JS, or Twig for example. This is part of the problem if that is the starting point from which you base a solution for this. Rule #1:
Keep It Stupid Simple

Especially for people working with the product. In this case the designers.

Besides it's not a matter if we know how to code, it is how fast and easy we can do the work. Another point being that being able to code and being able to code in Drupal are two different worlds.

Also a deadline for features in this case, in it's own regard, is not the best tool for making important decisions that affect a large part of the community and people that work with the product for the next coming years. We need to be able to move on new ideas, evaluate those, and implement them if they are better. Either through core, or through a module. Ideally working together on an idea from both ends, touching base every once in awhile, work on implementing it if it makes sense, and discuss it if it doesn't but there is a need.

Those ideas are out of the scope in this issue

How are these ideas out of scope? I'm sorry, but I don't see it. Could you please be so kind as to clarify your point?
I'm reading the points at the top of the page and discussing this. Additionally I'm touching on the line set for core, offering options that could possibly improve things, and allowing peer review of the idea in order to come to a solution of the topic this issue is about. In that regard your comment makes no sense to me, but maybe you interpreted it differently.

Anonymous’s picture

Title: Implement Theme Component Library » [Meta] Implement Theme Component Library

Changing this to meta, as I sense a lot of need, reading the comments, to discuss the finer points of this before we actually start writing code. Without derailing the project, just starting writing code on this, may lead us to working besides each other instead of with each other (and having to redo/ do double work).

At the same time, people can post code to the drupalcode bin, or something to that effect when people have ideas they want to put in code. Opening a seperate issue for code on this may be a good thing. The reasoning being that a lot of discussion is already on this issue. Having a issue for code will keep it clean.

For those of who have blogs/ website, maybe posting lengthier articles there and posting a link here for discussion may keep some of the lengths of the posts down as well. (edit: Although if we open a project page we could have seperate issues for this, as well as allow for specialized sections, keeping things centralized.)

Maybe we can set up a irc/ skype meeting between people who want to work on this, and if we want do a code write-up/ mock-up before the 40 days are past.

Additionally with Symfony getting into core, we can do this as a module as well. I'd rather spent some more time on this, and have a decent module in 8 for example (or possibly even during 7 lifetime still e.g. prototype) than rushing through code. So a mock-up presentation may be better as this allows for sharing within a greater audience, getting valuable input e.g. at Drupal Cons, and all the other positives that can go with that.

For the Symfony idea, we could have a bridge where we declare Drupal stuff, then write the working code. This should allow for independent development, while if anything changes in Drupal we can change this in the bridge. It may also allow for getting away from some of the legacy code (which I understand is a wish) for example and start from a clean slate. Later on this could be build into core. Think of this like changing the shock absorbers of the car with custom ones. With Symfony theoretically this should be possible. As well as maintaining performance rates and (re)usability. We could even do this as PHP OOP/ MVC but that may be straying to far from the fold. That is a good issue to discuss though. Getting a plan for that will help this get realized.

This issue is too important to leap in heads first, and needs a solid plan. Doing it this way will also allow for brainstorming. Which I feel this is in at this stage, looking at Jacine's original post as well. Doing some nice visual mockups and presentation, along the way, may actually help get this realized.

Let's do try to set some deadlines though while we get this going. We could open a planning page somewhere. Maybe open a project page? It might be a nice container for this.

RobW’s picture

Title: [Meta] Implement Theme Component Library » Implement Theme Component Library

DesignDolphin, I admire your enthusiasm, but please don't derail this issue.

This issue was posted by Snugug in response to a very long discussion in the "Add a framework based theme to core" issue, along with discussion on IRC and Twitter. The need for a theme component library has been discussed, vetted, and approved by many members of the community, including those heading initiatives in Drupal 8. As stated by the name, this issue is focused solely on implementing an html theme component library in D8 core, based heavily on Jacine's currently abandoned work.

Please open up another issue to discuss meta issues or alternate approaches D9, or a sandbox for D8 contrib.

Anonymous’s picture

This issue was posted by Snugug in response to a very long discussion in the "Add a framework based theme to core" issue, along with discussion on IRC and Twitter. The need for a theme component library has been discussed, vetted, and approved by many members of the community, including those heading initiatives in Drupal 8.

I can't read thoughts. This information should have been posted in the original issue. ;-)

All I see is a lot of discussion, and an opening issue with a-lot-of points to cover.
Too many for me to make any sense of to code for.

I have spent hours doing research on this subject, not counting my years of experience. Was asked multiple times to help out in this issue cue, and despite my schedule took some time to help out.

All I see is people discussing the technical side, while other people are saying it is offtopic. Well, color me clueless.

Anonymous’s picture

Title: Implement Theme Component Library » [Meta] Implement Theme Component Library

@RobW,

Considering your own contribution in this topic with page long theories and hardly any code I hardly find you the person to judge. Furthermore suggest we keep this meta, and go the route in #28.

Referring to the main points in the opening issue:

  • Get feedback from more frontend to see if most of us agree this is the direction we want to go.
  • Determine how much of this proposal is already covered by other proposals (I believe Twig actually may cover a fair deal of this)
  • Determine if there is enough time to get this complete to an acceptable phase before the D8 feature freeze.

Suggest we work on that here.

If you want to discuss this further please feel free to contact me through my contact form.

Now, please if you have some content or code to contribute feel free, otherwise refrain from commenting.

Marking this Meta. Not making a code issue yet, because I want some consensus from people on this on a workable route. Your opinion is known @RobW, thank you for sharing this, I want to hear from other people as well on this.

steveoliver’s picture

Title: [Meta] Implement Theme Component Library » Implement Theme Component Library

Hey Dolphin dude, please let me buy you a drink at badcamp. You sound like you've got a lot of great ideas.

sun’s picture

Title: Implement Theme Component Library » [meta] Introduce a Theme Component Library

Please note:

I've re-opened #1804614: [meta] Consolidate theme functions and properly use theme suggestions in core, since it is much more actionable and already contains a list of issues that can be worked on.

Follow that issue to work on and keep track of actual changes regarding theme function and template consolidation.

Please use this issue here for general Theme Component Library discussion.

Speaking of, the issue summary could be shortened and clarified. Additionally, the task of consolidating theme functions and templates is pretty clear (see issue above). However, @jacine's idea and proposal of a component library actually goes way beyond a simple consolidation, which only marks the initial step. The "actual" architectural change proposal for a Theme Component Library needs conceptual design work and clarification.

I have to admit that I asked her multiple times to understand what the concept of "components" and "items" means in actual terms and examples, but did not really understand it. IIRC, the only initial understanding I was able to gather was something along the lines of: "For example, vertical tabs is a component, but something like theme_links() is not. Why? Dunno, ask her again. ;)"

chx’s picture

Unpublished my comment, removing myself from issue.

chx’s picture

Issue summary: View changes

Updated with quote from Jacine

jenlampton’s picture

Issue summary: View changes

add component list

jenlampton’s picture

I spent some time on the issue summary today, and added the item and container components we identified a need for, and worked on this weekend at the BADCamp Twig sprint. I expect that as we spend more time going through our existing theme functions, we'll start to identify more and more things that are similar, and can be grouped together into components.

I believe we should try to consolidate similar markup patterns into components as we convert all the theme functions to Twig templates. Our attempt at the Theme Component Library won't be perfect the first time through, but I think we can still make a big step forward.

My hope is that rearranging markup structures couts as "tasks" and that we can continue to improve things well after feature freeze.

steveoliver’s picture

ry5n in IRC yesterday asked if we had discussed Twig macros. From the docs:

Macros are comparable with functions in regular programming languages. They are useful to put often used HTML idioms into reusable elements to not repeat yourself.

I don't think we have considered them yet, but it seems we may be able to leverage them in the Twig implementation of our theme component library.

dozymoe’s picture

  1. This is what I think of component library: symfony form widgets (twig). It's all about html than Drupal specific markup (Drupal Field div wrapper etc). Something similar to macro from previous comment.

    I dunno about the internals, but I intuitively know if I do {{ form_row(form.name) }}, I'd be using {% block form_row %} from form_div_layout.html.twig (the url I gave).

    This is the code I used to override symfony input rendering, so the input is rendered inside label:

    {% if form is defined %}
    {% spaceless %}
        {% form_theme form _self %}
    
        {# html form <input> element inside its <label>, also adds instruction markup #}
        {% block form_row %}
        <div>
        {% if not type is defined or type in ['text'] %}
            {% if required %}
                {% set label_attr = label_attr|merge({'class': (label_attr.class|default('') ~ ' required')|trim}) %}
            {% endif %}
            {% if label is empty %}
                {% set label = name|humanize %}
            {% endif %}
            <label{% for attrname, attrvalue in label_attr %} {{ attrname }}="{{ attrvalue }}"{% endfor %}>{{ label|trans({}, translation_domain) }} {{ form_widget(form) }}</label>
            {{ form_errors(form) }}
        {% else %}
            {{ form_label(form) }}
            {{ form_errors(form) }}
            {{ form_widget(form) }}
        {% endif %}
    
        {# additional instruction, for example when using custom pattern #}
        {% if instruction is defined and instruction.value is not empty %}
            <p class="{{ instruction.class|default('instruction') }}"><small>{{ instruction.value }}</small></p>
        {% endif %}
        </div>
        {% endblock form_row %}
    {% endspaceless %}
    {% endif %}

    This is the original:

    {% block form_row %}
    {% spaceless %}
        <div>
            {{ form_label(form) }}
            {{ form_errors(form) }}
            {{ form_widget(form) }}
        </div>
    {% endspaceless %}
    {% endblock form_row %}

    Pretty much copy/paste from several {% block form_* %}, no hook_form_alter() here ;) . I also added p class="instruction" something like Drupal input description.

    To use instruction you'd do {{ form_row(form.name, {'instruction': {'value': 'only lowercase letters, numbers, hyphen(-), and underscore(_) is allowed'}}) }}, I think. Uh, this is a rather old code, I forgot how it works.

  2. About theme suggestions, can we use {% extends "node.tpl.php" %} in node--BUNDLE.tpl.php?

    Why are we using tpl.php file extension... o_O

ry5n’s picture

Myself, along with the UX team, recently posted a proposed style guide for the Seven theme. However, the reason I’m posting it here is that besides being a style guide, it also attempts to codify a set of UI components for Drupal’s admin UI. In other words, it shows a themed subset of our Component Library, and might be of some interest.

ry5n’s picture

@sun From what I understand of @jacine’s work, she makes a distinction between Formats, Components and Containers.

Formats would be “native” HTML structures, like a <ul> containing any number of <li>s, or an entire <table>. I imagine that’s why she didn’t call them “elements”, since they may or may not be made of more than one tag.

Components would be composed of custom markup: formats and possibly containers, with any required HTML attributes and attached CSS and JS. They define something over and above native HTML semantics, like an accordion widget, popup menu, splitbutton, etc.

Containers would be markup wrappers used across any number of components, like Nicole Sullivan’s Media Object.

ry5n’s picture

Issue summary: View changes

remove non-blocker from twig paragraph, reformat

markhalliwell’s picture

mitokens’s picture

star-szr’s picture

Version: 8.0.x-dev » 9.x-dev
Status: Active » Postponed

Sorry folks but this isn't happening for D8. Cleaning up the theme system in general and making sure our Twig implementation is as solid as we can make it have kept us quite busy over the past 2-3 years and we haven't really had champion(s) to see this concept through.

@JohnAlbin led a good discussion about this concept at DCLA: https://events.drupal.org/losangeles2015/sessions/drupal-9-components-li...

Having said that, I would love to see someone in contrib try to run with this, and we definitely shouldn't stop talking about it.

catch’s picture

Version: 9.x-dev » 8.1.x-dev
Category: Task » Plan

We should see what we can do in minor releases for this.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.0-beta1 was released on March 2, 2016, which means new developments and disruptive changes should now be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

webchick’s picture

Folks here might be interested in #2702061: Unify & simplify render & theme system: component-based rendering (enables pattern library, style guides, interface previews, client-side re-rendering) which has more recent discussion.

It's not clear to me if one of these ought to be closed as a duplicate of the others, or if they're discussing two different facets of the same problem.

webchick’s picture

Issue tags: +Drupal core ideas

Hi there! This is an issue that we'd ideally like to move to the new "Drupal core ideas" queue when/if #2785735: [policy, no patch] Agile process for bigger changes in core (Part A: Ideation) goes through (hoping for the next week or two). If you could read that issue and provide your thoughts on that, that would be great!

webchick’s picture

Project: Drupal core » Drupal core ideas
Version: 8.3.x-dev »
Component: theme system » Plan

Moving over to the new Drupal Core Ideas queue while we get this into shape.

lauriii’s picture

We had discussion about theme component libraries at DrupalCon Dublin with @alexpott, @davidhernandez, @Fabianx, @JohnAlbin, @joelpittet, @mdrummond, @tkoleary, @prestonso and @Wim Leers. We decided that we want to further postpone this initiative for 6 months from now to give some more time for this idea to mature.

In the meanwhile, we agreed that we will be experimenting components inside the Components module. We will try to move features from #2702061: Unify & simplify render & theme system: component-based rendering (enables pattern library, style guides, interface previews, client-side re-rendering) to the module. We will also focus on trying to solve common pain points that themers face using that approach by making improvements to the Theme API.

Some of the recognized pain points are:

  1. Some tools are missing. For example automatic discovery of libraries, components, etc. Essentially, the things we already said we wanted to do for the Components module
  2. Admin components on the front end (how to not break them)
  3. Drillability without losing data preprocessing
  4. Lack of Twig-based component library

Here is some actionable issues that me and @Fabianx created that would improve TX and can be worked in the meanwhile:

Fabianx’s picture

Wim Leers’s picture

Thanks, lauriii & Fabianx!

yoroy’s picture

Component: Plan » Idea
Status: Postponed » Active

The six months have passed! :-)

Maybe use the 8.4 cycle to come up with a plan, define priorities and first steps, then start implementing things during 8.5?

yoroy’s picture

Is this still the place? Do we want to take steps for this in the 8.5 dev cycle?

webchick’s picture

Some of the web component talk in the latter comments at #2645250: [META] Start using reactive declarative JS programming for some new core admin UIs seems to be overlapping with this discussion.

catch’s picture

I'd still love to see us continue to work on consolidating the existing theme functions/templates in core and deprecating as much as possible, to reduce the surface area of what needs to be tackled here #1804614: [meta] Consolidate theme functions and properly use theme suggestions in core.

aleksip’s picture

markhalliwell’s picture

mitchell’s picture

Here's a code base that matches how I hoped something like this could look:
https://github.com/AljanScholtens/taiga-boilerplate

nod_’s picture

Status: Active » Postponed

Postponing to simplify triage of the ideas queue on the component topic.

It would be helpful to highlight the needs addressed by this idea in the issue summary and add it to #3240805: [meta] Organize components-related ideas as well, to help consolidate all the different related issues.