Global assets (scripts, etc.)

[tylersticka]

It would be nice if there were a way to include stuff for the head and foot of the document without plopping them into a specific pattern.

For example, if I wanted a global <script> included for all patterns, it'd be sweet to have somewhere purposeful to put it, instead of in an arbitrary pattern, which feels fragile and a tad hack-ish.

Right now you can basically "hide" them in a pattern (footer.mustache), or create a pattern with some explanatory text ("this pattern is just for scripts, which is why you can't see anything but this paragraph here"). Probably not ideal.

[dmolsen]

I guess this could be done as a JSON config file. Sound ok? Better format?

[dmolsen]

@bradfrost -

since you're dealing with this too... what say you?

[dmolsen]

Oh, and you can make references to JS and CSS in source/_patternlab-files/pattern-header-footer/(footer|header).html. That gets added to the beginning and end of each pattern. Doesn't get added to the style guide or view all views but you might not need it too.

[tylersticka]

I do not consider myself an ace JavaScript developer by any means, but what if you had JavaScript that applied to more than one pattern?

If you added it to every footer|header, does that mean the <script> would get duplicated multiple times over?

So you'd probably want to preface it with var myObject = myObject || { /* blah */ };, which seems inelegant maybe?

I'm fine with JSON. I'd be fine with a more global header/footer include, too. I don't know the best way to execute... I think Pattern Lab's pretty awesome so far, so it feels presumptuous to impose my opinion regarding organization.

[bradfrost]

I think the right format might be as patterns. I'm thinking they would live at patterns/00-atoms/00-meta. Inside that folder would be 00-head.mustache and 01-foot.mustache.

head.mustache and foot.mustache would be included on every page: the view all page and the pattern detail page.

