Rewrite the Omega documentation for Omega 3.x - A discussion about the topics that we should cover.

+
using context with Omega
upgrading from O2 -> O3

+1 on docs for updating Omega 2.x to Omega 3.x...

I have "mostly" completed 1 upgrade (not live) and have 3 to actually do including updating the Beta & Gamma sub-themes, so I will spearhead that portion for sure...

For those of us just dipping our toe into responsive layout, a discussion of how not to break it while customizing your theme would probably be helpful.

Would it be appropriate to include a topic on accessibility and, again, how not to break the accessibility the theme starts with?

Under

What is responsive design and wtf are "mobile-first layouts"?

, it would be wonderful to have two or three illustrations (say, non-functional Photoshop mockups) to grasp the concept of changing from the mobile to narrow, normal, and wide grids.

... overall strategies for how images (responsive images), sidebar text, and, especially, menus (responsive menus) might change responsively.

Any of the recent issues requesting "best practice" help in the issues queue.

+ What's New in Omega 3 List linked to relevant sections of the docs (including):
- Where all the settings in Omega 2 went and why many were made unavailable in Omega 3
- Which leads to, the distinction between what should be done in themes and what should be accomplished with modules

+Why is Core CSS being disabled by default in Omega?

+ best practice for updating custom sub-themes with version releases

+ Perhaps a brief Developers Release Note to provide a recommendation whether to update the sub-theme or not

So I took all of the above suggestions and tried to put them all together in a frame for the documentation. All open for discussion ofc.

Omega 3.x documentation

Introduction

• What is a Drupal base theme?
• "Why choose Omega?" Or "Do I need Omega?"
• Compare Omega and other commonly used base themes.
• What is the 960 grid system?
• Containers and Grids
• Prefix and Suffix Classes
• Push and Pull Classes
• 960 Grid Resources
• How the grid works.
• How to create my own custom grid.
• What is responsive design and wtf are "mobile-first layouts"? Responsive images?
• References to all the great responsive design discussions and tutorials on how to build a great scalable experience for all users from mobile to desktop.
• two or three illustrations (say, non-functional Photoshop mockups) to grasp the concept of changing from the mobile to narrow, normal, and wide grids.
• overall strategies for how images (responsive images), sidebar text, and, especially, menus (responsive menus) might change responsively.
• Formalize - Why do I need it?
• upgrading from O2 -> O3

The Omega 3 theme

• What's New in Omega 3 List linked to relevant sections of the docs (including):
• Where all the settings in Omega 2 went and why many were made unavailable in Omega 3
• The distinction between what should be done in themes and what should be accomplished with modules
• Why is Core CSS being disabled by default in Omega
• The difference between Omega and Alpha.
• Delta
• Tutorial on how to use Delta.
• using context with Omega
• Omega Tools
• Omega UI
• Tutorial on how to use Omega Tools (when it's done).
• Regions and Zones
• The concept of the CSS files in your starterkits and how they override each other.
• The .info file
• How to use the css[] array.
• How to use the libraries[] array.
• How to use the regions[] and zones[] arrays.
• How to use the grids[] array (backreference for generating custom grids

Omega subthemes

• Why Creating a Subtheme is Important
• Contributed Omega Subthemes
• Creating Omega Subthemes (How to create a subtheme with the starterkits)
• Using your Subtheme
• Beta
• Gamma
• Libra (?)
• HTML5 or XHTML? What is the difference and which starterkit should I use?
• How to override base theme stylesheets (like omega-menu.css, omega-branding.css, etc.) in your subtheme.

Advanced stuff

• The Omega debugging features & how to use them.
• How to make use of the preprocess and process functionality in Omega.
• How to modify and preprocess your templates in Omega.
• How to build your website without using Drupal core variables like $site_name, $site_slogan, $main_menu, etc. (How to use Blocks instead) and why blocks are better than those variables.
• How the advanced Omega CSS Aggregation works (for advanced users)
• How to write media queries.
• Drush
• The Omega tools wizard (not ready yet)
• Manually (? dunno what you mean here)
• best practice for updating custom sub-themes with version releases
• how not to break the responsive layout while customizing your theme
• accessibility and, how not to break the accessibility the theme starts with

Frequently Asked Questions

Some of the suff in the above could well be placed in a FAQ

I would just ask to make sure basic CSS styling is still covered well. I see only one or two items in #19 that pertain to customizing the styling CSS. The positioning, grid, and dynamic aspects of Omega are fantastic, but you will still have beginning users who need elementary examples.

I just started theming last week, originally using Genesis, which was very easy and intuitive to customize. I am thinking of switching to Omega, but am scratching my head a bit about the CSS file naming, the CSS settings, etc.

Some simple examples you might cover in the doc:
1. Add background image to header.
2. Change background color of whole page, content, sidebar, etc.
3. Change text styling and padding in various places.

I'm working on a beginner's guide that will cover basic getting started topics like this. I'll post back when it is ready.

This theme is pretty easy to add background images to, once you figure out the naming conventions of the regions and containers.

1. You may want to set a wrapper in the theme settings for whatever section you want to add a background image to.
2. #page {background-color: blue;} doesn't work?
3. Have you tried Firebug? You can identify CSS elements with it and then change them right in your browser to see what the results would be.

#21: A beginner's guide sounds great! Thanks for your specific answers. I was not actually saying I did not know how to do those things, but instead that they are good examples of what a rank beginner would want to do, and so would be good to include in the documentation. The answers you gave reflect knowledge of which settings are in which CSS files, which CSS files to create and where, what the ids and classes are to change, etc. That is exactly what should go in a beginner's guide. I was just remembering things that I didn't know when I first started theming.

+ Tutorial

• From Photoshop mock-up to an all styled and functional Omega 3.x theme Using the Omega Starter Kit as a starting point.

Ok, I didn't pick up the rhetorical aspect. Maybe a beginner guide with a subtheme.css with the regions noted to change? I thought about a css override file that could be cloned with bold colors to easily pick out each section.

well omega 3 is great !!! better v.2.
i will be happy if there will be section in doc all about theming for the newbie . (i am newbie)

i am subscribing this sound great !!!

@himerus keep the hard work you are the best !!!

+ Omega 3 CSS Maze Explained:
- What CSS is added by the Alpha layer
- What CSS is added by The Omega layer
- How is Core/Modules Generated CSS is being affected
- How is the CSS tree organized and what is overriding or extending what in the cascade
- How to control CSS groups and weights to control the overrides

@witchcraft BTW fubhy also deserves a lot of credit he is the maintainer of the Omega 3.x branch :)

This might not be an issue pertaining to this particular thread, but I wanted to clear it up while I was working on the beginner guide. When creating a subtheme, I am assuming that the subtheme name should not contain any dashes (-) I found if I used dashes, the theme isn't recognized. Is this Drupal or Omega specific? I seem to have encountered this once before but I think it was using a different theme.

sub :)

