Darren Mothersele

Software Developer

Warning: You are viewing old, legacy content. Kept for posterity. Information is out of date. Code samples probably don't work. My opinions have probably changed. Browse at your own risk.

Drupal Theme Generator Update

Apr 4, 2014

web-dev

It’s been a week now since I demoed my proof-of-concept for an automated theme generator at the Drupal show and tell event so I thought I’d collect together the feedback I’ve received so far and post an update.

###Wrong Approach?

Almost unanimously positive feedback. In fact, it seems other people have been thinking along similar lines:

The one opposing view I have encountered wasn’t actually against any of the ideas in the theme generator, but suggested that taking over Drupal markup was wrong and that we should be working with what Drupal provides. I know there are arguments for this, and if you want to go this route then you will need some other mechanism for documenting the conversion of your design to Drupal theme. If you want to argue this case, I’d suggest first try having that discussion with Morten, as I’m going to assume that we’re all OK with the concept of taking complete control of (completely rewriting) Drupal’s markup output.

###Annotation

In an earlier prototype I had started working with annotations inside HTML comments but I found these increasing harder to parse as the extractions became more sophisticated. Someone in conversation brought up ideas from KSS and suggested looking at CSS comments as an alternative.

I’m still proposing this as a possible approach (see Docblock), but for now I’m going to continue to annotate the markup (not the CSS) with x- attributes, as no one has had an issue with this, and at this stage it’s easier to work with QueryPath to create the extractions based on these attributes. It seems that annotating the markup with x- attributes will be acceptable as long as they are stripped from the markup during the build process.

It was great to get feedback from Brad Frost as his work on Atomic Design has been influential in the development of this process.

###In code, or config

In this first proof-of-concept, the generated theme is held in memory, well actually it is persisted as a Drupal variable containing a single object that holds the result of all the ‘extractions’ from the source. The original intention was that this would actually be a ctools exportable, so that it could be exported and managed as part of the configuration management process for the site.

This is how the Panels flexible layout builder works. It has one parent layout plugin that programmatically declares child layout plugins based on the layouts you define using the layout builder tool. These child layouts are stored as exportable objects, so they can be exported using Features. The current Hyde theme generator approach is similar, except that the parent plugins (for layout or styles) programmatically declare child layout and style plugins based on the result of each extraction from the HTML source design.

Storing the result of the build in configuration or database raised some concerns, mainly over capturing the results in version control. These tweets summarise the issue:

Matt picks up on my original intention, in that the design/theme would be captured in code and be version-able because the translation is automatic from the design’s HTML/CSS/JS.

The difficulty is in managing any changes that happen to the generated code once it becomes a Drupal theme. This is exactly the problem that using the theme generator is trying to solve. That it provides a documented, repeatable conversion process, so that design can become part of the (agile) development workflow.

However, it is going to be unavoidable that some tweaking will be needed. This covers a couple more issues that were raised at the Drupal show-and-tell event:

The approach I am looking at to solve this, is one I’ve seen practised by other tools that involve code generation. For example, have you seen BDD using Behat? When define a test scenario in Behat it generates stub code for any unrecognised steps in your tests. For example, if you say “Given I am in a directory”, you would get the generated stub code:

/**
 * @Given /^I am in a directory "([^"]*)"$/
 */
public function iAmInADirectory($argument1)
{
  throw new PendingException();
}

I think the theme generator could do something similar for elements marked as requiring pre-processing in the template file. This needs some further thought and perhaps a couple of experiements.

###Terminology

Still struggling with naming conventions. If this is going to be a more general tool then need generally understandable terms (like ‘component’). But, need to avoid overloading terms even more, as it’s already quite confusing having SMACSS modules, Drupal modules, panels, blocks, boxes, styles, layouts. urgh!

###Next steps…

So, I’m going to revise the current proof-of-concept and produce a second prototype. This time as a Drush command that generates an actual Drupal theme. Rather than holding the extracted theme in configuration it will generate a theme folder, that will include all the usual Drupal theme files, plus any plugins for Panels layouts, styles, display suite etc, and the CSS/JS copied across from the source design.

This will allow Hyde to generate stub code for pre-processing or other programmatic tweaks that are needed to get Drupal’s output to match the design markup. I also think people will be more accepting of this approach as it’s probably more like how it is expected to work.

My worry is that people will then hack the generated theme, it will go out of sync with the source design markup, and that will break the whole process.

If you want to get involved, please drop me a line. I need input from designers, themers, and developers. In particular, I’d be interested to speak to anyone else already using Atomic Design and/or SMACSS on Drupal projects.