I like dealing with these in the patterns folder instead of in the patternlab-files folder. I like to think the patternlab-files folder is sort of like the Wordpress "core" files (sorry for the Wordpress reference, it's really my only perspective) in that it's a folder you probably shouldn't mess with unless you absolutely have to.

I also don't like the JSON route, just because I think it overcomplicates things. If I just want to include some scripts or stylesheets or whatever in the header and footer, I shouldn't have to deal with JSON configurations to do so. By treating them as patterns, people can edit all their stuff in the patterns folder without having to detour to other areas.

So what do you think? I started working on this, but @dmolsen, I might need a little help making sure everything is showing up in the right places in the templates.

[tylersticka]

I dig that idea. I can't think of any specific use cases other than including <script>s right now, but it feels like there could be, so it's probably best to (a) build upon an existing convention and (b) allow for a lot of freedom in how the function is used.

[bradfrost]

I dig that idea. I can't think of any specific use cases other than including scripts right now

I'm thinking including/excluding meta tags in the head (viewport, author, et al), stylesheets, Modernizr scripts, etc. In the foot it would be yeah probably mostly <script> tags.

[dmolsen]

But they're not patterns. You're now hard coding that "00-atoms" has to exist for this feature to work. That goes against the flexibility for renaming. They'd also show up in the nav and style guide as well as have their own view all page which seems odd. I don't think we want to start hard coding exceptions.

It sucks that it needs to be something outside patterns but it probably should be. It'd be easier to override on a "pattern" basis that way too. For example, "source/_patterns/03-templates/homepage-header.mustache" overrides "source/_meta/header.mustache". The previous was not a fully baked idea ;)

I agree on the "core" nature of patternlab-files. I was simply pointing out that right now it'd work.

Sent from my iPhone

On Nov 26, 2013, at 7:20 PM, Brad Frost notifications@github.com wrote:

I think the right format might be as patterns. I'm thinking they would live at patterns/00-atoms/00-meta. Inside that folder would be 00-head.mustache and 01-foot.mustache.

head.mustache and foot.mustache would be included on every page: the view all page and the pattern detail page.

I like dealing with these in the patterns folder instead of in the patternlab-files folder. I like to think the patternlab-files folder is sort of like the Wordpress "core" files (sorry for the Wordpress reference, it's really my only perspective) in that it's a folder you probably shouldn't mess with unless you absolutely have to.

I also don't like the JSON route, just because I think it overcomplicates things. If I just want to include some scripts or stylesheets or whatever in the header and footer, I shouldn't have to deal with JSON configurations to do so. By treating them as patterns, people can edit all their stuff in the patterns folder without having to detour to other areas.

So what do you think? I started working on this, but @dmolsen, I might need a little help making sure everything is showing up in the right places in the templates.

—
Reply to this email directly or view it on GitHub.

[tylersticka]

@dmolsen I see your point, that is probably a presumptuous example.

Maybe part of the difficulty I have in wrapping my head around a particular implementation is that the use case doesn't necessarily map to a pre-existing convention of the tool. It's mostly like a pattern, except it isn't presented in any overt way and it occurs regardless of which pattern(s) is/are being viewed. It's kind of like _data except it would be weird if things were "overridden" in the sense that they are with data.

My expectation when I first started working with Pattern Lab was that every file included in source/js would be included by default. I assumed this because that's how source/css works, and I couldn't think of a case (for my project) where I'd want a script file included outside the global context. I know that doesn't solve the head/foot issue, but how important is that to define for this stage of development? Could you establish a file or directory naming convention for that to happen automatically?

(Just some food for thought. 🍔 )

[dmolsen]

@tylersticka -

I apologize. I'm not sure if it was obvious but my last comment was targeted at @bradfrost's suggestion. FWIW, source/css/ suffers the same issue as source/js/. Neither is included dynamically. Sass might hide that issue some.

@tylersticka & @bradfrost -

I'm feel like there are two issues to balance:

1. PL has taken a "you get to set this project up almost anyway you want" stance.
2. Source order for the included global assets is critical so how is that defined.

These are the current global header and footer files that get appended to pattern detail pages. They mimic Brad's original view file.

Including global assets seems to come down to finding a way to tack data into the header and footer so that's what I've focused on.

The Options in Detail

I think there are four options for including that info into a global header & footer found in core/:

1. In config/config.ini particular patterns are identified to be included in the header and footer for patterns. PL takes a stance that, by default, those patterns are 00-atoms/00-meta/_header.mustache and 00-atoms/00-meta/_footer.mustache. The underscores ensure that 00-meta and those patterns won't show up in the nav. I'm not sure what the easiest way will be to override this particular feature on a template/page basis. This gets closer to dealing with these directly as patterns and allows a lot of flexibility when authoring.
2. Once _patternlab-files is moved out of source/ and renamed core/ we can introduce a new directory into source/ called _meta/ where a header.mustache and footer.mustache file are stored. These can be overwritten by pattern-specific files. For example, 03-templates/homepage-header.mustache. This way source order is defined in HTML and there's a lot of flexibility for what can actually go in each outside of just assets. These files would be included in the overall header and footer for PL files.
3. PL ends up taking a stance on directory structure and says js/ and css/ are defaults that will be scanned for files to include. The default directories could be overwritten in config/config.ini. The files need to be numbered in the same way patterns are so that source order is defined. For example: js/01-jquery.js, js/02-slideshow-plugin.js, js/03-fun-thing.js. Same with CSS. I personally don't like adding the numbers because I think it would be odd when handing off to a production team but source order has to be defined somehow. Everything would get included with each pattern but it fits the style we already have for managing patterns. This wouldn't handle files that people wanted to load via CDN.
4. A JSON config file is used somewhere to define dependencies. It'd be similar to the dependencies section of NPM's package.json. My choice would be source/dependencies.json. I know it's ugly but I'm not sure how often it'd have to be modified. This could be expanded/overwritten via pattern-specific dependencies JSON files. It'd also give a quick look at what dependencies might exist for a project/pattern. It's indirect and may be a "programmer's solution." I'd also have to explore what other "dependencies" might exist. For example, meta tags that Brad brought up.

TL;DR

I'm sure I'm overlooking use cases or issues. I'm not promising I can definitely get a chosen solution working but at least this is a starting point. Brad, if you have something already working we can go with that.

So summing up:

• Point 1, centralized header/footer mustache templates within _patterns, gives flexibility to an author but is fragile from a naming convention standpoint.
• Point 2, centralized header/footer mustache templates outside _patterns, would be one of the two that are the easiest to implement. Might be too indirect and feel like editing "core." Lots of flexibility for an author.
• Point 3, setting default directories and using numbering to determine source order, would be the other "should be easy to implement" solutions. Auto-magical like most of PL but couldn't use a CDN easily (at all?) with it and takes a stance on how someone needs to set up their project. No code to write. Drop a file in, name (if source order is important), and go.
• Point 4, a dependencies.json file, is my favorite and could follow an existing pattern. Less code to write for an author and quick-glance list of global assets being used but stuck with JSON. Maybe not flexible in the long-term.

[tylersticka]

I apologize. I'm not sure if it was obvious but my last comment was targeted at @bradfrost's suggestion. FWIW, source/css/ suffers the same issue as source/js/. Neither is included dynamically. Sass might hide that issue some.

@dmolsen But an exception is made for style.css, correct? So I guess an equivalent solution for JS would be if nothing was included by default from the js directory except for script.js (not a suggestion, just a clarification that I understand).

Any of the proposed solutions would solve the issue as I encountered it in the project I'm working on. The only one that probably feels the least immediately intuitive (which I know is a tad ironic as it seems partially based off my mistaken assumption about how the css directory works) is Point 3. It sounds nice at first until I start thinking about including dependencies and not just my own scripts... it feels a little too opinionated, perhaps?

Thanks for giving this issue so much thought. Warms my heart! 😃

[dmolsen]

@tylersticka -

Yeah, you got it. :)

For now it looks like we're going with point 1. That's the solution Brad originally laid out. Not a huge fan but it's now working in the dev branch.

I'll leave this issue open for a little bit just in case Brad changes his mind.

[dmolsen]

Doesn't seem like Brad changed his mind so sticking with what we have and closing this issue.