Thanks for clearing this up, and thanks for your hard work on the 3.x branch. Super-awesome stuff. The responsive web features are great.

@fubhy i didn't know you are maintainer on this project thank you so much !!!!
this really great work guys and keep that way of spirit

So..... What would be a good place to coordinate documentation efforts? So we can avoid duplicating things, and work together getting the documentation as cool as Omega itself? :P

The layout of the Documentation section is being built out now using this issue thread as a guide as well as considering other factors, once the layout is completed and fubhy and himerus approve of it we will expose the link and a docsprint will be announced, i expect this to happen in few days, so we appreciate that you guys would start getting some docs snippets ready on your local computers as well as think of what you will be going to put in there if you are willing to contribute to getting this done ASAP :)

Cheers.

I'm working on the beginner guide right now. The guide is geared toward an absolute beginner and covers creating a base theme from the starter theme kit and creating a subtheme.css file and then identifying the #regions and #containers that cover the major sections of the theme.

I will include images as well and I think a subtheme.css with #user-container {background-color: blue} etc. for a starting point to easily identify the regions and containers that can be changed quickly.

I also will describe getting the theme settings and then adding them to the .info settings to make the changes persistent and portable.

@bhosmer i have sent you an email via the contact form please check it out.

@WebGear: How can we "start getting some docs snippets ready on your local computers" if there is no direction of who will be doing what?

@bhosmer: What will your beginner guide cover?

The beginner section will cover getting omega, creating a subtheme, creating a subtheme.css and then the containers and region names within that css file. Also, using the code export feature and adding it to your .info and then using the omega interface to disable and enable containers and regions. Does anyone have any input as to what should or should not be included in the beginner section?

The structure that is being constructed is based on the following general guideline layout:

1- Theory and Overview of the technologies involved in Omega 3.x
2- Beginners stuff: creating subthemes and general settings
3- Topics of medium complexity for the average but not newbie user
4- Really geeky, advanced and technically deep theming topics, like using the process, preprocess, CSS overrides trees, not using Drupal core variables... etc.

And maybe some walk-through tutorials somewhere around these lines if anyone is interested to contribute any.

That is the overall skeleton, if you would like to participate in the Docs at this stage and help with the final layout please let me know here or by email

Thanks.

This is getting BIG.

@fubhy
First of all, tnx for your work on Omega. I see on IRC that you are making some hours :)

@webgear
I would love to participate. I'm just starting with Omega 3 so "advanced stuff" will not be my thing. Yes it will be my thing to use it.
How will you work to prevent that things will be done double ?
Tell me what I could do ?

Perhaps it's good to know that a wikipage with documentation has been created at: Omega Theme 3.x Help Documentation.

No idea why it hasn't been mentioned before.

I think it wasn't mentioned yet because it was still being created and under construction. @webgear had mentioned a doc sprint coming up soon.

Isn't a wiki a community effort?

subscribe

subscribe

subscribe

sub

Please add

DO NOT use spaces or dashes (-) in your subtheme name, or your subtheme will NOT be recognized.

like at http://groups.drupal.org/node/155974 to the

