[edit 20131102:] The upgrade to D7 has this new 'feature' where anyone is free to edit the first post of a topic.
The edit is documented in sequence and a revision history is available.

But these weren't the terms under which I wrote and submitted this issue and I consider the changes, given no consent, to be damaging. Particularly given it's my username still attached to this first post.

I'm all for wikis, but again, not in the context of changing terms.

No one asked. And I would not have given consent.

Comments

brst t’s picture

Issue summary: View changes

adding the [] around the issue link

brst t’s picture

Issue summary: View changes

adding references

brst t’s picture

Title: Sass and SMACSS - how are you structuring your files ? Examples and discussion. » How do you structure your Sass?

20131102 - removed by author

dddbbb’s picture

I'm starting here: While SMACSS structure is very easy to grasp conceptually, I find it more than a little difficult in practice.

Agreed but don't let that put you off trying. Where SMACSS really shines is when your codebase starts getting big and when you want to start re-using lumps of it elsewhere.

I like to break things down to the point where I have at least one partial for overriding the markup produced by a particular contrib module, e.g. field_group (shakes fist at the sky): one partial for the overrides that I'll do no matter what project I'm working on (common partial) and another partial for the overrides that are project specific, such as bespoke aesthetic styling decisions etc (project partial). Then, when you're on a new project, you can just grab all the relevant common partials from a previous project and Bob's your live-in lover - you've just saved yourself a ton of time.

dddbbb’s picture

That said, I suppose that the suggestion of breaking the structure down into granular partials is not actually an aspect of SMACSS directly. Doesn't SMACSS predate Sass? I've read the book but can't remember.

Anyways, you know what I'm getting at...

brst t’s picture

20131102 - removed by author

brst t’s picture

Title: How do you structure your Sass? » Sass and SMACSS - how are you structuring your files ? Examples and discussion.

Renaming the topic to reflect the issue pertains to a mix of Sass and SMACSS.

Context of CSS coding standards and CSS file organization in particular.

dddbbb’s picture

Take forms for example - and please correct me if and where I'm wrong. In ohm, there's a partial _forms.scss in /base that aggregates a folder of partials in the descendent, /forms.

And in components there's anther folder full of partials. And it's aggregated through _components.scss in the level above.

All well and good - sort of, but not really.

According to SMACCS:

Base rules are the defaults. They are almost exclusively single element selectors but it could include attribute selectors, pseudo-class selectors, child selectors or sibling selectors. Essentially, a base style says that wherever this element is on the page, it should look like this.

and

[Components] are the reusable, modular parts of our design. They are the callouts, the sidebar sections, the product lists and so on.

(the word "Modules" replaced with "Components" above of course)

So yes, Ohm's structure may be a little over the top as per the example you've given. But both Ohm and SMACCS are supposed to be guides rather than rigid frameworks as I understand them. You mention that you understand it to be malleable in parts - that's exactly the right approach I think; once you've understood it, take as much inspiration from it as possible and run with it, killing off bits as required and adding bits as the need arises.

I'm taking the "common / project" model I mentioned earlier to quite a serious degree now and it's raising all sorts of interesting questions around the established model of parent / sub theme and how one might better structure things with re-usability in mind. I'm finding that I'm doing a lot of killing bits and adding adding bits as mentioned above.

dddbbb’s picture

Issue summary: View changes

Fleshing out the where is, where do I, what do I name it.

brst t’s picture

Title: How do you structure your Sass? » Sass and SMACSS - how are you structuring your files ? Examples and discussion.

20131102 - removed by author

fubhy’s picture

Priority: Minor » Normal

Thanks for opening this issue. Very good discussion and ideas so far. I'd like to add handbook pages for theme project management / structure / naming / ideology which this seems like a good foundation for. Can I invite you guys to join the documentation sprint tomorrow? Are you already on the mailing list of @cellar-door?

