Standardize classnames and layout to facilitate theming

Working notes on standardization of classnames and layout across Moodle activity types, with the intention of making theme design faster and more foolproof.

In order to be sure all bases are covered in standardization, I began with a Survey of existing page views and markup. I'm going to exclude editing screens from this survey because it would just be too much to cover. Additionally, student views should probably be the first priority.

Observations

• We mix & match IDs and classnames a lot in our markup and our selectors. Ideally IDs would be used for items which need efficient selection by JavaScript, and classnames would be used for everything else. Both markup and CSS would be written with that prescription in mind.
  • For example div#intro, which appears on many, many pages, is just static text and will never be the target of JavaScript. Not clear why this needs to be an ID.
• The generalbox class is ubiquitous, and very, very multipurpose.
  • We need a very minimally-styled parent "this is the content" container class. At present .generalbox is used for that on most admin views. But also used for small accentuated alerts and info boxes on other views. standard theme gives generalbox a grey background color. This makes sense for a small accentuated alert, but not for a full page of content (which may contain a small, accentuated alert or other child element with a background color which will there for not show up/make the implied visual impact on the viewer).
  • We should probably look at additional classnames to refine the generalbox according to context. There are some interesting and possibly useful examples of how we might want to do that here: http://twitter.github.com/bootstrap/components.html#alerts
  • The box class appears in the markup on many page views but neither base nor standard theme actually targets .box or uses it as a way to establish basic box attributes. We should standardize with one box model build on one base classname. IMHO generalbox might be a little more self-explanatory than box.
• It's a little strange that there's no renderer for a text within paragraph tags (pls correct me if I'm wrong). Common application seems to be

echo $OUTPUT->container('My text block here'); which isn't really contextual. Who knows what's in that div...

• span#maincontent is misleading. Do we still need it?
• The generaltable class could be more ubiquitous.
  • All tables should use a base table class, then add their own mod-specific class where necessary.
  • The forum uses its own .forumheaderlist for tables. Ideally it has a general table class assigned, then overrides where needed according to an additional class and/or body tag.
• Header usage, especially h2.main, is way higher than it should be.
  • Ideally, we use h2.main only once on a page view, for activity title or other "main" title.
  • .main is not a descriptive classname. It doesn't tell us anything we don't already know from h2 and the body tag.
  • .main also is not reliably used as the top-level header in the page-content. In many views it is applied to every header on the page.
  • On some page views, headers are used for purposes other than headings. We should move away from this. Text that is not a heading but needs emphasis should instead be given emphasis using uniformly-available classnames.
• Moodle page views very frequently have box elements in the content area of varying width. This can look unprofessional, and needs to be overridden on a per-page basis by theme designers. Ideally,
• Moodle standard theme does a lot of centering, and there is a lot of centering built into many of the activity page views.
  • Centering for a single button makes sense, but it is not necessary optimal for headers, notifications, or even tables.
  • There are not many examples, nowadays, of Web sites which center headers on functional pages. There are exceptions, of course, but most of those are Web sites with a higher emphasis on aesthetics than function, and far fewer page elements than Moodle. Of course this is handled by themes, and many Moodle themes do not do this, but we may want to consider this for the standard theme.

Recommendations

Move away from use of IDs as CSS selectors

• IDs are needed for elements which need identification for JavaScript. Elements which do not need to be accessed or manipulated by JavaScript can be identified by classnames.
• Wherever possible, CSS selectors should use classnames over IDs.

Add a paragraph renderer

Add a paragraph renderer. The container() renderer encourages developers to render text that is not appropriately tagged as paragraph text. This would be a simple thing to add. Or if not, at least discourage instructions and other text within bare divs. // similar to the heading renderer heading(); // to replace container() as a default text function to print a block of text paragraph();

.generalbox for text features

Use generalbox only for a box/block of text, not for container of all content in the central column. (In following with purported original purposes of .generalbox, assuming it used to be similar to .generaltable.)

  <!-- If we aren't going to implement a framework, then this will suffice. -->
  <div class="generalbox">
  <!-- If we are going to implement a framework, then, at least with regard to Twitter Bootstrap, .generalbox is analogous to the .well class. 
We might implement them both. -->
  <div class="generalbox well">

Use .maincontent instead of .generalbox to indicate parent of all content in central column

Expand the role="main" container div with a classname so it can take the place of .generalbox as a container of all content in the central column:

  <div role="main" class="maincontent">

Eliminate span.maincontent

Do we still need the following? If not, let's get rid of it. Or if it's just a spacer or some such thing, let's give it a classname such as .maincontent-spacer-top. If it doesn't need access by JavaScript, let's eliminate the ID.

  <span id="maincontent"></span>

Standardize inheritance for tables

The .generaltable instances look nice and are commonly used. But there are some activities where tables are given their own classes entirely, and not given the .generaltable as well. This makes it hard to style all tables with general styles. It's no problem for a mod developer to add additional classnames to target with the mod's own CSS, but the parent classname should be retained.

• The generaltable class could be more ubiquitous.
  • All tables should use a base table class, then add their own mod-specific class where necessary.
  • The forum uses its own .forumheaderlist for tables. Ideally it has a general table class assigned, then overrides where needed according to an additional class and/or body tag.

Header usage should be hierarchical within page views

• Header usage, especially h2.main, is way higher than it should be.
  • Ideally, we use h2.main only once on a page view, for activity title or other "main" title.
  • .main is not a descriptive classname. It doesn't tell us anything we don't already know from h2 and the body tag.
  • .main also is not reliably used as the top-level header in the page-content. In many views it is applied to every header on the page.
  • On some page views, headers are used for purposes other than headings. We should move away from this. Text that is not a heading but needs emphasis should instead be given emphasis using uniformly-available classnames.