README.txt

file. I'm using zen and other drupal themes and that dash, space and underscore thing cost me 1 hour!

Don't use accents too, e.g : in [description] in optional style sheets, you will only see the checkbox to activate/desactivate your custom css.

@jepSter: Would you be able to clarify where an Omega subtheme with spaces and/or dashes will not be recognized as opposed to one in Zen or those other themes? Do you mean it won't appear in Appearance > List > Enabled Themes / Disabled Themes?

None of my Omega subthemes has ever not contained spaces and hyphens, plus the base theme itself is "Omega - Responsive HTML5 Base Theme" . . . which makes me wonder where the caution applies.

Could it be possible having just some hints on how upgrading from 2.x to 3.x, i know that you're already covering this so just if you have some "line guide" (have to convert 2 small sites)
obiouvlsy only if you have 5 free minutes, thank you so much for the great work.

You're right--I should have stated that more specifically in my comment. I meant that the input will become machine readable, making it no big deal, when you let Omega create your subtheme.

Re: #19 "How to modify and preprocess your templates in Omega."

A simple example /checklist of the files to add (rather than modify) would be a great start.

There are comments in my subtheme's generated template.php file which suggests a clean way for me to alter template functionality

For example I want to add funtion MYTHEME_form_alter() for me to modify the html generated for my search form. The comments suggest that I don't need to copy the base theme's template.php file into my sub theme (nice! hooray!) but left me a bit baffled as to what *exactly* I should do to keep it clean.

+ How to write media queries.

What is the status of the official documentation rewrite? Is there any way I can help at the moment? I would like to avoid finding out we have been doing things double.

I guess it would help a lot getting the issue queue down if we could refer to existing documentation.

i can only subscribe (for now)

As far as I've seen, the wiki is always being updated and changed. I would say that you should feel free to add or change anything you see in there.

Subscribing

@Jumoke: There is a button for that!

First off, thank you so much, omega is incredible. +1 for panels integration and usage with omega

I know that there is a section in the current documentation to be written on panels layouts and the omega theme and that omega is very actively integrating support for panels, so I am not intending to restate what's already in the plan, but I would +1 on anything relating to using panels and the omega theme. I think it would be unfortunate if panels users or display suite(uses page manager/panels now) didn't really take a look at omega, which may occur simply because of it's strong connection with the context module. It seems so many see it as an either or, but many use both and even choose differently based on the type of site they are building.

Also, I am not an advanced write from scratch theme builder, just sitebuilder/designer/css, so for myself I do have a question regarding the usage and mixture of panels/display suite and the delta module(with context), and how they could maybe can not successfully work together and maybe some use cases/opinions on when,how, and why they should be used. It is my current understanding(and please correct me if I am wrong) that all the above modules can work together just like panels and context can. Display Suite/Panels is working with things like your node overrides (residing in #section-content) where displaying "block regions" can be turned on and off depending on your needs. Delta and Context can be used alongside display suite/panels for managing your "block regions" (header/footer/sidebars, all or some, whatever you like). Also minipanels can be placed in your "block regions" with context as well. Again, if I am way off base here, please let me know.

Another area regarding panels and omega is the use of html5. What would suggestions be regarding this and panels? There is a feature request in the panels queue "HTML5: Specify Element type on regions and panes" so that html5 tags like <article>, <section>, <aside> can be selected as well as the default div.

Again, thank you so much for all the hard work and all the great documentation you have already.

@Argus, Thank you, thank you thank you : ) I didn't notice that : ) Apologies

I have a list of miscellaneous things that I think could be clarified or added to the doc. I don't see a "todo" list or similar for the doc sprints, so perhaps this is a good place to put it.

1. Some clarifications on this page: Zone / Region Configuration - Where the magic happens!

   • * Provide full width wrapper around this zone

     Enabling this feature will give a wrapper around the zone itself, allowing you to theme in elements that appear outside the 960 pixel container zone.

     Not sure what "theme in elements" means here: does it mean insert elements, or does it mean add CSS for elements that are outside the 960?

   • Customize the region positioning

     This allows you to manipulate the placing of the regions in this zone.

     Turning this on adds a "Position" pulldown to the regions, but I don't know how this differs from "Weight". What does it mean?

2. Disabling content in narrower browsers

   This has been covered in some support requests, but I think could be in the doc: How should one drop regions or blocks as the screen gets smaller? The answer seems to be to make globals.css set up the mobile-sized display, and use display: none in the CSS to make things disappear. Then one must add display: block in the normal and wide to make them reappear. Is this right? This might be explained as part of the style-sheet cascading, but kind of deserves its own heading as well.

@Banghouse, thanks for mentioning. I'm in the Europe - Amsterdam time zone, which is 6 hours ahead of USA -NY, so attending the ICR sessions is a bit difficult. I will try my best to participate in other ways though :)

@jpw1116: A bit late answer on #52, but I'm pretty sure that it was the machine name.

Hehe, "A bit late"... Great you still took the trouble to reply after 4 years. :)