We can also discuss how to improve / extend Ohm (yes, Ohm is not anywhere near finished yet. We still have to cover so many things in it, remember though that it's particularly hard in Ohm as we want to keep it diverse and make it show different approaches and practices while also not becoming confusing).

So, would you like to join us tomorrow? I was planning to do a Google Hangout simultaneously with everyone interested so we can be even more productive and easily discuss some things.

brst t’s picture

Sure.
Messages sent.

dddbbb’s picture

And if base/ is to be a 'set and forget' for a project, how come normalize isn't in found in there?

Because base is intended as a "set & forget" foundation but it's still specific to your project (e.g. all input fields will have a brown border). Normalize is intended to be a fair bit broader (e.g. force browsers to adhere to similar defaults etc). Different things in my mind and again brings us back to the concept of "per project" and "common to all projects" - getting this bit right is the key I reckon, and is also where the secret treasure of Sass partials is buried. Aaaarrrrr!!

@fubhy - Thanks for the invite, I'd love to get involved. How does one go about getting on @cellar-door's mailing list?

dddbbb’s picture

Have emailed @cellar-door via his D.O profile. That enough?

Cellar Door’s picture

Yup! Added both of you on the list and we'll see you tomorrow in the hangout!

brst t’s picture

20131102 - removed by author

dddbbb’s picture

Sure, the variables would be set in utility/variables as you've described (e.g. that nasty brown colour that we've decided to use for input field borders) but the point at which it's referenced in the context of setting up the project defaults for forms would be stored in base/forms/etc (e.g. the input element selector where we assign that colour to the border property). A subtle abstraction you might say but one that's worth it when you consider how pluggable this makes the entire Sass structure.

Simplifying the structure seems tempting when you're only focussing on the scope of a single project. As soon as you step back and consider the potential for re-use between multiple projects (even unrelated), the investment in a more complex structure suddenly seems worth it. This is certainly what I've found and I've done a few Sass based themes now.

