Proposal to fix an underscore-engine issue: configurable output file suffixes

[geoffp]

As the maintainer of a design system that uses Underscore templates, I use Pattern Lab / Node to maintain it, and have written a pattern engine to be able to author Underscore templates. Unfortunately, our library of Underscore templates consists of files named with the .html extension. This destroys the frontend viewer's ability to render them, since the raw template overwrites the rendered output during the build step; they have exactly the same filename.

---

Therefore, as per @dmolsen's suggestion, I propose that the naming of these output files be configurable. I propose, for simplicity, that this be done with the addition of configurable suffixes for these output files, which would appear at the end of the base file name but before the file extension. Here is a proposal for the configuration structure, with the present-day scheme as defaults:

{
  ...
  outputFileSuffixes: {
    rendered: '',
    rawTemplate: '',
    markupOnly: '.markup-only',
  }
  ...
}

The timeline for this feature is ASAP. This is blocking our migration to Pattern Lab 2.0.

If I had permissions to do so, I would tag this needs-implementation because no POC implementation yet exists.

/cc @pattern-lab/voting-members

[dmolsen]

@geoffp -

In general I'm fine with this. I think there's only one issue at the moment. The name of the tab in the front-end is derived from config.patternExtension. Edit: the copy on the pattern tab will be derived from the extension of the file. Is that ok in your case or do we need an override for that too? Seems like in your case you'd have an HTML tab for markup only and HTML tab for the raw template.

System Input

The following options defined in the config:

outputFileSuffixes:
 - rendered: ''
 - rawTemplate: ''
 - markupOnly: '.markup-only'

System Output

Files will be rendered with the appropriate suffixes. .html will be automatically added to rendered and markupOnly. The original file extension will be added to rawTemplate.

@geoffp: So in this scenario I assume the patternExtension is html?

outputFileSuffixes will be passed as part of the existing config object.

Behavior

If these options are not configured and therefore undefined then the front-end will default to:

• for config.outputFileSuffixes.rawTemplate: ''
• for config.outputFileSuffixes.markupOnly: '.markup-only'

.html will be automatically added to the markupOnly option. config.patternExtension The original file extension for the pattern will be added to rawTemplate option.

Building pattern paths should set the "rendered" option so no need to be explicit on the front-end about it.

Example

A config with:

patternExtension: 'html'
outputFileSuffixes:
 - rendered: '.rendered'
 - rawTemplate: ''
 - markupOnly: '.markup-only'

Will end up with files like:

long-filename-here.rendered.html
long-filename-here.html
long-filename-here.markup-only.html

And two tabs called HTML.

If this is ok I can vote with a thumbs up.

[bmuenzenmeyer]

I am in favor of the proposal - making those filenames configurable makes sense.

@dmolsen -

In general I'm fine with this. I think there's only one issue at the moment. The name of the tab in the front-end is derived from config.patternExtension. Is that ok in your case or do we need an override for that too?

This issue has come up on two occasions now:

• Mixed pattern trees, where, for example, handlebars and mustache patterns might coexist
• Handlebars engine use where there was conflict between a user's .handlebars files and the configured .hbs setting.

Does this setting only control the tab label? If so, could it be derived from the pattern's file itself?

[dmolsen]

@bmuenzenmeyer -

Argh. Considering patternExtension is passed as part of the patternData (at least for PHP) then, with some modifications to how panels are gathered on the front-end, I think it would be doable. That tab could reflect the actual extension of the original pattern itself as opposed to the PatternEngine. It will in no way address the question I had for @geoffp but it's doable. I'll edit my round-up as appropriate to reflect that change.

To be clear, PL/PHP doesn't support a mixed "pattern tree." I don't really intend on going that route either. If your PatternEngine set-up allows it cool. Looking through your code it seems it does. My rules are a bit stricter than that and I only invoke one PatternEngine.

When @geoffp chimes in on what I wrote up I'll vote.

[geoffp]

@dmolsen -

I do think we should be able to change the title of the template tab based on each pattern's file extension, but in the Node case, the pattern engine loader is able to produce each engine's human-readable name (indirectly, via each Pattern object) based on the file extension, so I think in our case we'd prefer to use that value if that doesn't mess anything up for the PHP version. That way we wouldn't see HTML/HTML in the tabs, we'd see Underscore/HTML.

Apart from that clarification, I agree with everything you posted!

[dmolsen]

@geoffp -

Ah, got it now.

👍 from me on this change and I'll move it up the queue.

I have some fixes that need to happen to styleguidekit-assets-default anyway. This should be able to be rolled out in the short-term without changes to either core. Once it's been implemented in core things should all just work.

[bmuenzenmeyer]

👍

cheers!