Pages Should Build From Template templates

[dmolsen]

Pages shouldn't require their own mustache templates. Instead they should be defined simply by the custom data in JSON. Also, a Template should be able to have multiple Pages so that custom regions can be defined/previewed without creating a lot of duplicate mark-up. Custom Page JSON files should build upon one another to reduce duplicate content. For example, the file layout should look like this:

templates/
    homepage.mustache
pages/
    homepage.json
    homepage-emergency.json

homepage-emergency.json will use the templates/homepage.mustache as the base template. When rendering homepage-emergency the homepage.json file should be loaded and then homepage-emergency.json appended to/overwriting that data.

[bradfrost]

I like this idea a whole lot. I think it's a smart way to build variations of a template.

I also want to make sure it stays flexible enough to do it the old-fashioned way too though. Sometimes that might be required, and also JSON is great but is a lot more difficult than writing HTML. Again, totally all for this enhancement, but also want to support .mustache pages too.

[dmolsen]

Shouldn't be a problem :)

[bradfrost]

Is there any way to bump this up to the 0.7 release? I think this is a more core feature that affects more people rather than the multi-site stuff. As much as it would be great to see that.

Part of the reason why I'm asking is because I'm about to start a pretty big build that's planning on utilizing a lot of the dynamic data. So it would be great to have in there sooner to test things out.

[dmolsen]

@bradfrost -

Swapped.

[dmolsen]

@bradfrost -

After playing around with this I realized this can basically be done in Pattern Lab without me making any changes. To try it out do the following:

1. Copy the code from 04-pages/00-homepage.mustache into a new file 03-templates/03-homepage-test.mustache.
2. In 04-pages/00-homepage.mustache replace all of the mark-up with {{> templates-homepage-test }}
3. Generate your site

Voila! Your page is now using the template and overwriting the data with 04-pages/00-homepage.json. Ok, so I figure the use scenario would be something like:

1. Create a template with its own JSON file that has dummy data. You'll notice that there's a big hole in that test template when viewed in Pattern Lab. The mark-up between the original homepage template and homepage page is remarkably different.
2. Create a page with its own JSON file that has your real data.
3. In the page, rather than having mark-up, it'd just be the call to include the template.

This means that I don't have to change a thing. Honestly, it'd be a bigger change than I expected and it seems like there's a reasonable workaround that doesn't break anything.

I wish there was a decent way to build on a similarly named JSON file. I'll hack at that. Maybe an attribute in the JSON file that says which file it should be including/overwriting. Admittedly a weird loop but I'm hesitant to base this feature strictly on a naming convention. I'd also like to cut down on how much JSON you'd have to edit/manage.

[oscar-g]

What about approaching this the way other static site builders (Assemble or Docpad, namely) do:

You create templates/default.mustache and use {{ content }} or {{> content }} where you want the output of pages/home.mustache (or .html) to be.

In PatternLab we are building 'up': to build a molecule, we include an atom, and wrap HTML around the atom. However, including a template inside a page doesn't quite work because the purpose of a template is actually to wrap around a page; in other words, we need to be able to insert the contents of a page inside a specific region of the template (a div with a content class, for instance).

[dmolsen]

@oscar-g -

Not sure if this is tangential but just in case... I think "templates" and "pages" in Pattern Lab are slightly different than traditional site builders. Templates are quasi-wireframes. Pages build off of templates and show clients how they look with "real" content. This allows for the wireframes and a "real" content view to exist at the same time. This also gives us the ability to have multiple pages to show "states" of a template to a client. End tangent.

So the JSON solution as it exists today does essentially what you're suggesting. Elements defined in the page-related JSON replace variables (e.g. {{ content }}) in the patterns and mark-up that make up the template. Frankly, it's more robust than most because it's not about swapping out or replacing one generic area or a few YAML front-matter bits in a template. A lot of different things can be redefined. That's how we "insert the contents of a page inside a specific region of a template".

I admit that, in order for this work, the creation of a mustache file for a page that simply references the template is hack-ish but it works. It's not much different than choosing a layout for the content. Importantly, it works without me having to dig deep into core parts of the system. It turns out that saying a JSON file should be rendered in the exact same way as a mustache file would be and that PL should find that mustache file automagically is a little more involved than I expected.

Are you looking for PL to be a more robust site builder like the ones you mentioned?

[oscar-g]

@dmolsen,
Thanks for the explanation. I think PL has the potential to build production-ready sites. Some threads, like #30 or #64, discuss things that would make PL more similar to the other site builders I mentioned (add Jekyll to that list). What do you mean by robust?

[dmolsen]

@oscar-g -

While it has "potential" it might be a ways off. At the very least, a data storage format other than JSON would have to be explored. It can be... clunky ;) I'm not sure YAML is the answer tho.

After thinking on it robust was the wrong term. PL tries to push content into JSON files rather than hardcoding it within patterns themselves. This is just to get that flexibility between the low-fidelity wireframes and the high-fidelity pages. This means that PL might require a developer to define a lot more content outside of the templates/partials/includes than they might in the other solutions. I guess that's what I meant by "robust." More work ;) Though maybe more flexibility too.

[bradfrost]

@dmolsen Ah! I like the solution you laid out. That's smart. A simple include and swap out the JSON. Easy enough.

@oscar-g Pattern Lab is a tool for generating production-ready code, sure, but it's not meant to be a tool like Jekyll or other static site generators for deploying sites. It's important to point that out. Pattern Lab is already doing a whole lot, and I think trying to make it a full-on site generator distracts from its main goal of creating a design system.

[dmolsen]

@bradfrost -

I'm trying a big refactor of the guts of PL. Once I'm done I'm hoping you'll be able to do the following:

1. Build a template. For example, 03-templates/00-homepage.mustache.
2. Build a page that simply references the template using {{> templates-homepage }}. For example, 04-pages/00-homepage.mustache.
3. Build the base JSON for the page. For example, 04-pages/00-homepage.json.
4. Use JSON to define pseudo-patterns that build on the referenced pattern and referenced pattern's base JSON. For example, 04-pages/00-homepage~emergency.json. The ~ denotes that it's a pseudo-pattern. Whatever is before the tilde is the pattern and pattern JSON referenced in the same directory. Whatever is after the tilde is the text that will be added when the pseudo-pattern is built and is added to the nav. You'll be able to add ~00- to organize the pseudo-patterns after the main pattern in the nav.

I'm also hoping that we get a bit of a speed bump out of the refactor. I'm eliminating a fair bit of redundant code. Not that PL is slow right now but I get antsy about it. This feature should be implemented by the end of the week.