I've reached a point now where I believe that there's a lot to be gained from making the structure even more complex & granular, if re-usability is of interest (it certainly is to me). I recognise that this may not be the best thing for Omega 4 as a project though, as enough people seem to be struggling with the suggested Sass structures as they are (that's not to say the suggested structures are "correct" though - I get that this is all still being figured out).

brst t’s picture

20131102 - removed by author

brst t’s picture

Aside on an aside. Still looking front and forward.

More components to think about: Web Components: A Tectonic Shift for Web Development - Google I/O, May 2013. http://www.youtube.com/watch?v=fqULJBBEVQE

dddbbb’s picture

Personally, I like to open up the /abstractions directory and only find you know, abstracted stuff: mixins, utilities etc - stuff that doesn't actually do anything unless you invoke it.

Do whatever suits you best. As previously mentioned, they're just guides.

brst t’s picture

20131102 - removed by author

fubhy’s picture

I'd like this whole discussion to become a dedicated topic in our handbooks. Would you two like to write that?

dddbbb’s picture

My word, that sounds complicated :D

Can you elaborate any further on what you're after?

brst t’s picture

20131102 - removed by author

Cellar Door’s picture

I would recommend that this go into a "best practices" subcategory apart from and after the main 3 steps (before you theme, creating your subtheme and customizing). Though it's good knowledge to have I'm not sure I want to scare people off with so many options and ways to do things.

What do you guys think about a new section for best practices after customizing your subtheme and before advanced techniques. That way we can get someone quickly though the creation process and then get them thinking about the best practices which will lead them to the more advanced side of Omega 4.x?

Just trying to keep a simple easy flow to the intro docs...

brst t’s picture

20131102 - removed by author

Cellar Door’s picture

I think the idea behind the "customizing your theme" section is going to be mainly around where to find things, where to put your code to make it work, and a basic explanation of layouts. The first section in that is a brief overview of the SASS/CSS structure of the default/extended starterkits. I think it'd be great to put a link in there that would say "We have a set of best practices around how to organize your file structure. If you are unsure on what structure you are going to use in your theme [click here] and read more."

That way they're still in the setup docs but aren't going to overwhelm people. Let's be honest most people cruise right through the docs and won't read it all. If we give them enough to go and make mistakes or get hung up on things they'll come back and look at the best practices. We've all been there, get in get dirty then learn how to do it the right way. The setup guide should be a get in get dirty instructional that then leaves them wanting to get deeper in the best practices and techniques we recommend.

brst t’s picture

20131102 - removed by author

dddbbb’s picture

After sitting in on last night's docs sprint and seeing how it's taking shape, I certainly think that this topic is one for either the advanced "rabbit hole" section (given how subjective and conceptual the topic seems to get, and how quickly it gets there) or as @Cellar Door suggests, a new "best practices" section (though I'm wary of that scaring off new users too early). My vote is for rabbit hole, for the sake of new user sanity, not to mention the uproar in the issue queue that would surely follow if this was dumped in "customizing your Subtheme".

As @burst t suggested, a decent explanation of Ohm's structure and why it's the way it is would be a great addition too, though this may be better off divided into a 2 pronged attack:

  1. A simple-ish version mainly to orientate new users, perhaps as an extra item at the end of the steps under "Customizing Your Subtheme". @Courtney.B's chart could come in handy here as @burst t already mentioned.
  2. A more detailed run through the structure, mainly to explain why it's structured that way, rather than simply sign posting what's already there in code.
brst t’s picture

20131102 - removed by author

Cellar Door’s picture

@brst t - I thought I had included you in the email, sorry if it did not reach you. During our conversation last night we put the label "rabbit hole" on anything that was above just getting setup in the theme. It's not a derogatory term and there will actually be a lot of documentation in that area but the idea behind it was that lengthy and more in depth topics that could overwhelm someone on their first time thought would be put into that section of the docs. It'll be where the discussion around how to properly setup a local development environment will live as well. Though incredibly helpful, the level of depth in them can scare some away from even trying to use theme in the first place.

I think documenting the best practices and why we recommend them is a VERY worthwhile and valuable addition to the documentation. The hope is to create a doc environment that can foster someone from first subtheme to creating their own ohm-like theme. This will take multiple levels of documentation.

So the term rabbit hole isn't where docs go to die, it's where we can nerd out on a little higher level but do so in a way that won't scare off people. Let's admit it though - Omega 4 is a rabbit hole of it's own in that you can start of very surface level but it can and does get deep quickly. This is the exact reason we're working to create the docs.

I'll make sure to include your email again in the next doc sprint. Another way to find out about them is in the IRC channel.

brst t’s picture

20131102 - removed by author

dddbbb’s picture

@brst t, sorry I kept getting your handle wrong. I typed that last comment earlier this evening after a pretty manic week. Must've just been typing phonetically or something crap. Didn't do anything on purpose or mean to offend.

Also, as hopefully you now realise, I wasn't trying to devalue this topic in any way by using the term "rabbit hole". As I'm sure you now gather, it's just a term that was being used to help divvy up "beginner" and "not beginner" subject matter in the docs sprint. Sorry, I wasn't sure if you were present at the sprint or not as it's often tricky to attribute real names to handles and so on - I saw that you were invited a couple comments up.

Regarding the "rabbit hole" term specifically, I don't think it's so bad, especially if it's safely confined to the advanced end of the docs. A lot of the contemporary techniques involved in a modern, Sass based theme such as Omega 4 are still being explored: partial structures, globbing, preferred Ruby environment & Gem management systems, pros & cons of various grid systems and mixin libraries - it's all still up for grabs really. I like how the term conveys some of that uncertainty & subjectivity and at the same time makes light of it, making it a tiny bit more approachable. It sign-posts an area of the advanced docs with a reminder that things are gonna get a bit weird from here on in, but that's OK - it's supposed to be. Could've done with a similar sign at the top of this post! (joke - don't freak)

fubhy’s picture

I understood RVM and I still have little understanding as to what extensions are in the context of Omega4.

Don't worry too much about extensions. They are just a way of grouping configuration in different tabs with the option to disable them all at once. It's really just grouping of configuration...

'Rabbit hole' is just terrible for documentation. A rabbit hole is a metaphor from Alice in Wonderland and it serves to suggest the documentation is absolute crap more than it does nerdy. You fall into some hole that you didn't see and have no idea where it leads and it's full of fantasy and other unfathomable stuff.

Cardiology isn't through-the-looking-glass rabbit hole stuff just because I'm not an MD.

Hmm, maybe you are right. Do you have a better suggestion for a term for this? I certainly don't think we should 'hide' documentation like this. It's certainly not 'advanced' in the common sense. It's just not 'the first step' when you start with Omega... it's not really 'optional' if you know what I mean. Understanding Sass, SMACCS, OOCSS, BEM, etc. is something I consider absolutely required at this point. And I don't see all of these concepts as carved in stone but rather as a stepping stone for people to get a sense for organizing and managing their front-end projects. It's required to communicate the necessity of well-structured stylesheets and build up a sense for how to do this conceptually instead of indoctrinating a pre-built setup. It's also a matter of taste really... And yes, RVM, while it may look scary at a first glance (for someone who never used it before) it's absolutely NOT advanced. It's really fairly simple once you understand why you are using it and why it is so important and awesome. Same with well organized stylesheets. At a first glance it might look overly complex and you are lost in your Sass file hierarchy. However, once you get the underlying point, it's so much simpler than the traditional way of using plain, unorganized CSS. It's all about planting the seed for understanding these concepts in peoples heads - That's very important.

So, bottom-line: Yes, we do need a absolutely beginner tutorial for how to set up plain Omega and how to create starterkits and what not, but this part of the documentation is VERY important too and deserves a top-level spot somewhere. Just like the dev-stack does.

So yes, a 'rabbit-hole' with a hidden sub-tree is maybe the wrong thing to do.

Any suggestions?

fubhy’s picture

Priority: Normal » Major

Bumping to major. This is very essential.

C13L0’s picture

Instead of "Rabbit Hole", what about "Best Practice". Using smaccs, bem, basic structure, and etc is essential and there should be some consistency throughout the Omega community. As a newbie to drupal, I would like an Omega best practice guide with the understanding it can be tailored to fit my project.

edit: Somewhat more generic could be "Practical Guide"

brst t’s picture

20131102 - removed by author

Cellar Door’s picture

I think we're getting caught up on the semantics of "rabbit hole" while there are some great points being made. We used rabbit hole as more of an affectionate term to the way these conversations go. Since it's not a very clear cut and more of our recommendations (these are constantly evolving topics) I think putting them front and center may overwhelm the first time person coming into the theme. We had someone on the last hangout that agreed with this that they would be overwhelmed with talk of SMACSS etc..

So even if it's not the "best" route, getting someone into the theme, get them creating a subtheme, and maybe they put all their Sass into a single style.scss file would get them started. That's why I would consider this an optional topic. Creating a subtheme, creating layouts etc. are not optional as they're required for the theme to function.

I'll take a look at the proposed structure and leave comments from there but I'm a big fan of 3 step processes for beginners. Makes it easy to get your mind around. Then once they're done with the 3 steps we then teach them how we recommend to continue using it (but with the knowledge that it's optional) then after that we have the "rabbit hole" of bleeding edge experimental and extremely techincal stuff. I think most of all we keep the pages bite size. A few paragraphs and images then on to the next step. One of the things I think that make Omega 3.x popular was it's accessibility to all levels of themers. With 4.x we've definitely catered to the advanced users and these docs are our opportunity to make sure we keep the bar to entry as low as possible.

