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.

[dmolsen]

@bradfrost -

And before you ask... Yes, after saying I didn't want to make a big change I'm making a really big change ;) Originally I was thinking I would be hacking existing functions. Now I'm straight-up eliminating them. Just saw too much redundant stuff. It'll make unit tests possible, the export feature should be easier to implement, and it should just be plain easier to add new features/plugins/extensions/whatever in the future.

[bradfrost]

I have nothing to say but GODSPEED. hahahaha I love the concept.

---

Brad Frost
http://bradfrostweb.com
http://twitter.com/brad_frost

On Mon, Dec 2, 2013 at 8:22 AM, Dave Olsen notifications@github.com wrote:

@bradfrost https://github.com/bradfrost -

And before you ask... Yes, after saying I didn't want to make a big change
I'm making a really big change ;) Originally I was thinking I would be
hacking existing functions. Now I'm straight-up eliminating them. Just saw
too much redundant stuff. It'll make unit tests possible, the export
feature should be easier to implement, and it should just be plain easier
to add new features/plugins/extensions/whatever in the future.

—

Reply to this email directly or view it on GitHubhttps://github.com//issues/31#issuecomment-29616904
.

[dmolsen]

@bradfrost -

This should now be working in dev branch. Lots of under-the-hood changes to get it going but all worth it I think. The use case I outlined above works so you can try it out.

[dmolsen]

@bmuenzenmeyer -

Used the pseudo-patterns as an opportunity to refactor. Lots of organizational changes in how the arrays are set-up. Dropped a few functions to focus on one, gatherPatternInfo, that pulls together nav, pattern paths, and pattern partial info. I'm going to try to document the changes tonight. I'll probably stick the info here for now.

[dmolsen]

@bmuenzenmeyer -

Ok, with the switch to gatherPatternInfo() and support for pseudo-patterns I've re-organized and expanded the default arrays of data. I didn't actually go so far as to remove those arrays but I think it's a little better organized.

navItems - I've renamed a lot of the keys so they better match what they're showing. For example, instead of buckets it's now patternTypes because, well, those are the pattern types. These changes matter because it's how the mustache templates know which variables to iterate over. I've posted a gist that shows the new keys and examples of their values.

patternPaths - Quite a bit of change here to address issue #73 and pseudo-patterns. patternSrcPath is the source pattern that will be rendered. patternDestPath is the place where the rendered pattern should be written to. This way a pseudo-pattern can reference one pattern but be written out in a different location. render is a flag because hidden patterns can be used in other patterns but shouldn't render in the viewall or style guide views. Seems like a weird place to put that data but it was just easier to pop it in here. I've posted a gist that shows the new keys and examples of their values.

patternPartials - I believe the only thing I changed here was changing patternPartialPath to patternPartial and patternPartial to patternPartialCode. This was just to be more consistent with how I refer to patternPartial.

data - With support for #74 I needed a place to stick pattern-specific listItems data. So now data has two attributes under a specific patterns data save. data["patternSpecific"]["atoms-colors"]["data"] would hold anything in atoms-colors.json and data["patternSpecific"]["atoms-colors"]["listitems"] would hold anything in atoms-colors.listitems.json.

I think that's all of the changes to the data models. I regret that I didn't do more granular commits but I was lazy and did the work over a really long period. Any questions just shoot. I'm going to work on more robust docs for the new features.

[bmuenzenmeyer]

@dmolsen Thanks for the thoughts, this will definitely come in handy as I devote more time to PL-Node (finally!).