I do have to say I love seeing all the effort and concern over documents! It's one thing that's normally overlooked in projects. This is what makes Omega great!

brst t’s picture

20131102 - removed by author

brst t’s picture

20131102 - removed by author

dddbbb’s picture

I'm liking "presentational" & "functional" in this context, much clearer indeed. Good find.

bennybobw’s picture

Hi Everyone,
Thanks for this discussion and all your work on this. I'm new to Omega, sass, and SMACSS and am trying to wrap my head around it all. It's starting to make a little more sense.

I'm using the extended subtheme, and one thing I'm having trouble with is where to override styles for specific views or nodes. I think what I'm going to do is to add a stylesheet called _overrides? Or is that kind of thing supposed to go in _hacks. Most themes I develop have some overrides, so I think it would be good to document a best practice for this kind of thing and/or some examples.

fubhy’s picture

Well, those are simply components. Just specific ones.

Percept’s picture

This is a very interesting topic ... I haven't read all the replies here in detail yet, but while reading I realised this is a really hard topic to discuss without actual real-life examples.

So ... would it be an option to select a website design, setup the site structurally with all the needed elements (regions, blocks, views, ...) and then let people download the code + db + files and code a Omega 4 sub-theme according to what they see as best practices.

Something like a CSS Zengarden but instead of making the site look different, they should all look (exactly) the same.
This way we can compare and discuss actual SASS code/structure.

It doesn't have to be very complex ... front-page and basic page layout. Some different type blocks like newsletter subscription, main-navigation, latest news, a view of article teasers, ...

brst t’s picture

20131102 - removed by author

Percept’s picture

brst t, I'm not quite sure what you mean exactly with

No Sass in Bartik, which would be my first choice for familiarity, so how about making use of Ohm ? It's both practical and relevant, here.

sub-theme Ohm?

brst t’s picture

20131102 - removed by author

Percept’s picture

I want to make one but I'm not quite sure sub-theming Ohm is the best approach for "educational" purposes?
Why not sub-theme Omega directly?

brst t’s picture

20131102 - removed by author

fubhy’s picture

Okay.. wait.. Let's hold on to that thought for a minute. What about adding a playground starterkit to Omega? Basically just as Ohm but not as a static reference/documentation source but also for simply playing around with it?

brst t’s picture

20131102 - removed by author

brst t’s picture

20131102 - removed by author

fubhy’s picture

Yeah.. That is essentially what we do. Except ours is still a bit cleaner IMHO.

brst t’s picture

20131102 - removed by author

fubhy’s picture

Hm... Not sure. I find our's equally intuitive (if not more). I guess that's a matter of taste. I find Ohm very well organized and structured.

C13L0’s picture

(open/close/open/close/open/close...!$*^ grep) .

My sentiments exactly.

fubhy’s picture

I am absolutely open to removing the partials folder for example. As in... Have 'base', 'components', etc. directly in the "sass" folder. Same with the Utility folder maybe. We can think about inflating that.

brst t’s picture

20131102 - removed by author

fubhy’s picture

/layouts can't go into /components. They are separate top level Sass files.

fubhy’s picture

brst t’s picture

20131102 - removed by author

brst t’s picture

Status: Active » Fixed

20131102 - removed by author

fubhy’s picture

I hope we can fix layouts and move them to subfolders in some way. Not sure I can fix that in compass myself... I am not that good with Ruby. Will try to provide a pull request for the github repo though. We'll see ;)

brst t’s picture

20131102 - removed by author

dddbbb’s picture

Top work. I like it.

brst t’s picture

20131102 - removed by author

fubhy’s picture

Yes, agreed with both your points. I already opened an issue to fix some other related stuff in Ohm Hero and make it live up to those expectations. #2089589: The Ohm Hero layout should probably not have background colors/styling.

Also, removing grid variables is a good point as they make no sense there anyways. Even if you were to use Susy it would not make much sense to define them globally like that because that's simply not how you would use them anyways. Same with the breakpoints... Layouts can be 100% separate if you ask me (meaning that we don't leak any global variables into them) as they don't get any styling anyways (layouts should be pure architectural CSS) and the grid definitions/breakpoints are absolutely up to itself too.

So... Yes, agreed. We will fix that in the issue I linked.

I can't now, however, as I am in the middle of the last couple of hours before my final exam of this year @ university. Gotta stick my head into the books again. Will do this in the evening tomorrow though unless I end up completely drunk ;).

brst t’s picture

20131102 - removed by author

Percept’s picture

I didn't have time to follow up on my zengarden suggestion until now ... I just downloaded Omega 7.4 and I see the file-structure has totally changed and Susy was replaced by Singularity. I just tried a couple of hours to create a Susy based sub-theme from the Omega default starterkit and it's not really working.

I know you guys put a lot of work into this but it really isn't getting any more clear structure-wise.

fubhy’s picture

Susy was not replaced by singularity. Susy is still in the config.rb and Gemfile. We just chose to use Singularity for most of the contained example layouts.

The Sass structure we now have in the starterkits has been created after we found consensus about a neat and simple structure in this very issue and has been implemented over at #2089383: Further improve and simplify Ohm's Sass structure..

The new Sass structure has a much simpler and less deeply nested hierarchty which should make it much simpler for newcomers to grasp the concept as a whole. It also makes extensive use of sass-globbing which enables us to vastly simplify the partial import chain.

Please be a bit more specific about what exactly you find troubling with the new structure. Where did you run into problems?

brst t’s picture

20131102 - removed by author

Percept’s picture

I've read and checked some screencasts about singularitygs and will be using it for my next site along with breakpoint.

Fubhy, one of the main things I don't like about the new structure is the importing of stuff through globbing. I understand it makes it a lot less cumbersome to add files but it reduces the otherwise self-explanatory structure significantly.

The other issue I have is not really a direct Omega issue but more personal. I have some basic Sass/Compass knowledge, using variables, mixins ... but the list of "default" plugins you need to know gets larger and it's hard keeping of if you are not already a Sass/Compass/all plugins pro. Toolkit, singularitygs, susy, compass, breakpoint, ... I'll just have to up my Sass game to use Omega :)

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.

Anonymous’s picture

Issue summary: View changes
brst t’s picture

Issue summary: View changes
brst t’s picture

Issue summary: View changes